openstack/deb-keystone
Code Issues Proposed changes

Update security compliance documentation

Browse Source 
The security compliance settings in the admin guide
referenced configuration options that no longer work.
The functionality to exclude users from password expiry
or password changing was moved to per user resource options.

This change also consolidates the duplicate documentation
between the advanced topics in the operator guide into the
admin-guide.

Closes-Bug: #1701389
Change-Id: I36be658f0a1efb25c55b24596bf67639c69c89d9
This commit is contained in:
Gage Hugo 2017-06-30 09:52:03 -05:00
parent bebd7056ad
commit 55108b2fee
4 changed files with 119 additions and 254 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
doc/source/admin/identity-security-compliance.rst
View File

@ -16,12 +16,12 @@ such as LDAP, should implement their own security controls.
Enable these features by changing the configuration settings under the
``[security_compliance]`` section in ``keystone.conf``.
Setting the account lockout threshold
-------------------------------------
Setting an account lockout threshold
------------------------------------
The account lockout feature limits the number of incorrect password attempts.
If a user fails to authenticate after the maximum number of attempts, the
service disables the user. Re-enable the user by explicitly setting the
service disables the user. Users can be re-enabled by explicitly setting the
enable user attribute with the update user API call, either
`v2.0`_ or `v3`_.
@ -30,20 +30,35 @@ the ``lockout_failure_attempts``:
.. code-block:: ini
[security_compliance]
lockout_failure_attempts = 6
[security_compliance]
lockout_failure_attempts = 6
You set the number of minutes a user would be locked out by setting
the ``lockout_duration`` in seconds:
.. code-block:: ini
[security_compliance]
lockout_duration = 1800
[security_compliance]
lockout_duration = 1800
If you do not set the ``lockout_duration``, users may be locked out
If you do not set the ``lockout_duration``, users will be locked out
indefinitely until the user is explicitly enabled via the API.
You can ensure specific users are never locked out. This can be useful for
service accounts or administrative users. You can do this by setting
``ignore_lockout_failure_attempts`` to ``true`` via a user update API
(``PATCH /v3/users/{user_id}``):
.. code-block:: json
{
"user": {
"options": {
"ignore_lockout_failure_attempts": true
}
}
}
Disabling inactive users
------------------------
@ -53,13 +68,55 @@ within 90 days. You can achieve this by setting the
.. code-block:: ini
[security_compliance]
disable_user_account_days_inactive = 90
[security_compliance]
disable_user_account_days_inactive = 90
This above example means that users that have not authenticated (inactive) for
the past 90 days are automatically disabled. Users can be re-enabled by
explicitly setting the enable user attribute via the API.
Force users to change password upon first use
---------------------------------------------
PCI-DSS 8.2.6 requires users to change their password for first time use and
upon an administrative password reset. Within the identity `user API`_,
`create user` and `update user` are considered administrative password
changes. Whereas, `change password for user` is a self-service password
change. Once this feature is enabled, new users, and users that have had their
password reset, will be required to change their password upon next
authentication (first use), before being able to access any services.
Prior to enabling this feature, you may want to exempt some users that you do
not wish to be required to change their password. You can mark a user as
exempt by setting the user options attribute
``ignore_change_password_upon_first_use`` to ``true`` via a user update API
(``PATCH /v3/users/{user_id}``):
.. code-block:: json
{
"user": {
"options": {
"ignore_change_password_upon_first_use": true
}
}
}
.. WARNING::
Failure to mark service users as exempt from this requirement will result
in your service account passwords becoming expired after being reset.
When ready, you can configure it so that users are forced to change their
password upon first use by setting ``change_password_upon_first_use``:
.. code-block:: ini
[security_compliance]
change_password_upon_first_use = True
.. _`user API`: http://developer.openstack.org/api-ref/identity/v3/index.html#users
Configuring password expiration
-------------------------------
@ -68,8 +125,8 @@ setting the ``password_expires_days``:
.. code-block:: ini
[security_compliance]
password_expires_days = 90
[security_compliance]
password_expires_days = 90
Once set, any new password changes have an expiration date based on the
date/time of the password change plus the number of days defined here. Existing
@ -77,31 +134,37 @@ passwords will not be impacted. If you want existing passwords to have an
expiration date, you would need to run a SQL script against the password table
in the database to update the expires_at column.
In addition, you can set it so that passwords never expire for some users by
adding their user ID to ``password_expires_ignore_user_ids`` list:
If there exists a user whose password you do not want to expire, keystone
supports setting that user's option ``ignore_password_expiry`` to ``true``
via user update API (``PATCH /v3/users/{user_id}``):
.. code-block:: json
{
"user": {
"options": {
"ignore_password_expiry": true
}
}
}
Configuring password strength requirements
------------------------------------------
You can set password strength requirements, such as requiring numbers in
passwords or setting a minimum password length, by adding a regular
expression to the ``password_regex`` setting:
.. code-block:: ini
[security_compliance]
password_expires_ignore_user_ids = [3a54353c9dcc44f690975ea768512f6a]
[security_compliance]
password_regex = ^(?=.*\d)(?=.*[a-zA-Z]).{7,}$
In this example, the password for user ID ``3a54353c9dcc44f690975ea768512f6a``
would never expire.
The above example is a regular expression that requires a password to have:
Indicating password strength requirements
-----------------------------------------
You set password strength requirements, such as requiring numbers in passwords
or setting a minimum password length, by adding a regular expression to the
``password_regex``:
.. code-block:: ini
[security_compliance]
password_regex = ^(?=.*\d)(?=.*[a-zA-Z]).{7,}$
The above example is a regular expression that requires a password to have
one letter, one digit, and a minimum length of seven characters.
* One (1) letter
* One (1) digit
* Minimum length of seven (7) characters
If you do set the ``password_regex``, you should provide text that
describes your password strength requirements. You can do this by setting the
@ -109,20 +172,23 @@ describes your password strength requirements. You can do this by setting the
.. code-block:: ini
[security_compliance]
password_regex_description = Passwords must contain at least 1 letter, 1
digit, and be a minimum length of 7
characters.
[security_compliance]
password_regex_description = Passwords must contain at least 1 letter, 1
digit, and be a minimum length of 7
characters.
The service returns that description to users to explain why their requested
password did not meet requirements.
It is imperative that the ``password_regex_description`` matches the actual
regex. If the ``password_regex`` and the ``password_regex_description`` do
not match, it will cause user experience to suffer since this description
will be returned to users to explain why their requested password was
insufficient.
.. note::
You must ensure the ``password_regex_description`` accurately and
completely describes the ``password_regex``. If the two options are out of
sync, the help text could inaccurately describe the password requirements
being applied to the password. This would lead to poor user experience.
You must ensure the ``password_regex_description`` accurately and
completely describes the ``password_regex``. If the two options are out of
sync, the help text could inaccurately describe the password requirements
being applied to the password. This would lead to a poor user experience.
Requiring a unique password history
-----------------------------------
@ -133,8 +199,8 @@ by setting the ``unique_last_password_count``:
.. code-block:: ini
[security_compliance]
unique_last_password_count= 5
[security_compliance]
unique_last_password_count= 5
The above example does not allow a user to create a new password that is the
same as any of their last four previous passwords.
@ -144,8 +210,8 @@ the user can change it by setting the ``minimum_password_age``:
.. code-block:: ini
[security_compliance]
minimum_password_age = 1
[security_compliance]
minimum_password_age = 1
In the above example, once a user changes their password, they would not be
able to change it again for one day. This prevents users from changing their
@ -154,14 +220,13 @@ old password.
.. note::
When you set ``password_expires_days``, the value for the
``minimum_password_age`` should be less than the ``password_expires_days``.
Otherwise, users would not be able to change their passwords before they
expire.
When you set ``password_expires_days``, the value for the
``minimum_password_age`` should be less than the ``password_expires_days``.
Otherwise, users would not be able to change their passwords before they
expire.
.. _Security Hardening PCI-DSS: https://specs.openstack.org/openstack/keystone-specs/specs/keystone/newton/pci-dss.html
.. _v2.0: https://developer.openstack.org/api-ref/identity/v2-admin/index.html?expanded=update-user-admin-endpoint-detail#update-user-admin-endpoint
.. _v3: https://developer.openstack.org/api-ref/identity/v3/index.html#update-user

