Merge "Better document using Glance with Keystone."

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