Client Authentication filter

 

Currently, the Client Authentication filter supports the  OpenStack Identity Service  authentication scheme. For example, the Client Authentication filter may be configured to interact with Keystone or Cloud Auth 2.0 (both of which implement the OpenStack Identity Service contract) when validating user credentials.

General filter information

Filter name: client-auth

Filter configuration: client-auth-n.cfg.xml

Released: prior to version 1.0.5

REMOVED: v8.0.0.0

Prerequisites

Headers:  X-Auth-Token is a required header that is used by the Client Authentication filter to define the operating parameters of the HTTP transaction. If the incoming HTTP request X-Auth-Token header does not have an auth token, Repose performs the same steps as when the Tenant ID is missing. Thus, both the Tenant ID and the X-Auth-Token must be present in order for Repose to attempt to validate user credentials.
Preceding filters: The Header Normalization filter is often used with the Client Authentication filter but is not required. If the Header Normalization filter is used, it should be placed before the Client Authentication filter.

Basic client authentication configuration (Keystone) 


1. Set Up Repose 
Configure Repose using either a cluster or a single instance configuration.

2. Add the Client Authentication filter 
Add the Client Authentication filter to your system model configuration. Place this filter below the logging and the normalization filters. If you are not using logging or normalization filters in your system model configuration, place the Client Authentication filter at the top of the filter chain.

3. Configure the Client Authentication filter 

 a.  Within the identity-service element:

    • Configure the administrator username and password for the authentication service that you interact with.
    • Configure the uri with the authentication endpoint.

 b. Within the openstack-auth element:

    • Set request-groups to false if you need only a single rate limit group that can be set to default, or if you populate the X-PP-Groups header in a different way. The default is true.
    • If token-cache-timeout is configured, the minimum between that value and the value provided by the identity service will be used. Roles will be cached as part of the token.

    • Adjust the cache time if necessary for group-cache-timeout. The default setting is 600,000 milliseconds (10 minutes). The Keystone service does not provide a TTL in the groups response, so you will need to adjust the group-cache-timeout if you do not want to use the default value.

 

In the following example, the system model is configured to perform basic authentication with the Client Authentication filter.

 

Configuration options   

Non-tenanted mode

The Client Authentication filter has the option of a non-tenanted mode within the openstack-auth element  of the configuration. This is enabled when tenanted=false. In this mode, Repose will validate the authentication token without regard to a tenant.

The following steps will guide you through the recommended setup.

  1. Configure the Header Normalization Filter 

Configure the Header Normalization filter to blacklist x-roles headers before they reach the Client Authorization filter.  The Header Normalization filter strips the x-roles header from the request which will protect against bad x-roles header information.

      2.  Configure the Client Authentication Filter

To configure the Client Authentication filter to bypass tenant validation checks:

    • Add the roles in the ignore-tenant-role element that you want the filter to pass.
    • Configure tenanted to false.

Tenanted mode

The Client Authentication filter will parse the URI using the configurable regular expression id-regex to extract the tenant ID from the request URI. If the origin service is configured to run in delegated mode, an HTTP request header named X-Identity-Status will be set with a value of indeterminate. The request will then be passed along to the origin service with the X-Authorization and X-Identity-Status request headers set. The Client Authentication filter determines if the origin service is in delegated mode based on the boolean value of the delegable attribute.

If the tenant ID is missing, Repose will not make a call to the external authentication service to validate credentials. Repose will set the X-Authorization header with no user entry (e.g. X-Authorization: Proxy). Instead, the filter returns a 401 to the client.

To run in tenanted mode:

  • Set tenanted to true and include the client-mapping element to specify the index where the URI exists within your API. 
  • Specify ignore-tenant-roles to designate administrator roles that bypass tenant checks. 
  • Specify service-admin-roles to designate a list of roles that will not be validated against a tenant.
  • Set send-all-tenant-ids to true if you want to allow all tenant ids to be included in headers.

