Rackspace Identity Basic Authentication filter

Deprecated

This filter has been renamed to Keystone v2 Basic Auth in Repose version 8.

Purpose

The Rackspace Identity 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: rackspace-identity-basic-auth

Filter configuration: rackspace-identity-basic-auth.cfg.xml

Released: version 6.1.1.1 – 7.3.8.2 *

* available in release 8.0.0.0 as Keystone v2 Basic Auth

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

Required follow-on (succeeding) filters:

This filter only acquires a user token. You can authenticate or authorize by adding an appropriate filter, such as the OpenStack Identity v3, the Client Authentication, or the Client Authorization filter to process the X-Auth-Token header. 

Basic configuration

To set up basic authentication with an Identity service, edit the rackspace-identity-basic-auth.cfg.xml file.

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

2. Add the filter 
Add the Rackspace Identity Basic Auth filter to your system model configuration. Place this filter before other authentication filters.

3. Configure the filter 

Within the rackspace-identity-basic-auth element:

  • Configure the rackspace-identity-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.

If using the API-key secret-type, the identity service must support the Rackspace API key extension of the OpenStack Keystone v2 standard.

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 Rackspace Identity 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

Configure the Rackspace Identity Basic Authentication filter by editing the rackspace-identity-basic-auth.cfg.xml. Add the filter to the Repose deployment through the system model configuration by editing the following elements and attributes.

Element

Attribute

Required/

Optional

DescriptionVersion
<rackspace-identity-basic-auth>-RequiredSpecifies the sub-elements and attributes to define your Rackspace Identity Basic Authentication configuration. 
rackspace-identity-service-uriRequiredThe target Rackspace Identity 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

Note: Prior to version 7.3.1.0, only api-key was supported.

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