Client Authorization filter

Note: This filter has been removed in favor of the Keystone v2 filter.

Purpose

For identities that are validated by the Authentication component, you can use the Client Authorization filter to confirm that the services being requested match those for which the user has permission.

The Authorization component enables the service implementer to validate that a client's request is allowed.

  • If the client's request is allowed, then the request is passed through without any changes.

  • If the client's request is not allowed, then the request is denied with an HTTP 403 (forbidden) response.

General filter information

Filter name: client-authorization

Filter configuration: openstack-authorization.cfg.xml

Release: version 1.1.0

REMOVED: v8.0.0.0

Prerequisites

Headers: X-Auth-Token is a required header that is used by the Client Authorization filter to define the operating parameters of the HTTP transaction. 

Preceding filtersThe Header Normalization and the Client Authentication filters are not required but are recommended when using the Client Authorization filter. If they are used they should be placed in the following order before the Client Authorization filter: 

  1. Header Normalization filter
  2. Client Authentication filter

Basic client authorization configuration

1. Set up Repose

Configure Repose using either a cluster or a single instance configuration.

2. Add the Client Authorization filter

Add the Client Authorization filter to your system model configuration. Place this filter below the Header Normalization and the Client Authentication filters. See the standard filter order for more detailed information about filter placement.

3. Configure the Client Authorization filter

  • Under  <authentication-server>, configure the administrator usernamepassword, and hyperlink reference (href) for the authentication service that you interact with. 
  • Under  <service-endpoint>, configure the href for the service catalog that you interact with.
  • You may configure other attributes within the Client Authorization filter as necessary.

4. Start Repose

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

Optional non-tenanted authorization configuration

You can configure the Client Authorization filter to allow service access to all endpoints by using the <ignore-tenant-role> element. This allows users with specific roles to access all tenant resources without a tenant check. Within the <ignore-tenant-role> element, add the roles that you want to the Client Authorization filter to pass. The Client Authorization filter must receive the x-roles header for the <ignore-tenant-role> feature to work.  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. Add the Client Authentication filter
    Add the Client Authentication filter to the System Model, so the x-roles header will be populated and passed to the Authorization filter.
  3. Configure the Authorization filter
    Configure the Authorization Filter by adding the roles in the <ignore-tenant-role> element that you want the filter to pass.

 

The following example shows a section of the authorization configuration that will allow a request from a user with “testRole0” and the “testRole1”to pass.

Optional delegating mode

In some cases, you may want to delegate the decision to authorize a request down the chain to either another filter or to the origin service.

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 filter must be able to communicate with an OpenStack Identity server in order to obtain a client's endpoint list. This configuration element informs the filter on how to contact the OpenStack Identity server, which credentials to use when doing so, and how long to cache the responses from the OpenStack Identity server.

The openstack-authorization.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
<rackspace-authorization>-RequiredSpecifies the sub-elements and attributes to define your client authorization configuration. 
<authentication-server>-RequiredInforms the component on how to contact the OpenStack Identity server, which credentials to use when doing so, and how long to cache the responses from the OpenStack Identity server. 
usernameRequiredUsername for the authentication service that you interact with. 
passwordRequiredPassword for the authentication service that you interact with. 
hrefRequiredNames the href for the authentication service that you interact with. 
tenantIdOptionalDefines the tenant Id for Auth User.  
endpoint-list-ttlOptionalStates time to live used to cache endpoint list responses from the authentication service. This value is in seconds.  
connectionPoolIdOptionalTells 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. 
<service-endpoint>-RequiredInforms the filter of the service endpoint's publicURL which is used to identify whether or not the client's request is authorized. 
hrefRequiredNames the href for the service catalog that you interact with. 
regionOptionalStates the region endpoint for the service catalog. 
nameOptionalStates the name of the endpoint for the service catalog. 
typeOptionalStates the type for the endpoint for the service catalog. 
<ignore-tenant-roles>-OptionalSpecifies the attributes for ignore-tenant-roles. 
ignore-tenant-roleOptional

Specifies the roles that bypass the tenant requirement check.

Implemented in version 6.2.0.2
rolesOptional

Specifies the roles that bypass the tenant requirement check.

Implemented in version 6.2.0.2
<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. 

 

Return codes and conditions

The Client Authorization filter allows the Service Implementer to validate that a client request is allowed. If the request is allowed it is passed without any changes. If the request is disallowed, then the request is denied with a HTTP 500 - Internal Server Error response.

Repose relies on the identity service for two items:

  1. To get an admin token which Repose will use to get the service catalog for tenants.
  2. To get the tenant's service catalog.
When the identity service returns:
Repose passes this response to the client:
This occurs when:

413 Request Entity 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.

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

 

Test suite summary of request headers created

The Client Authorization filter does not create any request headers.

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

Background

Authorization or AuthZ is the process of confirming that you have permission to do what you are asking to do. For example, your authenticated identity might be checked against a list of the services to which you have subscribed. Authorization processes are often used by software  that requires users to register their identities and subscribe to specific services.

A request is considered authorized if any of the endpoints in the client's endpoint list start with the service endpoint associated with the requested component. For example, if an authenticated client requests the compute service, and that client's endpoint list (also known as a service catalog) includes an endpoint for the compute service, then the client is authorized to use the compute service and the client's request is forwarded to the compute service for further processing.