OpenStack Identity v3 filter

General filter information

Filter name: openstack-identity-v3

Filter configuration: openstack-identity-v3.cfg.xml

Released: version 6.1.0.3

Prerequisites

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


Preceding filters:

  • The Header Translation filter can be used to convert the X-Auth-Token header to X-Subject-Token to maintain backwards compatibility with other filters. If the Header Translation filter is used, it should be placed before the OpenStack Identity v3 filter.
  • 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.

Basic authentication configuration 

To set up basic authentication with the OpenStack Identity v3 filter, edit the openstack-identity-v3.cfg.xml file.

Within the openstack-identity-service element:

  • Configure username and password to match the administrator username and password to access the OpenStack identity service.
  • Set uri as the target URI for authentication requests.
  • Optional elements and attributes are listed in the Configurable parameters table below.

Configuration options

Authorization

You can configure the OpenStack Identity v3 filter to authorize requests by configuring the openstack-identity-service and the service-endpoint elements.

Within the openstack-identity-service element:

  • Configure username and password to match the administrator username and password to access the OpenStack identity service.
  • Set uri as the target URI for authentication requests.

Within the service-endpoint element:

  • Configure url to match the URL for the endpoint that matches the origin service.
  • Optional attributes that you can set for the service endpoint are regionname, and interface.

Project ID Validation

The OpenStack Identity v3 filter can be configured to parse a project ID out of a request URI and validate it against the project ID(s) available in the response token from the Identity v3 service. To enable this feature, add the <validate-project-id-in-uri regex="${your-regex}"> element to your openstack-identity-v3 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 project ID is expected. This will also populate the X-Project-Id header with the value in the capture group.  If this element is not present, the OpenStack Identity v3 filter will not attempt to validate a project ID from the URI.

 

