Update documentation for using keystone auth

Cleanup and add clarification to the documentation
for using Keystone auth.

Update to refer to auth_token middleware being
distributed as part of the keystomemiddelware project
rather than keystone.

Include capabilities (/info) in the list of reasons
why delay_auth_decision might need to be set in
auth_token middleware config.

Add description of the project_id:user_id format
for container ACLs and emphasize that ids rather than
names should be used since this patch has now merged:
https://review.openstack.org/#/c/86430

DocImpact
blueprint keystone-v3-support
Change-Id: Idda4a3dcf8240474f1d2d163016ca2d40ec2d589

2 files changed, 79 insertions, 38 deletions

diff --git a/doc/source/overview_auth.rst b/doc/source/overview_auth.rst
index 2bb00d73c..3b631692d 100644
--- a/doc/source/overview_auth.rst
+++ b/doc/source/overview_auth.rst
@@ -109,29 +109,33 @@ receive the auth token and a URL to the Swift system.
 Keystone Auth
 -------------
 
-Swift is able to authenticate against OpenStack keystone via the
-:mod:`swift.common.middleware.keystoneauth` middleware.
+Swift is able to authenticate against OpenStack Keystone_ via the
+:ref:`keystoneauth` middleware.
 
-In order to use the ``keystoneauth`` middleware the ``authtoken``
-middleware from keystonemiddleware will need to be configured.
+In order to use the ``keystoneauth`` middleware the ``auth_token``
+middleware from KeystoneMiddleware_ will need to be configured.
 
 The ``authtoken`` middleware performs the authentication token
 validation and retrieves actual user authentication information. It
-can be found in the keystonemiddleware distribution.
+can be found in the KeystoneMiddleware_ distribution.
 
-The ``keystoneauth`` middleware performs authorization and mapping the
-``keystone`` roles to Swift's ACLs.
+The :ref:`keystoneauth` middleware performs authorization and mapping the
+Keystone roles to Swift's ACLs.
+
+.. _KeystoneMiddleware: http://docs.openstack.org/developer/keystonemiddleware/
+.. _Keystone: http://docs.openstack.org/developer/keystone/
 
 Configuring Swift to use Keystone
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Configuring Swift to use Keystone is relatively straight
-forward.  The first step is to ensure that you have the auth_token
-middleware installed, distributed with keystone it can either be
-dropped in your python path or installed via the keystone package.
+Configuring Swift to use Keystone_
+is relatively straight forward.  The first
+step is to ensure that you have the ``auth_token`` middleware installed. It can
+either be dropped in your python path or installed via the KeystoneMiddleware_
+package.
 
 You need at first make sure you have a service endpoint of type
-``object-store`` in keystone pointing to your Swift proxy. For example
+``object-store`` in Keystone pointing to your Swift proxy. For example
 having this in your ``/etc/keystone/default_catalog.templates`` ::
 
   catalog.RegionOne.object_store.name = Swift Service
@@ -161,8 +165,10 @@ add the configuration for the authtoken middleware::
   include_service_catalog = False
 
 The actual values for these variables will need to be set depending on
-your situation.  For more information, please refer to the Keystone
-documentation on the ``auth_token`` middleware, but in short:
+your situation.  For more information, please refer to the `Keystone
+auth_token middleware documentation
+<http://docs.openstack.org/developer/keystonemiddleware/middlewarearchitecture.html#configuration>`_,
+but in short:
 
 * Those variables beginning with ``auth_`` point to the Keystone
   Admin service.  This information is used by the middleware to actually
@@ -171,20 +177,23 @@ documentation on the ``auth_token`` middleware, but in short:
 * The admin auth credentials (``admin_user``, ``admin_tenant_name``,
   ``admin_password``) will be used to retrieve an admin token. That
   token will be used to authorize user tokens behind the scenes.
-* cache is set to ``swift.cache``. This means that the middleware
+* ``cache`` is set to ``swift.cache``. This means that the middleware
   will get the Swift memcache from the request environment.
-* include_service_catalog defaults to True if not set. This means
+* ``include_service_catalog`` defaults to ``True`` if not set. This means
   that when validating a token, the service catalog is retrieved