In the following example, the Client Authentication filter is configured to ignore tenant roles named role-1 and role-2.

 

The following table shows the results for configurations that use the tenanted attribute, the service-admin-roles element, and ignore-tenant-roles element.

Tenanted

service-admin-roles

ignore-tenant-roles

Result

True

Not set or no match

Not set or no match

  • URI must have a tenant ID
  • User must have a tenant ID
  • URI tenant ID and user tenant ID must match

True

Not set or no match

Match

  • URI must have a tenant ID
  • User must have a tenant ID
  • URI tenant ID and user tenant ID must match

True

Match

Not set or no match

  • URI must have a tenant ID
  • User must have a tenant ID
  • URI tenant ID and user tenant ID do not have to match

True

Match

Match

  • URI must have a tenant ID
  • User does not need to have a tenant ID
  • URI tenant ID and user tenant ID do not have to match

False

Not set or no match

Not set or no match

  • URI does not need to have to have tenant ID
  • User must have a tenant ID
  • URI tenant ID and user tenant ID do not have to match

False

Not set or no match

Match

  • URI does not need to have to have tenant ID
  • User does not need to have a tenant ID 
  • URI tenant ID and user tenant ID do not have to match

False

Match

Not set or no match

  • URI does not need to have to have tenant ID
  • User must have a tenant ID
  • URI tenant ID and user tenant ID do not have to match

False

Match

Match

  • URI does not need to have to have tenant ID
  • User does not need to have a tenant ID 
  • URI tenant ID and user tenant ID do not have to match

Tenant ID/token

If the Client Authentication filter successfully obtains the tenant ID and the token from the request, Repose will send a request to the external authentication service to validate the token.

If the token is valid, Repose does the following: 

  1. Perform another request against the external authentication service to retrieve the user's groups using the user ID from the validated token. If request-groups is set to false, Repose does not make another request against the external authentication service to retrieve the user's groups.
  2. Add the groups to the X-PP-Groups request header to be consumed by the Rate Limiting filter. If attribute request-groups is set to false, the X-PP-Groups request header will not be set for Rate Limiting filter if that is expected, rate limiting will be working with the group that is set default to true in the rate limiting configuration. By default, the request-groups attribute is set to true.
  3. Add the user ID to the X-PP-User request header to be consumed by the Rate Limiting filter.
  4. Set the X-User-Name header with the username returned in the validated token object.
  5. Set the X-User-Id header with the user ID returned in the validated token object.
  6. Set the X-Tenant-Name header with the tenant ID passed in on the URL.
  7. Set the X-Tenant-Id header with the tenant ID passed in on the URL.
  8. Set the X-Roles header with the roles returned in the validated token object.
  9. Set the X-Authorization header to proxy userId.
  10. If delegating is set to true, set X-Identity-Status to confirmed.
  11. Pass the updated request to the origin service

If the token is not valid, Repose does the following:

  1. Set the X-Authorization header to Proxy userId.
  2. If delegating is set to true, set X-Identity-Status to indeterminate.
  3. If delegating is set to false, pass the updated request to the origin service.

If the Response Repose receives from the Authentication Service, when validating a user token, does not have the following, Repose will print a message in the logs and return a 500 error

  1. Tenant
  2. Roles List
  3. User

Whitelist

You can configure Repose authentication 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 Repose whitelist as shown in the sample authentication configuration file.

The whitelist contains a list of regular expressions Repose will attempt 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.

Cache

Repose authentication caches authentication tokens, roles, and groups. The length of time that tokens and roles 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 and roles in the client authentication configuration file. If you specify the token-cache-timeout value in the configuration file, this value is used when caching tokens and roles, unless the token TTL value 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, the maximum allowed TTL is used.

The length of time that user groups are cached is determined by a Repose configuration attribute: group-cache-timeout. The attribute value is optional and defaults to 600,000 milliseconds (10 minutes). You can set the group-cache-timeout value in the OpenStack authentication scheme as shown in the following example.

