Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: minor typo in return code

...

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.

ElementsAttributes

Required/

Optional

DescriptionVersion
<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.7.3.0.0
<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.


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.

<uri-regex>
-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.
<timeouts>-Optional

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.
<group>-Optional

Time in seconds to cache authenticated groups.


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

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

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

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

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


<validate-tenant>-Optional

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 7.3.0.0

enable-legacy-roles-modeOptional

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 8.0.0.0

<uri-extraction-regex>

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

<pre-authorized-roles>

-Optional
validation check.
<role>-Required if using the <pre-authorized-roles> elementA user role.
<send-tenant-id-quality>-Optional

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.
<require-service-endpoint>-Optional

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-urlRequired

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


regionOptional

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


nameOptional

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


typeOptional

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:

 2xx
400401402403404405413429500501502503
Repose Get Admin Token Call ReturnsOK500500500500401500*503*503502502502052502
Repose Validate Token Call ReturnsOK500401
500
500500401500*503*503502502502502
Repose Groups Call ReturnsOK500401
500
500500OK500*503*503502502502502

* 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)

Name

Action

Function

Example

X-Auth-Token

Required on incoming request

Obtained from authentication service and provides access to origin service.

123abc

X-Authorization

Returned from the authentication service and passed to origin service

Informs origin service that user has been authenticated.

Proxy User

X-Identity-Status

Returned from the authentication service and passed to origin service

Indicates if identity has been confirmed.

Confirmed or Indeterminate

X-User-Name

Returned from the authentication service and passed to origin service

Identifies user name.

jjenkins

X-User-ID

Returned from the authentication service and passed to origin service

Identifies user ID.

12345

X-Roles

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

Header
Example
X-PP-Userjjenkins
X-PP-Groupsadmin,user

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.

Name

Function

Example

  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. 

HeaderExample
X-Impersonator-Id1024
X-Impersonator-Nameadmin-user
X-Impersonator-Rolesracker,admin

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