1 files changed, 86 insertions, 5 deletions
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index 03fa1d63..1c339490 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -74,11 +74,12 @@ following sections:
 * ``[s3]`` - Amazon S3 authentication driver configuration.
 * ``[identity]`` - identity system driver configuration
 * ``[catalog]`` - service catalog driver configuration
-* ``[token]`` - token driver configuration
+* ``[token]`` - token driver & token provider configuration
 * ``[policy]`` - policy system driver configuration for RBAC
 * ``[signing]`` - cryptographic signatures for PKI based tokens
 * ``[ssl]`` - SSL configuration
 * ``[auth]`` - Authentication plugin configuration
+* ``[os_inherit]`` - Inherited Role Assignment extension
 * ``[paste_deploy]`` - Pointer to the PasteDeploy configuration file
 
 The Keystone primary configuration file is expected to be named ``keystone.conf``.
@@ -106,7 +107,10 @@ file. It is up to the plugin to register its own configuration options.
 * ``methods`` - comma-delimited list of authentication plugin names
 * ``<plugin name>`` - specify the class which handles to authentication method, in the same manner as one would specify a backend driver.
 
-Keystone provides two authentication methods by default. ``password`` handles password authentication and ``token`` handles token authentication.
+Keystone provides three authentication methods by default. ``password`` handles password
+authentication and ``token`` handles token authentication.  ``external`` is used in conjunction
+with authentication performed by a container web server that sets the ``REMOTE_USER``
+environment variable.
 
 How to Implement an Authentication Plugin
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -148,6 +152,32 @@ invoked, all plugins must succeed in order to for the entire
 authentication to be successful. Furthermore, all the plugins invoked must
 agree on the ``user_id`` in the ``auth_context``.
 
+The ``REMOTE_USER`` environment variable is only set from a containing webserver.  However,
+to ensure that a user must go through other authentication mechanisms, even if this variable
+is set, remove ``external`` from the list of plugins specified in ``methods``.  This effectively
+disables external authentication.
+
+
+Token Provider
+--------------
+
+Keystone supports customizable token provider and it is specified in the
+``[token]`` section of the configuration file. Keystone provides both UUID and
+PKI token providers, with PKI token provider enabled as default. However, users
+may register their own token provider by configuring the following property.
+
+* ``provider`` - token provider driver. Defaults to
+  ``keystone.token.providers.pki.Provider``
+
+Note that ``token_format`` in the ``[signing]`` section is deprecated but still
+being supported for backward compatibility. Therefore, if ``provider`` is set
+to ``keystone.token.providers.pki.Provider``, ``token_format`` must be ``PKI``.
+Conversely, if ``provider`` is ``keystone.token.providers.uuid.Provider``,
+``token_format`` must be ``UUID``.
+
+For a customized provider, ``token_format`` must not set to ``PKI`` or
+``UUID``.
+
 Certificates for PKI
 --------------------
 
@@ -163,7 +193,9 @@ private key should only be readable by the system user that will run Keystone.
 The values that specify where to read the certificates are under the
 ``[signing]`` section of the configuration file.  The configuration values are:
 
-* ``token_format`` - Determines the algorithm used to generate tokens.  Can be either ``UUID`` or ``PKI``. Defaults to ``PKI``
+* ``token_format`` - Determines the algorithm used to generate tokens.  Can be
+  either ``UUID`` or ``PKI``. Defaults to ``PKI``. This option must be used in
+  conjunction with ``provider`` configuration in the ``[token]`` section.
 * ``certfile`` - Location of certificate used to verify tokens.  Default is ``/etc/keystone/ssl/certs/signing_cert.pem``
 * ``keyfile`` - Location of private key used to sign tokens.  Default is ``/etc/keystone/ssl/private/signing_key.pem``
 * ``ca_certs`` - Location of certificate for the authority that issued the above certificate. Default is ``/etc/keystone/ssl/certs/ca.pem``
@@ -460,7 +492,56 @@ Each user can then change their own password with a HTTP PATCH ::
     -H "X_Auth_Token: <authtokenid>" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}'
 
 In addition to changing their password all of the users current tokens will be
-deleted (if the backend used is kvs or sql)
+deleted (if the backend used is sql)
+
+
+Inherited Role Assignment Extension
+-----------------------------------
+
+Keystone provides an optional extension that adds the capability to assign roles to a domain that, rather than
+affect the domain itself, are instead inherited to all projects owned by theat domain.  This extension is disabled by
+default, but can be enabled by including the following in ``keystone.conf``.
+
+    [os_inherit]
+    enabled = True
+
+
+Token Binding
+-------------
+
+Token binding refers to the practice of embedding information from external
+authentication providers (like a company's Kerberos server) inside the token
+such that a client may enforce that the token only be used in conjunction with
+that specified authentication. This is an additional security mechanism as it
+means that if a token is stolen it will not be usable without also providing the
+external authentication.
+
+To activate token binding you must specify the types of authentication that
+token binding should be used for in ``keystone.conf`` e.g.::
+
+    [token]
+    bind = kerberos
+
+Currently only ``kerberos`` is supported.
+
+To enforce checking of token binding the ``enforce_token_bind`` parameter
+should be set to one of the following modes:
+
+* ``disabled`` disable token bind checking
+* ``permissive`` enable bind checking, if a token is bound to a mechanism that
+  is unknown to the server then ignore it. This is the default.
+* ``strict`` enable bind checking, if a token is bound to a mechanism that is
+  unknown to the server then this token should be rejected.
+* ``required`` enable bind checking and require that at least 1 bind mechanism
+  is used for tokens.
+* named enable bind checking and require that the specified authentication
+  mechanism is used. e.g.::
+
+    [token]
+    enforce_token_bind = kerberos
+
+  *Do not* set ``enforce_token_bind = named`` as there is not an authentication
+  mechanism called ``named``.
 
 
 Sample Configuration Files
@@ -1079,7 +1160,7 @@ if the backend is providing too much output, in such case the configuration
 will look like::
 
   [ldap]
-  user_filter = (memberof=CN=openstack-users,OU=workgroups,DC=openstack,DC=com)
+  user_filter = (memberof=CN=openstack-users,OU=workgroups,DC=openstack,DC=org)
   tenant_filter =
   role_filter =