Keystone v2 filter


This filter is meant to be a replacement for the Client Authentication filter.

General Filter Information

Filter name: keystone-v2

Filter configuration: keystone-v2.cfg.xml

Released: version


Headers:  X-Auth-Token is a required header that is used by the Keystone v2 filter to define the operating parameters of the HTTP transaction. If an incoming HTTP request is missing the X-Auth-Token header, Repose will return a response with status code 401.

Preceding filters:

  • The Header Normalization filter can be used to remove headers that would be populated by the OpenStack Identity v3 filter to prevent spoofing of identities.

Authentication Configuration

To set up authentication with the Keystone v2 filter, edit the keystone-v2.cfg.xml file.

Within the identity-service element:

  • Optionally configure username and password attributes to match an administrator username and password to access the OpenStack identity service. If configured, Repose will fetch and use an admin token to authenticate any incoming user tokens. If these attributes are not configured, token self-validation will be attempted meaning that a user token will be used to authenticate itself.
  • Set uri as the target URI (i.e., the URI of your Identity Service endpoint) for authentication requests.
  • Optional elements and attributes are listed in the configurable parameters table below.

Configuration options


You can configure the Keystone v2 filter to authorize requests by configuring the require-service-endpoint element in the following way:

  • Configure public-url to match the URL for the endpoint that matches the origin service.
    • The comparison against the public-url verifies that the configured public-url matches the start of the token endpoint public-url (e.g., a configured public-url of "" will match the endpoint public-url of "").
  • Optional attributes that you can set for the service endpoint are regionname, and type.

Tenant ID Validation

The Keystone v2 filter can be configured to parse a tenant ID out of a request URI and validate it against the tenant ID(s) available in the response token from the Keystone v2 service. To enable this feature, add the following to your keystone-v2 configuration file as a child of the root element:


Note that ${your-regex} should be replaced by a Java regular expression that contains a capture group around the portion of the URI where the tenant ID is expected. This will also populate the X-Tenant-Id header with the value in the capture group. If the validate-tenant element is not present, the Keystone v2 filter will not attempt to validate a tenant ID from the URI.

Bypassing Tenant ID Validation by Role

If tenant ID validation is enabled, the Keystone v2 filter can be configured to bypass the check for certain requests. To do so, add the <pre-authorized-roles> element to your configuration file as a child of the root element. This element will have <role> children elements which define the roles for which the tenant ID check does not occur. These roles will be compared to the roles returned in a token from the Keystone v2 service, and if there is a match, the project ID check will be skipped.

Role Forwarding

Role forwarding refers to the extraction of the names of the roles returned with a user's token and adding them to the X-Roles header.

Starting in Repose, this filter will handle roles with tenants more intelligently. The following bullets outline the new behavior:

  • If NOT IN tenanted mode (i.e., the validate-tenant element is not present in the configuration) all roles in the user's token will be forwarded.
  • If IN tenanted mode AND pre-authorized, all roles in the user's token will be forwarded. Note that in order for a user to be pre-authorized based on role, the role in question must either not have an associated tenant, or the associated tenant must match the tenant extracted from the URI.
  • If IN tenanted mode AND NOT pre-authorized, only roles with no associated tenant or an associated tenant matching the tenant extracted from the URI will be forwarded.


You can configure the Keystone v2 filter to allow no-op processing of requests that do not require authentication. For example, a service might want all calls authenticated with the exception of the call for WADL retrieval. In this situation, you can configure the whitelist as shown in the sample Keystone v2 configuration file.

The whitelist contains a list of regular expressions that Repose attempts to match against the full request URI. If the URI matches a regular expression on the white list, the request is passed to the origin service. Otherwise, authentication is performed against the request.

Authentication Configuration with Whitelist
<keystone-v2 xmlns="">


The Keystone v2 filter caches authentication tokens. The length of time that tokens are cached is determined by the Time To Live (TTL) value that is returned from the authentication service (e.g., an OpenStack Identity v2 service) during token validation.

You can specify an alternate maximum TTL for caching of authentication tokens groups in the keystone-v2.cfg.xml file. If you specify the token element value in the configuration file, this value is used when caching tokens, unless the token TTL value provided by the OpenStack identity service is less than the token-cache-timeout value. This method prevents Repose from caching stale tokens. If the token's TTL exceeds the maximum allowed TTL value (2^31 - 1), the maximum allowed TTL is used.

