Add PCI docs to identity admin guide

This is a straight copy of the end-user focused docs that keystone
has in their developer docs [1].

[1] http://docs.openstack.org/developer/keystone/security_compliance.html

Change-Id: I38afb0eedacf048d8529a30eca451660b52b99ea

doc/admin-guide/source/identity-management.rst

@@ -24,6 +24,7 @@ command-line client.
    identity-fernet-token-faq.rst
    identity-use-trusts.rst
    identity-caching-layer.rst
+   identity-security-compliance.rst
    identity-keystone-usage-and-features.rst
    identity-auth-token-middleware.rst
    identity-service-api-protection.rst

doc/admin-guide/source/identity-security-compliance.rst

@@ -0,0 +1,167 @@
+.. _identity_security_compliance:
+
+===============================
+Security compliance and PCI-DSS
+===============================
+
+As of the Newton release, the Identity service contains additional security
+compliance features, specifically to satisfy Payment Card Industry -
+Data Security Standard (PCI-DSS) v3.1 requirements. See
+`Security Hardening PCI-DSS`_ 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.
+
+Enable these features by changing the configuration settings under the
+``[security_compliance]`` section in ``keystone.conf``.
+
+Setting the 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
+enable user attribute with the update user API call, either
+`v2.0`_ or `v3`_.
+
+You set the maximum number of failed authentication attempts by setting
+the ``lockout_failure_attempts``:
+
+.. code-block:: ini
+
+    [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
+
+If you do not set the ``lockout_duration``, users may be locked out
+indefinitely until the user is explicitly enabled via the API.
+
+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 are automatically disabled. Users can be re-enabled by
+explicitly setting the enable user attribute via the API.
+
+Configuring 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 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
+adding their user ID to ``password_expires_ignore_user_ids`` list:
+
+.. code-block:: ini
+
+    [security_compliance]
+    password_expires_ignore_user_ids = [3a54353c9dcc44f690975ea768512f6a]
+
+In this example, the password for user ID ``3a54353c9dcc44f690975ea768512f6a``
+would never expire.
+
+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.
+
+If you do set the ``password_regex``, you should 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 service returns that description to users to explain why their requested
+password did not meet requirements.
+
+.. 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.
+
+Requiring a 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 does not allow a user to create a new password that is the
+same as any of their last four 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 one day. This prevents users from changing their
+passwords immediately in order to wipe out their password history and reuse an
+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.
+
+.. _Security Hardening PCI-DSS: http://specs.openstack.org/openstack/keystone-specs/specs/keystone/newton/pci-dss.html
+
+
+.. _v2.0: http://developer.openstack.org/api-ref/identity/v2-admin/index.html?expanded=update-user-admin-endpoint-detail#update-user-admin-endpoint
+
+.. _v3: http://developer.openstack.org/api-ref/identity/v3/index.html#update-user