openstack/swift
Code Issues Proposed changes

Update documentation for using keystone auth

Browse Source 
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
This commit is contained in:
Alistair Coles 2014-09-10 16:09:13 +01:00
parent 423ac74e88
commit 49fa5b8fb4
2 changed files with 79 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
doc/source/overview_auth.rst
View File

@ -109,29 +109,33 @@ receive the auth token and a URL to the Swift system.
Keystone Auth Keystone Auth
------------- -------------
Swift is able to authenticate against OpenStack keystone via the Swift is able to authenticate against OpenStack Keystone_ via the
:mod:`swift.common.middleware.keystoneauth` middleware. :ref:`keystoneauth` middleware.
In order to use the ``keystoneauth`` middleware the ``authtoken`` In order to use the ``keystoneauth`` middleware the ``auth_token``
middleware from keystonemiddleware will need to be configured. middleware from KeystoneMiddleware_ will need to be configured.
The ``authtoken`` middleware performs the authentication token The ``authtoken`` middleware performs the authentication token
validation and retrieves actual user authentication information. It 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 The :ref:`keystoneauth` middleware performs authorization and mapping the
``keystone`` roles to Swift's ACLs. 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuring Swift to use Keystone is relatively straight Configuring Swift to use Keystone_
forward. The first step is to ensure that you have the auth_token is relatively straight forward. The first
middleware installed, distributed with keystone it can either be step is to ensure that you have the ``auth_token`` middleware installed. It can
dropped in your python path or installed via the keystone package. 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 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`` :: having this in your ``/etc/keystone/default_catalog.templates`` ::
catalog.RegionOne.object_store.name = Swift Service catalog.RegionOne.object_store.name = Swift Service
@ -161,8 +165,10 @@ add the configuration for the authtoken middleware::
include_service_catalog = False include_service_catalog = False
The actual values for these variables will need to be set depending on The actual values for these variables will need to be set depending on
your situation. For more information, please refer to the Keystone your situation. For more information, please refer to the `Keystone
documentation on the ``auth_token`` middleware, but in short: 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 * Those variables beginning with ``auth_`` point to the Keystone
Admin service. This information is used by the middleware to actually 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``, * The admin auth credentials (``admin_user``, ``admin_tenant_name``,
``admin_password``) will be used to retrieve an admin token. That ``admin_password``) will be used to retrieve an admin token. That
token will be used to authorize user tokens behind the scenes. 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. 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 that when validating a token, the service catalog is retrieved
and stored in the X-Service-Catalog header. Since Swift does not and stored in the ``X-Service-Catalog`` header. Since Swift does not
use the X-Service-Catalog header, there is no point in getting use the ``X-Service-Catalog`` header, there is no point in getting
the service catalog. We recommend you set include_service_catalog the service catalog. We recommend you set ``include_service_catalog``
to False. to ``False``.
* If you wish to authenticate using Keystone's v3 API you must set the
``auth_version`` option to ``v3.0``.
.. note:: .. note::
If support is required for unvalidated users (as with anonymous 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. to be configured with delay_auth_decision set to 1.
and you can finally add the keystoneauth configuration:: and you can finally add the keystoneauth configuration::
@ -193,13 +202,40 @@ and you can finally add the keystoneauth configuration::
use = egg:swift#keystoneauth use = egg:swift#keystoneauth
operator_roles = admin, swiftoperator operator_roles = admin, swiftoperator
By default the only users able to give ACL or to Create other Access control using keystoneauth
containers are the ones who has the Keystone role specified in the ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``operator_roles`` setting.
This user who have one of those role will be able to give ACLs to By default the only users able to perform operations (e.g. create a container)
other users on containers, see the documentation on ACL here on an account are those having a Keystone role for the corresponding Keystone
:mod:`swift.common.middleware.acl`. 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.
For further information see :ref:`keystoneauth`
Users with the Keystone role defined in ``reseller_admin_role`` Users with the Keystone role defined in ``reseller_admin_role``
(``ResellerAdmin`` by default) can operate on any account. The auth system (``ResellerAdmin`` by default) can operate on any account. The auth system

27
swift/common/middleware/keystoneauth.py
View File

@ -79,20 +79,25 @@ class KeystoneAuth(object):
reseller_prefix = NEWAUTH reseller_prefix = NEWAUTH
The keystoneauth middleware supports cross-tenant access control using The keystoneauth middleware supports cross-tenant access control using
the syntax <tenant>:<user> in container Access Control Lists (ACLs). For the syntax ``<tenant>:<user>`` to specify a grantee in container Access
a request to be granted by an ACL, <tenant> must match the UUID of the Control Lists (ACLs). For a request to be granted by an ACL, the grantee
tenant to which the request token is scoped and <user> must match the ``<tenant>`` must match the UUID of the tenant to which the request
UUID of the user authenticated by the request token. 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 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 the introduction of domains in keystone names are no longer globally
unique. For backwards compatibility, ACLs using names will be granted by unique.
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 For backwards compatibility, ACLs using names will be granted by
token has been obtained via the keystone v2 API) or are both in the keystoneauth when it can be established that the grantee tenant,
default domain to which legacy accounts would have been migrated. The id the grantee user and the tenant being accessed are either not yet in a
of the default domain is specified by the config option domain (e.g. the request token has been obtained via the keystone v2
``default_domain_id``: 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 default_domain_id = default