Merge "Update security compliance documentation"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
2fd8b52b7f
@ -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`_.
|
||||
|
||||
@ -41,9 +41,24 @@ the ``lockout_duration`` in seconds:
|
||||
[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
|
||||
------------------------
|
||||
|
||||
@ -60,6 +75,48 @@ 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
|
||||
-------------------------------
|
||||
|
||||
@ -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:: ini
|
||||
.. code-block:: json
|
||||
|
||||
[security_compliance]
|
||||
password_expires_ignore_user_ids = [3a54353c9dcc44f690975ea768512f6a]
|
||||
{
|
||||
"user": {
|
||||
"options": {
|
||||
"ignore_password_expiry": true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
In this example, the password for user ID ``3a54353c9dcc44f690975ea768512f6a``
|
||||
would never expire.
|
||||
Configuring password strength requirements
|
||||
------------------------------------------
|
||||
|
||||
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``:
|
||||
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_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.
|
||||
The above example is a regular expression that requires a password to have:
|
||||
|
||||
* 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
|
||||
@ -114,15 +177,18 @@ describes your password strength requirements. You can do this by setting the
|
||||
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.
|
||||
being applied to the password. This would lead to a poor user experience.
|
||||
|
||||
Requiring a unique password history
|
||||
-----------------------------------
|
||||
@ -161,7 +227,6 @@ old password.
|
||||
|
||||
.. _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
|
||||
|
||||
@ -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
|
||||
----------------
|
||||
|
||||
@ -14,4 +14,3 @@ Advanced Topics
|
||||
auth-totp.rst
|
||||
event_notifications.rst
|
||||
external-auth.rst
|
||||
security_compliance.rst
|
||||
|
||||
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user