-  and stored in the X-Service-Catalog header. Since Swift does not
-  use the X-Service-Catalog header, there is no point in getting
-  the service catalog. We recommend you set include_service_catalog
-  to False.
+  and stored in the ``X-Service-Catalog`` header. Since Swift does not
+  use the ``X-Service-Catalog`` header, there is no point in getting
+  the service catalog. We recommend you set ``include_service_catalog``
+  to ``False``.
+* If you wish to authenticate using Keystone's v3 API you must set the
+  ``auth_version`` option to ``v3.0``.
 
 
 .. note::
 
     If support is required for unvalidated users (as with anonymous
-    access) or for tempurl/formpost middleware, authtoken will need
+    access or making capabilities requests using :ref:`discoverability`) or
+    for tempurl/formpost middleware, authtoken will need
     to be configured with delay_auth_decision set to 1.
 
 and you can finally add the keystoneauth configuration::
@@ -193,13 +202,40 @@ and you can finally add the keystoneauth configuration::
   use = egg:swift#keystoneauth
   operator_roles = admin, swiftoperator
 
-By default the only users able to give ACL or to Create other
-containers are the ones who has the Keystone role specified in the
-``operator_roles`` setting.
+Access control using keystoneauth
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default the only users able to perform operations (e.g. create a container)
+on an account are those having a Keystone role for the corresponding Keystone
+project that matches one of the roles specified in the ``operator_roles``
+option.
+
+Users who have one of the ``operator_roles`` will be able to set container ACLs
+to grant other users permission to read and/or write objects in specific
+containers, using ``X-Container-Read`` and ``X-Container-Write`` headers
+respectively. In addition to the ACL formats described
+:mod:`here <swift.common.middleware.acl>`, keystoneauth supports ACLs using the
+format::
+
+ other_project_id:other_user_id.
+
+where ``other_project_id`` is the UUID of a Keystone project and
+``other_user_id`` is the UUID of a Keystone user. This will allow the other
+user to access a container provided their token is scoped on the other
+project. Both ``other_project_id`` and ``other_user_id`` may be replaced with
+the wildcard character ``*`` which will match any project or user respectively.
+
+Be sure to use Keystone UUIDs rather than names in container ACLs.
+
+.. note::
+
+    For backwards compatibility, keystoneauth will by default grant container
+    ACLs expressed as ``other_project_name:other_user_name`` (i.e. using
+    Keystone names rather than UUIDs) in the special case when both the other
+    project and the other user are in Keystone's default domain and the project
+    being accessed is also in the default domain.
 
-This user who have one of those role will be able to give ACLs to
-other users on containers, see the documentation on ACL here
-:mod:`swift.common.middleware.acl`.
+    For further information see :ref:`keystoneauth`
 
 Users with the Keystone role defined in ``reseller_admin_role``
 (``ResellerAdmin`` by default) can operate on any account. The auth system
diff --git a/swift/common/middleware/keystoneauth.py b/swift/common/middleware/keystoneauth.py
index d342084ea..46a8367b5 100644
--- a/swift/common/middleware/keystoneauth.py
+++ b/swift/common/middleware/keystoneauth.py
@@ -79,20 +79,25 @@ class KeystoneAuth(object):
         reseller_prefix = NEWAUTH
 
     The keystoneauth middleware supports cross-tenant access control using
-    the syntax <tenant>:<user> in container Access Control Lists (ACLs). For
-    a request to be granted by an ACL, <tenant> must match the UUID of the
-    tenant to which the request token is scoped and <user> must match the
-    UUID of the user authenticated by the request token.
+    the syntax ``<tenant>:<user>`` to specify a grantee in container Access
+    Control Lists (ACLs). For a request to be granted by an ACL, the grantee
+    ``<tenant>`` must match the UUID of the tenant to which the request
+    token is scoped and the grantee ``<user>`` must match the UUID of the
+    user authenticated by the request token.
 
     Note that names must no longer be used in cross-tenant ACLs because with
     the introduction of domains in keystone names are no longer globally
-    unique. For backwards compatibility, ACLs using names will be granted by
-    keystoneauth when it can be established that both the grantee and the
-    tenant being accessed are either not yet in a domain (e.g. the request
-    token has been obtained via the keystone v2 API) or are both in the
-    default domain to which legacy accounts would have been migrated. The id
-    of the default domain is specified by the config option
-    ``default_domain_id``:
+    unique.
+
+    For backwards compatibility, ACLs using names will be granted by
+    keystoneauth when it can be established that the grantee tenant,
+    the grantee user and the tenant being accessed are either not yet in a
+    domain (e.g. the request token has been obtained via the keystone v2
+    API) or are all in the default domain to which legacy accounts would
+    have been migrated. The default domain is identified by its UUID,
+    which by default has the value ``default``. This can be changed by
+    setting the ``default_domain_id`` option in the keystoneauth
+    configuration::
 
         default_domain_id = default