4
doc/source/advanced-topics/event_notifications.rst
View File

@ -157,7 +157,9 @@ The reason object will contain the following keys:
* ``reasonType``: Description of the PCI-DSS event
* ``reasonCode``: HTTP response code for the event
For more information, see :doc:`security_compliance` for configuring PCI-DSS in keystone.
For more information, see
:doc:`../admin/identity-security-compliance`
for configuring PCI-DSS in keystone.
Supported Events
----------------

1
doc/source/advanced-topics/index.rst
View File

@ -14,4 +14,3 @@ Advanced Topics
auth-totp.rst
event_notifications.rst
external-auth.rst
security_compliance.rst

201
doc/source/advanced-topics/security_compliance.rst
View File

@ -1,201 +0,0 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy
of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
=============================
Security Compliance & PCI-DSS
=============================
As of the Newton release, keystone added security compliance features,
specifically to satisfy Payment Card Industry - Data Security Standard
(PCI-DSS) v3.1 requirements. See `Security Hardening: PCI-DSS
<https://specs.openstack.org/openstack/keystone-specs/specs/keystone/newton/
pci-dss.html>`_ for more information on PCI-DSS.
Security compliance features are disabled by default and most of the features
only apply to the SQL backend for the identity driver. Other identity backends,
such as LDAP, should implement their own security controls.
These features can be enabled by changing the configuration settings under the
``[security_compliance]`` section in ``keystone.conf``.
Account Lockout Threshold
-------------------------
The account lockout feature limits the number of times a user can attempt to
login with an incorrect password. If a user fails to authenticate after the
maximum number of attempts, the user will be disabled. Users can be re-enabled
by explicitly setting the enable user attribute via the API.
You can set the maximum number of failed authentication attempts by setting
the ``lockout_failure_attempts``:
.. code-block:: ini
[security_compliance]
lockout_failure_attempts = 6
You can then set the number of minutes a user would be locked out by setting
the ``lockout_duration`` in seconds:
.. code-block:: ini
[security_compliance]
lockout_duration = 1800
If the ``lockout_duration`` is not set, then users may be locked out
indefinitely until the user is explicitly enabled via the API.
Finally, you can set it so that some users, such as service users, are never
locked out by setting the user options attribute
``ignore_lockout_failure_attempts`` to ``True`` via a user update API
(``PATCH /v3/users``) call.
Disabling Inactive Users
------------------------
PCI-DSS 8.1.4 requires that inactive user accounts be removed or disabled
within 90 days. You can achieve this by setting the
``disable_user_account_days_inactive``:
.. code-block:: ini
[security_compliance]
disable_user_account_days_inactive = 90
This above example means that users that have not authenticated (inactive) for
the past 90 days will be automatically disabled. Users can be re-enabled by
explicitly setting the enable user attribute via the API.
Force users to immediately change their password upon first use
---------------------------------------------------------------
PCI-DSS 8.2.6 requires users to change their password for first time use and
upon an administrative password reset. Within the identity `user API`_,
`create user` and `update user` are considered administrative password
changes. Whereas, `change password for user` is a self-service password
change. Once this feature is enabled, new users, and users that have had their
password reset, will be required to change their password at the next
authentication (first use), before being able to access any services.
Prior to enabling this feature, you will want to exempt any users, especially
service account users, that you do not wish to be required to change their
password. You can mark a user as exempt by setting the user options attribute
``ignore_change_password_upon_first_use`` to ``True`` via a user update API
(``PATCH /v3/users``) call.
.. WARNING::
Failure to mark service users as exempt from this requirement will result
in your service account passwords becoming expired after being reset.
When ready, you can configure it so that users are forced to change their
password upon first use by setting ``change_password_upon_first_use``:
.. code-block:: ini
[security_compliance]
change_password_upon_first_use = True
.. _`user API`: http://developer.openstack.org/api-ref/identity/v3/index.html#users
Password Expiration
-------------------
Passwords can be configured to expire within a certain number of days by
setting the ``password_expires_days``:
.. code-block:: ini
[security_compliance]
password_expires_days = 90
Once set, any new password changes will have an expiration date based on the
date/time of the password change plus the number of days defined here. Existing
passwords will not be impacted. If you want existing passwords to have an
expiration date, you would need to run a SQL script against the password table
in the database to update the expires_at column.
In addition, you can set it so that passwords never expire for some users by
setting the user options attribute ``ignore_password_expiry`` to ``True`` via
a user update API (``PATCH /v3/users``) call.
Password Strength Requirements
------------------------------
You set password strength requirements, such as requiring numbers in passwords
or setting a minimum password length, by adding a regular expression to the
``password_regex``:
.. code-block:: ini
[security_compliance]
password_regex = ^(?=.*\d)(?=.*[a-zA-Z]).{7,}$
The above is an example of a regular expression that requires 1 letter, 1
digit, and a minimum length of 7 characters.
If you do set the ``password_regex``, you will also want to provide text that
describes your password strength requirements. You can do this by setting the
``password_regex_description``:
.. code-block:: ini
[security_compliance]
password_regex_description = Passwords must contain at least 1 letter, 1
digit, and be a minimum length of 7
characters.
The description will be returned to users to explain why their requested
password was insufficient.
.. NOTE::
It is imperative to ensure the ``password_regex_description`` fully and
completely describes the ``password_regex``. If the two options are out of
sync, the help text may inaccurately describe the password requirements
being applied to the password. This can lead to poor user experience.
Unique Password History
-----------------------
The password history requirements controls the number of passwords for a user
that must be unique before an old password can be reused. You can enforce this
by setting the ``unique_last_password_count``:
.. code-block:: ini
[security_compliance]
unique_last_password_count= 5
The above example will not allow a user to create a new password that is the
same as any of their last 4 previous passwords.
Similarly, you can set the number of days that a password must be used before
the user can change it by setting the ``minimum_password_age``:
.. code-block:: ini
[security_compliance]
minimum_password_age = 1
In the above example, once a user changes their password, they would not be
able to change it again for 1 day. This prevents users from changing their
passwords immediately in order to wipe out their password history and reuse an
old password.
.. NOTE::
If ``password_expires_days`` is set, then the value for the
``minimum_password_age`` should be less than the ``password_expires_days``.
Otherwise, users would not be able to change their passwords before they
expire.