Keystone v2 Basic Authentication filter

Purpose


The Keystone v2 Basic Authentication filter allows a user to obtain a user token based on the user name and secret presented in the standard HTTP Basic authentication scheme.

General filter information


Filter name: keystone-v2-basic-auth

Filter configuration: keystone-v2-basic-auth.cfg.xml

Release: version 8.0.0.0 *

* available in prior versions as Rackspace Identity Basic Auth filter

Prerequisites


Required Headers

AuthorizationX-Auth-Token
MissingPresentNothing to do
PresentMissingToken is requested (1)
MissingMissingRequest is rejected with 401 (2)

(1) The password field should contain the API key OR password (depending on the filter's configuration) for the provided user name.  Note: Password is only supported starting in Repose 7.3.1.0.
(2) Requests that are rejected with a 401 Unauthorized will contain a WWW-Authenticate header with the value of Basic realm="RAX-KEY".

Preceding filters: None

Following filters: This filter only acquires a user token; it does not perform any authentication nor authorization.  You can authenticate or authorize by adding the appropriate filter (e.g. Keystone v2) to process the Auth-Token header added by this filter.

Basic configuration


Within the keystone-v2-basic-auth element:

  • Configure the keystone-v2-service-uri attribute for the endpoint URI of the identity service.
  • Configure the secret-type attribute to indicate whether an API-key or password is expected in the Authorization header.
  • You can set the optional attribute token-cache-timeout-millis for the token cache timeout. The default value is 10 minutes. If the token cache timeout is set to Zero (0), caching is disabled and every inbound request will access the configured identity service to obtain a user token.

Optional 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 Basic Auth filter allows an unauthenticated request to pass when placed in delegating mode. The filter sends the X-Auth-Token header when valid credentials and identity have been confirmed and sends the X-Delegated header 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.

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 keystone-v2-basic-auth.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-basic-auth>-RequiredSpecifies the sub-elements and attributes to define your Keystone v2 Basic Authentication configuration. 
keystone-v2-service-uriRequiredThe target Keystone v2 endpoint URI for credential requests including scheme, host, and port to service. 

token-cache-timeout-millisOptionalTime in milliseconds to cache authentication token. The default value is 10 minutes. A value of Zero (0) is disabled. 

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
secret-typeOptional

Type of the secret portion of the authentication credentials provided in the Authorization header. Valid values are: api-key, password

Default value is: api-key

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

Return codes and conditions


  • If the identity service returns a 200 OK status code, the accompanying user token is added to the request as an X-Auth-Token header.
  • Any other return from the identity service indicates a user token is unable to be obtained and is handled as follows:
When the identity service returns:
Repose passes this response to the client:
This occurs when:
401 Unauthorized

401 and filter will append the  WWW- Authenticate header with the value of Basic realm = RAX-KEY

A bad user name and secret combination is used.

403 Forbidden403 and filter will  append the  WWW- Authenticate header with the value of Basic realm = RAX-KEY

The identity service is misconfigured or not available.

404 Not Found500

The identity service is misconfigured or not available.

413 Payload Too Large

*503 with retry-after header

Authentication calls fail due to service unavailability.

429 Too Many Requests

*503 with retry-after header

Authentication calls fail due to service unavailability.

All others500

The identity service is misconfigured or not available.

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

Request headers created


The Keystone v2 Basic Authentication filter creates the X-Auth-Token header which is used by an authentication or authorization filter.

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

Version 8.0.0.0: Renamed filter from Rackspace Identity Basic Auth to Keystone v2 Basic Auth.