Group and endpoint can also be cached by configuring their corresponding elements.

Using Atom feeds for cache expiration

You can configure the Keystone v2 filter to use Cloud Feeds for cache expiration. This configuration blocks malicious users from accessing the origin service by repeatedly checking the Cloud Feed from the authentication service. To set up the Keystone v2 filter to use Cloud feeds for cache expiration, you will need to enable the atom-feed-service in the System model, configure the atom-feed-service in the atom-feed-service.cfg.xml, and inform this filter which feeds to listen too in the the keystone-v2.cfg.xml file using the feed-id.

Rackspace Specific

Rackspace infrastructure uses Cloud Feeds (Formerly Atom Hopper) to notify services of events. This is not default OpenStack behavior, and may require additional services for use.

A list of Rackspace Cloud Feeds endpoints for Identity Events can be found at the internal Rackspace Wiki page linked here.

Delegating mode

In some cases, you may want to delegate the decision to authenticate a request down the chain to either another filter or to the origin service. The Keystone v2 filter allows an unauthenticated request to pass as either confirmed or indeterminate when placed in delegating mode. The filter sends a confirmed value when valid credentials have been confirmed by the Identity service, and sends an indeterminate value when the Identity service can not confirm the credentials.

To place the filter in delegating mode, add the delegating element to the filter configuration with a quality that determines the delegating priority.

If the Keystone v2 filter is configured to run in delegating mode, the X-Identity-Status HTTP header is set to a value of indeterminate. The request is then passed along to subsequent filters and the origin service with the X-Delegated header set.

Configurable parameters

XML schema definition

Example configuration

The keystone-v2.cfg.xml file contains the following elements and attributes. Add the filter to your Repose deployment through the system model configuration.




<keystone-v2>-RequiredThe root element of your Keystone v2 authentication configuration.
<identity-service>-RequiredDefines an OpenStack Identity (Keystone) endpoint with access credentials.
usernameOptional (Required if password is provided)Administrator username to access the OpenStack identity service. If not provided, token self-validation will be attempted.
passwordOptional (Required if username is provided)Administrator password to access the OpenStack identity service. If not provided, token self-validation will be attempted.
uriRequiredTarget URI for authentication requests.
set-roles-in-headerOptionalSet the user's roles in the x-roles header
set-groups-in-headerOptionalSet the user's groups in the x-pp-groups header. If the user has no groups, the header will not be set.
set-catalog-in-headerOptionalSet the user's service catalog in the x-catalog header
connection-pool-idOptionalTells the connection pool service to map to the pool with specified id. If default is chosen, the default connection pool configurations in connection pool service is used.

If present, the filter will not send a failing response when an invalid state is reached. Instead, it will add the data relating to the failure to a header and forward the request to be handled by a different filter or service. 

If not present, the filter will send a failing response when an invalid state is reached.

qualityOptionalThe quality, a double between 0 and 1, assigned to the delegation header on delegation. This value will be used to order delegation based on priority when multiple delegations are present.
<white-list>-OptionalA list of URI patterns all users can access.

-Required if using the <white-list> elementSpecifies the URI pattern that a user has access to.
<cache>-OptionalA container element for all configuration associated with caching.

A container element for specific cache timeout values. For all timeout values, the following applies:

If -1, caching is disabled.
If 0, data is cached indefinitely. In other words, data is eternal.
If greater than 0, data is cached for the value provided, in seconds.

variabilityOptionalCache timeout offset (in seconds) used when caching. A random value between -cache-offset and +cache-offset will be applied to the existing timeout values.
<token>-OptionalTime in seconds to cache authenticated token.

Time in seconds to cache authenticated groups.

<endpoints>-OptionalTime in seconds to cache authenticated endpoints.

Enables registering and listening to an Atom feed for cache invalidation.Implemented in version
idRequired if using the <atom-feed> element

The Feed ID as configured in the atom-feed-service.

Implemented in version
<tenant-handling>-OptionalA container element for all configuration associated with tenants.

Send all the tenant IDs from the user and the roles the user has.


If this element is included, tenant validation will be enforced based on the extraction URI.

