diff --git a/doc/source/authentication.rst b/doc/source/authentication.rst index e9ce451ec5..8f3acf4b5c 100644 --- a/doc/source/authentication.rst +++ b/doc/source/authentication.rst @@ -84,6 +84,117 @@ The final step is to verify that the `OS_AUTH_` crednetials are present:: OS_AUTH_URL= 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 -------------------------- diff --git a/etc/glance-api.conf b/etc/glance-api.conf index a8328d4f73..f2bec54334 100644 --- a/etc/glance-api.conf +++ b/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 diff --git a/etc/glance-registry.conf b/etc/glance-registry.conf index 79d02a32f1..481351c1c8 100644 --- a/etc/glance-registry.conf +++ b/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