Stand alone service catalog

bp get-catalog

This spec introduces a stand alone v3 API request to fetch an authenticated service catalog, for use with tokens that do not contain a catalog (those produced using the ?nocatalog query parameter).

Problem Description

PKI tokens are large, even when compression is applied, largely due to the size of the service catalog that can be included. One way to address the issue is for the client to request tokens on Identity API v3 using the ?nocatalog query parameter, which removes the service catalog from the token itself. Unfortunately, this then breaks clients and services that expect a service catalog to appear in the token.

Proposed Change

On the service-side, we need an explicit API call to retrieve an authenticated service catalog, such as GET /v3/auth/catalog. This would return the exact contents of a token’s catalog object, with no modification other than perhaps links, as is convention in the Identity v3 API. The goal is that the object should be usable by all existing clients of the v3 service catalog.

python-keystoneclient must be able to make the new API call (perhaps lazily) when the catalog is accessed.

keystonemiddleware.auth_token must be able to make the new API call to populate the X-Service-Catalog header if a token does not contain a catalog.


Token response bodies could also contain a service catalog that is not encoded into the PKI token. While this provides a solution for end users, the downside of this option is that services are still left with tokens lacking a catalog, and have no means to retrieve one.

Security Impact

While this introduces a new authenticated API resource, it does not expose any data that would have been previously hidden from end users.

It’s worth noting that the contents of the service-side catalog could change after the token was issued. Remote services should therefore not expect a static catalog for a given token, nor use the stand alone service catalog as a means of authorization.

Notifications Impact


Other End User Impact

This will enable end users to obtain a service catalog using v3 tokens that were generated without a service catalog.

Both python-keystoneclient and keystonemiddleware.auth_token should add support for the new call without any user intervention.

Performance Impact

This change will potentially increase network chattiness in favor of smaller tokens.

keystonemiddleware.auth_token might want to cache the service catalog for a token to avoid repeating catalog requests back to Keystone.

Tokens will be generated slightly faster, as a resulting of eliminating calls to the catalog driver.

Tokens may be substantially reduced in size, effectively reducing HTTP packet sizes for all services (especially beneficial to those that do not utilize the service catalog).

Other Deployer Impact

keystonemiddleware.auth_token might benefit (in terms of performance) from a new configuration option to indicate that the protected service does not require a catalog.

Developer Impact




Primary assignee:


Other contributors:


Work Items

  • add new API call to openstack/identity-api

  • add service-side implementation to openstack/keystone

  • add support to python-keystoneclient for retrieving a service catalog when faced with a token that lacks one

  • add support to keystonemiddleware.auth_token to retrieve a service catalog when faced with a token that lacks one (and the underlying service expects a catalog)


The addition of authentication specific routes to the /auth path is part of the auth-specific-data blueprint. However there is no dependency between the functionality of the different blueprints.

Documentation Impact

The proposed API will need to be documented on openstack/openstack-api-site as part of Identity API v3.