Move swift_auth middleware from keystone to swift.

- Rename it to keystoneauth for consistenties.
- Implements blueprint keystone-middleware.

Change-Id: I208fecdf3ee991694b4239f065032324d297fd35

doc/source/overview_auth.rst

@@ -42,6 +42,91 @@ such as the X-Container-Sync-Key for a container GET or HEAD.
 The user starts a session by sending a ReST request to the auth system to
 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.
+
+In order to use the ``keystoneauth`` middleware the ``authtoken``
+middleware from keystone 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 Keystone distribution.
+
+The ``keystoneauth`` middleware performs authorization and mapping the
+``keystone`` roles to Swift's ACLs.
+
+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.
+
+You need at first make sure you have a service endpoint of type
+``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
+  catalog.RegionOne.object_store.publicURL = http://swiftproxy:8080/v1/AUTH_$(tenant_id)s
+  catalog.RegionOne.object_store.adminURL = http://swiftproxy:8080/
+  catalog.RegionOne.object_store.internalURL = http://swiftproxy:8080/v1/AUTH_$(tenant_id)s
+
+On your Swift Proxy server you will want to adjust your main pipeline
+and add auth_token and keystoneauth in your
+``/etc/swift/proxy-server.conf`` like this ::
+
+  [pipeline:main]
+  pipeline = [....] authtoken keystoneauth proxy-logging proxy-server
+
+add the configuration for the authtoken middleware::
+
+  [filter:authtoken]
+  paste.filter_factory = keystone.middleware.auth_token:filter_factory
+  auth_host = keystonehost
+  auth_port = 35357
+  auth_protocol = http
+  auth_uri = http://keystonehost:5000/
+  admin_tenant_name = service
+  admin_user = swift
+  admin_password = password
+
+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:
+
+* Those variables beginning with ``auth_`` point to the Keystone
+  Admin service.  This information is used by the middleware to actually
+  query Keystone about the validity of the
+  authentication tokens.
+* 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.
+
+.. note::
+
+    If support is required for unvalidated users (as with anonymous
+    access) 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::
+
+  [filter:keystoneauth]
+  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.
+
+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`.
+
 --------------
 Extending Auth
 --------------