Using Atom feeds for cache expiration

 

You can configure the Client Authentication 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 Client Authentication filter to use Cloud feeds for cache expiration, you will need to configure the client-auth-n.cfg.xml file.

The following steps will guide you through the recommended setup.

  1. Configure check-interval
    Within the atom-feeds element, set check-interval to the interval frequency for requesting Atom feeds to purge the cache. The default time is set at 1 minute or 60000 milliseconds.
  2. Configure rs-identity
    Within the rs-identity element, configure the following attributes:
  • Set id as a unique identifier for the feed.
  • Set uri to point to the path to the feed.
  • Set isAuthed to true to require authentication credentials. Note that these credentials will likely match the credentials provided in the <identity-service> element.
  • Set auth-uri to point to the URI to authenticate against if it is different from the client-auth URI.
  • Set user to name the authentication administrator username.
  • Set password to name the authentication administrator password.

An example configuration file follows:

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

Supported events

Repose specifies the supported events in the SaxAuthFeedReader class.

See the Cloud Identity chapter in the Rackspace Cloud Feeds Developer Guide for the events that Repose supports.


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 Client Authentication 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 delegation priority.

If the Client Authentication 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. 

The format for the X-Delegated header value is “status_code={status-code}`component={filter-name}`message={failure message};q={delegating-quality}”

 

Configurable parameters

XML schema definition

Example configuration

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

openstack-ids-auth
Elements Attributes

Required/

Optional

DescriptionVersion
<client-auth>-RequiredSpecifies the sub-elements and attributes to define your client authentication configuration. 
<openstack-auth>-RequiredDefines an OpenStack Identity Service authentication configuration. 
tenantedOptional

Determines if the URI must contain a tenant ID. Default value is true.

If set to true, the URI must have a tenant ID in it, it must match the tenant ID of the user making the request, and client-mapping must be used.

If set to falsethe filter will not check the URI or compare the user’s tenant ID with it.

 
request-groupsOptional

Determines whether or not to make a GET Groups call to the authentication service and forward the result in the X-PP-Groups header. (This is an extra external call from Repose.) Default is true.

 
token-cache-timeoutOptionalDefines time in milliseconds to cache auth token. Default is the TTL received from the Keystone service. 
group-cache-timeoutOptionalDefines time in milliseconds to cache auth groups. Default is 600,000 milliseconds (10 minutes). 
cache-offsetOptionalCaches 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. Implemented in version 2.8.0.2
user-cache-timeoutOptionalDetermines cache timeout of endpoint in milliseconds.  
send-all-tenant-idsOptional

Option to allow all tenant ids to be included in headers. Default is false.

 

Implemented in version 6.2.2.0
send-tenant-id-qualityOptionalTells the filter whether or not to send quality parameters with the X-Tenant-Id header. 
connectionPoolIdOptionalTells the connection pool service to map to the pool with specified id. If default is chosen then the default connection pool configurations in connection pool service is used.Implemented in version 2.10.0
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
<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.

Implemented in version 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.Implemented in version 7.0.0.1
<identity-service>-RequiredSpecifies the the attributes for the authentication service that you interact with. 
usernameRequiredUsername for the authentication service that you interact with. 
passwordRequiredPassword for the authentication service that you interact with. 
uriRequiredDefines target URI for authentication requests. 
tenantIdOptionalTenantId with admin permission used by the Keystone implementation perform admin tasks. 
<client-mapping>-Required if tenanted is set to true.

Defines target URI for authentication requests. You can have multiple client-mapping elements.


 
id-regexRequired if using client-mapping.

Used to extract the client id from a given URI. 

 
tenantIdOptionalTenantId with admin permission used by the Keystone implementation perform admin tasks. 
<endpoints-in-header>-OptionalDetermines whether or not to include endpoints in a headers, what format, what identity contract version, and cache timeout.  
formatOptionalDetermines endpoint header format.  
cache-timeoutOptionalDetermines cache timeout of endpoint in milliseconds. 
identity-contract-versionOptionalDetermines the contract identity version. Currently, only a value of 2 is allowed. 
<service-admin-roles>-Optional

