diff --git a/doc/source/overview_auth.rst b/doc/source/overview_auth.rst index 2bb00d73c8..3b631692d8 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 +`_, +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -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`. +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 `, 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`` (``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 d342084ea5..46a8367b53 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 : in container Access Control Lists (ACLs). For - a request to be granted by an ACL, must match the UUID of the - tenant to which the request token is scoped and must match the - UUID of the user authenticated by the request token. + the syntax ``:`` to specify a grantee in container Access + Control Lists (ACLs). For a request to be granted by an ACL, the grantee + ```` must match the UUID of the tenant to which the request + token is scoped and the grantee ```` 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