Better document using Glance with Keystone.

Addresses bug 871803 by expounding on what configuration should
look like.  Also fixes the example config files, which generally
had the authentication setup completely wrong.

Change-Id: I44b2b8bd340ca95b5a2c2e9408797b0308000a65

doc/source/authentication.rst

@@ -84,6 +84,117 @@ The final step is to verify that the `OS_AUTH_` crednetials are present::
   OS_AUTH_URL=<THIS SHOULD POINT TO KEYSTONE>
   OS_AUTH_STRATEGY=keystone
 
+Configuring the Glance servers to use Keystone
+----------------------------------------------
+
+Keystone is integrated with Glance through the use of middleware.  The
+default configuration files for both the Glance API and the Glance
+Registry use a single piece of middleware called ``context``, which
+generates a request context without any knowledge of Keystone.  In
+order to configure Glance to use Keystone, this ``context`` middleware
+must be replaced with two other pieces of middleware: the
+``authtoken`` middleware and the ``auth-context`` middleware, both of
+which may be found in the Keystone distribution.  The ``authtoken``
+middleware performs the Keystone token validation, which is the heart
+of Keystone authentication.  On the other hand, the ``auth-context``
+middleware performs the necessary tie-in between Keystone and Glance;
+it is the component which replaces the ``context`` middleware that
+Glance uses by default.
+
+One other important concept to keep in mind is the *request context*.
+In the default Glance configuration, the ``context`` middleware sets
+up a basic request context; configuring Glance to use
+``auth_context`` causes a more advanced context to be configured.  It
+is also important to note that the Glance API and the Glance Registry
+use two different context classes; this is because the registry needs
+advanced methods that are not available in the default context class.
+The implications of this will be obvious in the below example for
+configuring the Glance Registry.
+
+Configuring Glance API to use Keystone
+--------------------------------------
+
+Configuring Glance API to use Keystone is relatively straight
+forward.  The first step is to ensure that declarations for the two
+pieces of middleware exist.  Here is an example for ``authtoken``::
+
+  [filter:authtoken]
+  paste.filter_factory = keystone.middleware.auth_token:filter_factory
+  service_protocol = http
+  service_host = 127.0.0.1
+  service_port = 5000
+  auth_host = 127.0.0.1
+  auth_port = 5001
+  auth_protocol = http
+  auth_uri = http://127.0.0.1:5000/
+  admin_token = 999888777666
+
+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 ``service_`` are only needed if you
+  are using a proxy; they define the actual location of Glance.  That
+  said, they must be present.
+* Except for ``auth_uri``, 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 ``auth_uri`` variable must point to the Keystone Auth service,
+  which is the service users use to obtain Keystone tokens.  If the
+  user does not have a valid Keystone token, they will be redirected
+  to this URI to obtain one.
+* The ``admin_token`` variable specifies the administrative token that
+  Glance uses in its query to the Keystone Admin service.
+
+The other piece of middleware needed for Glance API is the
+``auth-context``::
+
+  [filter:auth_context]
+  paste.filter_factory = keystone.middleware.glance_auth_token:filter_factory
+
+Finally, to actually enable using Keystone authentication, the
+application pipeline must be modified.  By default, it looks like::
+
+  [pipeline:glance-api]
+  pipeline = versionnegotiation context apiv1app
+
+(Your particular pipeline may vary depending on other options, such as
+the image cache.)  This must be changed by replacing ``context`` with
+``authtoken`` and ``auth-context``::
+
+  [pipeline:glance-api]
+  pipeline = versionnegotiation authtoken auth-context apiv1app
+
+Configuring Glance Registry to use Keystone
+-------------------------------------------
+
+Configuring Glance Registry to use Keystone is also relatively
+straight forward.  The same pieces of middleware need to be added as
+are needed by Glance API; see above for an example of the
+``authtoken`` configuration.  There is a slight difference for the
+``auth-context`` middleware, which should look like this::
+
+  [filter:auth-context]
+  context_class = glance.registry.context.RequestContext
+  paste.filter_factory = keystone.middleware.glance_auth_token:filter_factory
+
+The ``context_class`` variable is needed to specify the
+Registry-specific request context, which contains the extra access
+checks used by the Registry.
+
+Again, to enable using Keystone authentication, the application
+pipeline must be modified.  By default, it looks like:
+
+  [pipeline:glance-registry]
+  pipeline = context registryapp
+
+This must be changed by replacing ``context`` with ``authtoken`` and
+``auth-context``::
+
+  [pipeline:glance-registry]
+  pipeline = authtoken auth-context registryapp
+
 Sharing Images With Others
 --------------------------
 

etc/glance-api.conf

@@ -159,12 +159,12 @@ scrubber_datadir = /var/lib/glance/scrubber
 [pipeline:glance-api]
 pipeline = versionnegotiation context apiv1app
 # NOTE: use the following pipeline for keystone
-# pipeline = versionnegotiation authtoken context apiv1app
+# pipeline = versionnegotiation authtoken auth-context apiv1app
 
 # To enable Image Cache Management API replace pipeline with below:
 # pipeline = versionnegotiation context imagecache apiv1app
 # NOTE: use the following pipeline for keystone auth (with caching)
-# pipeline = versionnegotiation authtoken context imagecache apiv1app
+# pipeline = versionnegotiation authtoken auth-context imagecache apiv1app
 
 [pipeline:versions]
 pipeline = versionsapp
@@ -194,3 +194,6 @@ auth_port = 5001
 auth_protocol = http
 auth_uri = http://127.0.0.1:5000/
 admin_token = 999888777666
+
+[filter:auth-context]
+paste.filter_factory = keystone.middleware.glance_auth_token:filter_factory

etc/glance-registry.conf

@@ -43,7 +43,7 @@ limit_param_default = 25
 [pipeline:glance-registry]
 pipeline = context registryapp
 # NOTE: use the following pipeline for keystone
-# pipeline = authtoken keystone_shim context registryapp
+# pipeline = authtoken auth-context registryapp
 
 [app:registryapp]
 paste.app_factory = glance.registry.api.v1:app_factory
@@ -63,5 +63,6 @@ auth_protocol = http
 auth_uri = http://127.0.0.1:5000/
 admin_token = 999888777666
 
-[filter:keystone_shim]
+[filter:auth-context]
+context_class = glance.registry.context.RequestContext
 paste.filter_factory = keystone.middleware.glance_auth_token:filter_factory