OpenStack Identity v3 Filter

Authentication is the process of validating that a request was made by a valid user.
This is accomplished by checking that the subject token on the request can be confirmed by the identity service.

Authorization is the process of validating that the user has permission to make a request.
This is accomplished by checking two factors:

That a project ID in the path of the request matches a project ID that the user has some permission on.

That the user has access to a specified endpoint.

Authorization is an optional feature.

Enrichment is the process of adding additional information to the request.
This information is gathered through authentication and authorization.
It includes things like the user’s name, ID, roles, groups, and service catalog.

General filter information

Prerequisites & Postconditions

Required Request Headers

X-Subject-Token - A required header that identifies the user and is validated against the identity service.
If an incoming request is missing this header, then a response status code of Unauthorized (401) is returned.

Required Preceding Filters

This filter has no required preceding filters, however the following filters may be useful:

Header Translation Filter - To convert the X-Auth-Token header to X-Subject-Token to maintain backwards compatibility with other filters.
If used, it should be placed before this filter.

If the forward-catalog attribute is true, then the service catalog from the identity service is base 64 encoded and placed in the following header:

X-Catalog - The base 64 encoded service catalog for the user. (e.g., "amplbmtpbnMgc2VydmljZSBjYXRhbG9nDQo=")

Some instance of the OpenStack Identity v3 service may support impersonation.
When an impersonation token is validated, the identity service will return identifying information for the impersonator.
This information allows impersonated calls to be tracked (e.g., via SLF4J HTTP Logging filter).
The origin service can also determine when a request is impersonated and who the impersonator is.
The information is placed in the following headers:

X-Impersonator-Name - Identifies user name of the impersonator. (e.g., "admin-user")

Delegation is a way to continue processing a request despite the occurrence of an error.
It is mainly intended for use by the Highly Efficient Record Processor (HERP) filter and Delegation Response Processor (DeRP) filter for internal delegation processing within Repose.
However, it can be exposed to the origin service under certain configurations.
If delegation is enabled via the inclusion of the delegating element in the configuration, the following headers may be added to the request:

X-Delegated - Identifies any errors that occurred.

Only if the delegating element is defined and an error occurs during processing.

HTTP connection pool ID to use when talking to the OpenStack Identity v3 service.NOTE: If the connection-pool-id is not defined, then the default pool is used.

2

Set the user’s groups in the X-PP-Groups header.
Default: true

3

Set the user’s service catalog, base64 encoded, in the X-Catalog header.
Default: false

4

Project ID to use when authenticating as an admin user with the OpenStack Identity v3 service.
Providing a project ID will scope the access of the admin to a specific project.
Optional.

Enabling Delegation

In some cases, you may want to delegate the decision to reject a request down the chain to either another filter or to the origin service.
This filter allows a request to pass as either confirmed or indeterminate when configured to run in delegating mode.
To place the filter in delegating mode, add the delegating element to the filter configuration with an optional quality attribute that determines the delegating priority.
When in delegating mode, the filter sets the X-Identity-Status header with a value of confirmed when valid credentials have been authenticated by the OpenStack Identity v3 service and to indeterminate when the credentials are not.
The the X-Identity-Status header is in addition to the regular X-Delegated delegation header being created.

If this element is present, then delegation is enabled.
Delegation will cause this filter to pass requests it would ordinarily reject along with a header detailing why it would have rejected the request.

2

Indicates the quality that will be added to any output headers.
When setting up a chain of delegating filters the highest quality number will be the one that is eventually output to the logging mechanisms.
Default: 0.7

Configuring White-Listed URI’s

You can configure this 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 example below.
The whitelist contains a list of Java Regular Expressions that Repose attempts to match against the full request URI.
If the URI matches an expression in the white list, then the request is passed to the origin service.
Otherwise, authentication is performed against the request.

Configuring Cache Timeouts

This filter caches authentication tokens and user groups.
The length of time that tokens are cached is determined by the Time To Live (TTL) value that is returned from the OpenStack Identity v3 service during token validation.

You can configure alternate maximum TTL for caching of authentication tokens and groups.
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 v3 is less than the configured 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.

This value will be added or subtracted to the cache timeouts to help ensure that the cached items have some variability so they don’t all expire at the exact same time.
Default: 0

2

The number of seconds which cached tokens will live in the datastore.
Default: 600

3

The number of seconds which cached groups will live in the datastore.
Default: 600

Each timeout value behaves in the following way:

If 0, data is cached using the TTL in the token provided by the OpenStack Identity v3 service.

If greater than 0, data is cached for the value provided, in seconds.

Configuring Cache Invalidation Using an Atom Feed

You can configure this filter to use an Atom Feed 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 this filter to use Cloud Feeds for cache expiration, you will need to enable the Atom Feed Consumption service in the System model, configure the Atom Feed Consumption service, and configure this filter with which feeds to listen to.

The 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.

Project ID Authorization

Project ID authorization is the capability of this filter to parse a tenant ID out of the request and validate it against the project ID(s) available in the response token from the OpenStack Identity v3 service.

Indicates if all the project IDs from the user and the roles the user has should be sent or not.
If true, all project IDs associated with the user are sent.
If false, only the matching project IDs from the request are sent.
If no request project IDs match any user projects, then the default user project is sent.
If no default user project ID exists, then an indeterminate project ID from the set of role project IDs is sent.
If no role project IDs exist, then no project ID is sent.
Default: false

2

If this element is included, then project ID validation will be enforced based on the value extracted from the request.

3

A / delimited list of prefixes to attempt to strip from the project ID in the token response from the Keystone v2 Identity service.
The post-strip project ID is only used in the project validation check.

4

The Java Regular Expression with at least one capture group.
The first capture group must be around the portion of the URI to extract the project ID from for validation.

5

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

6

The default project ID has the highest quality by default.
Default: 0.9

7

Followed by the one that matches the project ID extracted from the request by default (if any).
Default: 0.7

8

Followed by the project IDs from the roles by default.
Default: 0.5

If the default project ID and a project ID extracted from the request are the same, then the highest quality between the two will be used.

If the validate-project-id-in-uri element is not present, then this filter will not attempt to validate a project ID from the request.

Tenant ID Validation Bypass

If project ID authorization is enabled, then a list of roles that are allowed to bypass this check can be configured.
These configured roles will be compared to the roles returned in a token from the OpenStack Identity v3 service, and if there is a match, the project ID check will be skipped.