Defines a list of roles that will not be validated against a tenant. A user with any of the roles specified will bypass the check to see if the user’s tenant ID matches the tenant ID in the URI.

  • If tenanted is set to false, this option has no effect.
Implemented in version 2.8.4
<role>-Required if using <service-admin-roles>Names the role that will not be validated against a tenant. 
<ignore-tenant-roles>-Optional

Defines a list of roles that bypass the tenant requirement check. A user with any of the roles specified will not have the requirement for a tenant. 

  • If tenanted is set to true, the service-admin-roles element must be configured to match the ignore-tenant-roles element.
  • If tenanted is set to false, this option has no effect.
Implemented in version 4.1.5
<role>-Required if using <ignore-tenant-roles>Names the role that will bypass the tenant requirement check. 
client-auth-n.cfg.xml
ElementsAttributes

Required/

Optional

DescriptionVersion
<client-auth>-RequiredSpecifies the sub-elements and attributes to define your authentication configuration. 

<white-list>

-OptionalLists the URI patterns that all users can access.Implemented in version previous to 2x
<uri-pattern>-Required if using whitelist.Specifies the URI pattern that a user has access. 
uri-regexRequired if using whitelist.Specifies the regular expression of which URI is allowed access. 
<atom-feeds>-OptionalSpecifies the elements and attributes that define your Atom feed configuration. 
check-intervalOptionalInterval between requesting Atom feeds to purge cache. The default is one minute. 

<rs-identity-feed>

-Required if using atom-feeds.Specifies the attributes for your rs-identity-feed. 
idRequired if using atom-feeds.Specifies the unique ID of the Atom feed. 
uriRequired if using atom-feeds.Specifies the Atom feed URI. 
isAuthedOptional

Configure whether or not this feed requires authentication credentials.

Default value is false.

 
auth-uriRequired if isAuthed = trueURI to authenticate against if different from client-auth URI. 
userOptionalSpecifies the authenticated administer's username. 
passwordOptionalSpecifies the authenticated administer's password. 

 

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

The request will return from the Client Authentication filter 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.
504 Gateway Timeout504The authentication service fails to respond after the connection is made and the socket times out.

* In versions previous to 7.0.1.0, the response to a 413 or a 429 error code is a 500.

 

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 Client Authentication 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 Client Authentication 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 (Keystone contract)

Name

Action

Function

Example

X-Auth-Token

Required on incoming request

Obtained from AuthN service and provides access to origin service.

123abc

X-Authorization

Returned from auth service

Informs origin service that user has been authenticated.

Proxy User

X-Identity-Status

Returned from auth service and passed to origin service

Indicates if identity has been confirmed.

Confirmed or Indeterminate

X-Tenant-Name

Returned from auth service and passed to origin service

Identifies tenant name.

1234567

X-Tenant-ID

Returned from auth service and passed to origin service

Identifies tenant ID.

1234567

X-User-Name

Returned from auth service

Identifies user name.

jjenkins

X-User-ID

Returned from auth service and passed to origin service

Identifies user ID.

12345

X-Roles

Returned from auth service 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 Client Authentication 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
X-PP-Userjjenkins
X-PP-Groupsadmin user

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

Other headers

OpenStack Identity Service supports impersonation.  When an impersonation token is validated, the authentication service will return identifying information for the impersonator.  The Client uthentication filter will put this information into the following headers so that impersonated calls can be tracked (via 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

 

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

 

If the user token that is returned from the OpenStack Identity service contains a rax-auth:contactId node, then it's value is placed in the X-CONTACT-ID header of the request.

HeaderExample
X-Header-Id

188324

 

Change history

Version 6.2.2.0: You can set send-all-tenant-ids to true so that all of the tenant IDs per user are returned and the default ID is specified.

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