strip-token-tenant-prefixesOptionalA '/' delimited list of prefixes to strip from the tenant ID when validating the tenant in the URI. Note that the validation is attempted against the unmodified token tenant ID first, then against the prefix-stripped tenant ID for all matching prefixes. If any validation succeeds, the URI tenant is considered to be valid.Implemented in version


If in legacy roles mode, all roles associated with a user token are forwarded.
If NOT in legacy roles mode, roles which aren't tied to the tenant provided in the request will NOT be forwarded UNLESS the user has a pre-authorized role.

Defaults to false.

Implemented in version


-Required if using the <validate-tenant> element
response from the identity service. The post-strip tenant id is only used in the tenant


validation check.
<role>-Required if using the <pre-authorized-roles> elementA user role.

If this element is included, include quality parameters on all the tenant ID headers sent.

default-tenant-qualityOptionalThe quality to associate with the default tenant ID.
uri-tenant-qualityOptionalThe quality to associate with the tenant ID extracted from the URI.
roles-tenant-qualityOptionalThe quality to associate with the tenant IDs extracted from token roles.

If this element is included, authorization will be enforced. The use associated with the provided x-auth-token must have an endpoint meeting the criteria defined

by the attributes on this element.


Public URL to match on the user's service catalog entry.


Region to match on the user's service catalog entry.


Name of the service to match in the user's service catalog entry.


Type to match in the user's service catalog entry.

Return codes and conditions

If the token is returned from the authentication service as invalid because it has expired, is bad, or is from a malicious user, the Keystone v2 filter returns the response to the client with a 401 error code.

The request will return from the Keystone v2 to the Repose filter chain for further processing. Once Repose processing is complete, the request will either be passed on to the origin service or a response will be sent to the client.

When the identity service returns:
Repose passes this response to the client:
This occurs when:
401 Unauthorized401 or 500

(401) Self-validating tokens are being used, and the user token has expired.

(500) The admin token has expired.

403 Forbidden403The admin token is unauthorized.
413 Payload Too Large*503 with retry-after headerThe identity service rate limits the Repose instance.
429 Too Many Requests*503 with retry-after headerThe identity service rate limits the Repose instance.
500 Internal Server Error502The identity service failure to process the request.

When the identity service returns:

Repose Get Admin Token Call ReturnsOK500500500500401500*503*503502502502502
Repose Validate Token Call ReturnsOK500401
Repose Groups Call ReturnsOK500401

* 503 response includes the retry-after header.

Request headers created

This section describes the headers that are used by the Keystone v2 filter to define the operating parameters of the HTTP transaction.

X-PP-User and X-PP-Groups

If the requesting client is able to authenticate and is passed down the request chain, the Keystone v2 filter will set X-PP-User and X-PP-Groups populated with the corresponding fields in the responses from Identity. If Identity returns either a 404 response, or a response with a body containing an empty groups array, this filter will not prevent the request from passing nor will it populate the X-PP-Groups header.

General authentication headers (OpenStack identity contract)






Required on incoming request

Obtained from authentication service and provides access to origin service.



Returned from the authentication service and passed to origin service

Informs origin service that user has been authenticated.

Proxy User


Returned from the authentication service and passed to origin service

Indicates if identity has been confirmed.

Confirmed or Indeterminate


Returned from the authentication service and passed to origin service

Identifies user name.



Returned from the authentication service and passed to origin service

Identifies user ID.



Returned from the authentication service and passed to origin service

Identifies roles.

admin, user

X-Authenticated-ByReturned from the authentication service and passed to origin serviceIdentifies the method(s) by which the request was authenticatedpassword

Rate limiting headers


X-Catalog header

Keystone v2 includes the ability to pass on a base 64 encoded service catalog from the authentication service via the x-catalog header to the origin service.




  1. X-Catalog

  1. Lists the service catalog for the user.

  1. amplbmtpbnMgc2VydmljZSBjYXRhbG9nDQo=

X-Impersonator Headers

OpenStack Identity Service supports impersonation.  When an impersonation token is validated, the authentication service will return identifying information for the impersonator.  The Keystone v2 filter will put this information into the following headers so that impersonated calls can be tracked (e.g., via SLF4J HTTP Logging).  Also, the end service can determine when a request is impersonated and who the impersonator is. 


Default Region Header

The OpenStack Identity Service also has other attributes it provides when a token is validated. One of those attributes can be the default region for the user. This information will be passed in the form of a header.