Note that this behavior is analogous to the tenanted mode available in the Client Authentication filter (Client Authentication filter#Tenantedmode) which adhered to the OpenStack Identity v2 contract. The configuration has, however, changed slightly to reduce verbosity as well as complexity. The project ID has also replaced the tenant ID as per the OpenStack Identity contract.

Bypassing Project ID Validation by Role

If project ID validation is enabled, the OpenStack Identity v3 filter can be configured to bypass the check for certain requests. To do so, add the <roles-which-bypass-project-id-check> 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 project ID check does not occur. These roles will be compared to the roles returned in a token from the Identity v3 service, and if there is a match, the project ID check will be skipped.

 

Whitelist

You can configure the OpenStack Identity v3 filter to allow the 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 OpenStack Identity v3 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. 

In the following example, the system model is configured to whitelist with the OpenStack Identity v3 filter.

Cache

The OpenStack Identity v3 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 (for example, Rackspace Cloud Identity) during token validation.

You can specify an alternate maximum TTL for caching of authentication tokens groups in the openstack-identity-v3.cfg.xml file. If you specify the token 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 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.

The length of time that user groups are cached is determined by the element group. The element value is optional and defaults to 600,000 milliseconds (10 minutes). You can set the group value in the OpenStack authentication scheme as shown in the example below.

You can also subscribe to an atom feed to monitor token invalidation.  To do so, you would configure the atom feed details in the Atom Feed Service configuration, and you would refer to that configuration in the cache configuration 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 OpenStack Identity v3 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 and identity have been confirmed and sends an indeterminate value when no credentials have been sent or identity has not been confirmed.

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 OpenStack Identity v3 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. The X-Authorization and the X-Identity-Status request headers are set with no user entry. 

Legacy mode


The OpenStack Identity v3 filter is written to work in a pure v3 environment. However, we have seen that most deployments are using an Identity v3 service in a legacy v2 environment. As one would expect, this does not work correctly. The legacy services populate the X-Auth-Token request header while the v3 service expects it to be in the X-Subject-Token request header. At the same time, the v3 service populates the X-Project-Id request header while the legacy services expect it to be in the X-Tenant-Id request header.

The long term fix would be to upgrade the entirety of the system to a pure v3 environment. As this can be a lengthy process, an interim solution would be to sandwich the OpenStack Identity v3 filter between a pair of Header Translation filters. This will provide the expected values in both the v3 and legacy request headers. Those configurations would be like:

and

Configurable parameters

XML schema definition

Example configuration

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

ElementsAttributes

Required/

Optional

DescriptionVersion
<openstack-identity-v3>-RequiredSpecifies the sub-elements and attributes to define your OpenStack identity v3 authentication configuration. 
forward-unauthorized-requestsOptional

Default is false.

  • If set to false, the OpenStack Identity v3 filter will not forward unauthorized requests.
  • If set to true, the OpenStack Identity v3 filter will forward unauthorized requests and set the X-Authorization and X-Identity-Status headers to the appropriate values.
 
token-cache-timeoutOptional

Time in milliseconds to cache authentication token.

 
groups-cache-timeoutOptional

Time in milliseconds to cache authentication groups.

 
cache-offsetOptional

Cache timeout offset (in milliseconds) for token and group cache. A random value between -cache-offset and +cache-offset will be applied to the existing token and group timeout values.

 
forward-groupsOptionalTells the service whether or not to make a GET groups API call to the OpenStack identity service. 
send-all-project-idsOptionalTells the filter whether or not to send multiple X-Project-Id headers corresponding to all available project ids for a user.6.1.1.1
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.7.3.0.0
<validate-project-id-in-uri> Optional

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

8.2.0.0
default-project-qualityOptionalThe quality to associate with the default project ID.8.2.0.0
uri-project-qualityOptionalThe quality to associate with the project ID extracted from the URI.8.2.0.0

roles-project-qualityOptionalThe quality to associate with the project IDs extracted from token roles.8.2.0.0
<validate-project-id-in-uri>-Optional

Enables the validation of a project ID from the request URI against the user information held by the Identity service (i.e., the token).

6.1.1.1
strip-token-project-prefixesOptionalA '/' delimited list of prefixes to strip from the project ID when validating the project in the URI. Note that the validation is attempted against the unmodified token project ID first, then against the prefix-stripped project ID for all matching prefixes. If any validation succeeds, the URI project is considered to be valid.7.3.0.0
<roles-which-bypass-project-id-check>-Optional

A list of roles to bypass the project ID check, if enabled. Users with any of the roles specified will not be required to have a project ID.

Deprecated in v8.1.0.0.

 
<pre-authorized-roles>-OptionalA list of roles to bypass all authorization checks, if enabled. Users with any of the roles specified will not be required to have a project ID.8.1.0.0

<whitelist>

-Optional A list of URI patterns all users can access. 
<uri-pattern>-Required if using<whitelist>Specifies the URI pattern that a user has access to. 
<openstack-identity-service>-Required Defines an OpenStack OpenStack identity endpoint and access credentials. 
usernameRequiredAdministrator username to access the OpenStack identity service. 
passwordRequiredAdministrator password to access the OpenStack identity service. 
uriRequiredTarget URI for authentication requests. 
project-idOptionalThe project ID of the administrator defined by the username and password. 
<service-endpoint>-OptionalDescribes the service mapping for the origin service. 
urlRequired if using<service-endpoint>URL for the endpoint that matches the origin service. 
regionOptionalRegion for the endpoint that matches the origin service. 
nameOptionalName for the endpoint that matches the origin service. 
interfaceOptionalInterface for the endpoint that matches the origin service. 
<delegating>-Optional

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.

7.0.0.1
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.7.0.0.1
<cache>-Optional

Configuration for the cache

8.0.2.0
<timeouts>-Optional

Configuration for the cache timeouts

8.0.2.0
varianceOptionalCache timeout offset (in milliseconds) for token and group cache. A random value between -variance and +variance will be applied to the existing token and group timeout values.8.0.2.0
<token>-OptionalTime in milliseconds to cache authentication token.8.0.2.0
<group>-OptionalTime in milliseconds to cache authentication groups.8.0.2.0
<atom-feed>-Optional

Enables registering and listening to an Atom feed for cache invalidation.

8.0.2.0
idRequired if using the <atom-feed> elementThe Feed ID as configured in the atom-feed-service.8.0.2.0


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 OpenStack Identity v3 filter returns the response to the client with a 401 error code.

The request will return from the OpenStack Identity v3 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.

The rules in the table below may also be found at: Authentication in OpenStack

When the identity service returns:
Repose passes this response to the client:
This occurs when:
401 Unauthorized401The authentication service sends a 401 error code to Repose and delegable = false .
403 Forbidden403The identity service is misconfigured or not available.
413 Payload Too Large*503 with retry-after headerThe identity service is misconfigured or not available.
429 Too Many Requests*503 with retry-after headerThe identity service is misconfigured or not available.
500 Internal Server Error500The identity service is misconfigured or not available and did not send a delegated WWW-Authenticate header to Repose.

When the identity service returns:

 2xx   400   401   402   403   404   405   413   429   500   501   502   503
Repose Get Admin Token Call ReturnsOK    500   500   500   500   500   500  *503  *503   500   500   500   500
Repose Validate Token Call ReturnsOK    500   500   500   500   401   500  *503  *503   500   500   500   500 
Repose Groups Call ReturnsOK    500   500   500   500   500   500  *503  *503   500   500   500   500 

* 503 response includes the retry-after header.

Request headers created

This section describes the headers that are used by the OpenStack Identity v3 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 OpenStack Identity v3 filter will set X-PP-User and X-PP-Groups according to the schema of the authentication service. The filter will also set a quality with a value of '1' for these headers.

Example Configuration Element for X-PP-User Header

X-PP-User:Username

General authentication headers (OpenStack identity contract)

Name

Action

Function

Example

X-Subject-Token

Required on incoming request

Obtained from authentication service and provides access to origin service.

123abc

X-Authorization

Returned from authentication service

Informs origin service that user has been authenticated.

Proxy User

X-Identity-Status

Returned from authentication service and passed to origin service

Indicates if identity has been confirmed.

Confirmed or Indeterminate

X-Subject-Name

Returned from authenticationservice and passed to origin service

Identifies subject name.

1234567

X-Subject-ID

Returned from authenticationservice and passed to origin service

Identifies subject ID.

1234567

X-User-Name

Returned from authenticationservice

Identifies user name.

jjenkins

X-User-ID

Returned from authenticationservice and passed to origin service

Identifies user ID.

12345

X-Roles

Returned from authenticationservice and passed to origin service

Identifies roles.

admin, user

Token expiration header

When a token is validated, the authentication service will return identifying information with token expiration date. The OpenStack Identity v3 filter will put this information into the following header in HTTP rfc1123 GMT time format.

Name

Function

Example

X-Token-Expires

Identifies when token will expire.

Tue, 02 Jul 2013 16:25:08 GMT

Rate limiting headers

Header
Example
Same as
X-PP-UserjjenkinsX-User-Name
X-PP-Groupsadmin userX-Roles

X-Catalog header

Client authentication 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.

Name

Function

Example

  1. X-Catalog

  1. Lists the service catalog for the user.

  1. amplbmtpbnMgc2VydmljZSBjYXRhbG9nDQo=

Example Configuration Element for X-Catalog Header

<endpoints-in-header format="xml" cache-timeout="600000"identity-contract-versions="2">

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 OpenStack Identity v3 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.

HeaderExample
X-Impersonator-Id1024
X-Impersonator-Nameadmin-user

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.

HeaderExample
X-Default-RegionSAT

Change history

Version 7.0.1.0: Repose returns a 503 error code with the retry-after header when authentication calls fail because of service unavailability (413 or 429 error codes).