1. OpenRepose
  2. Home
Search

Keystone v2 Authorization Filter

The Keystone v2 Authorization Filter authorizes requests based on data about the user making the request.

General filter information

  • Name: keystone-v2-authorization

  • Default Configuration: keystone-v2-authorization.cfg.xml

  • Released: v8.8.0.0

  • Bundle: repose-filter-bundle

  • Schema

Prerequisites & Postconditions

Required Request Headers

The following headers are expected to be populated by the Keystone v2 Filter.

  • X-Map-Roles

  • X-Catalog (Only required for endpoint authorization)

  • X-Tenant-Id (Configurable, and only required for tenant authorization if configured to extract the tenant from a header)

Required Preceding Filters

This filter expects that the Keystone v2 Filter precede it to populate necessary user data. Be aware, however, that the necessary user data is transported via request header, and thus, could could be populated elsewhere.

It is best practice to prevent spoofing by putting the Header Normalization filter before any authentication and/or authorization filters so that it can remove any headers that would be populated by them.

Request Headers Created

The following headers are created:

  • X-Tenant-Id - The Tenant ID’s for the user. This header will only be added if this filter is configured to validate tenants. If this header already exists, this filter will either add the matching tenant to the header value or replace the header value with just the matching tenant depending on how this filter is configured.

  • X-Roles - Identifies roles (e.g., admin, user). This header will be always be added with a value of all of the user’s roles associated with the validated tenant. If no tenant has been validated, then all user roles will be added to this header. If this header already exists, it will be replaced.

  • X-Map-Roles - The tenant-to-roles mapping for the user’s tenants which are validated and roles associated with those tenants. This header will not be modified if the send-all-tenant-ids configuration attribute is set to true. This header is a base 64 encoded JSON map of strings to arrays of strings (e.g., the base 64 encoding of {"someTenant": ["someRole", "sharedRole"], "otherTenant": ["otherRole", "sharedRole"]}). Roles without a tenant association will be mapped to the repose/domain/roles key (e.g., {"repose/domain/roles": ["tenantlessRole"]}).

  • X-Identity-Status - Indicates if identity has been confirmed. Identity is considered to be confirmed if authorization succeeds. Possible values are Confirmed and Indeterminate.

If delegation is enabled, then the X-Delegated header is created. This is mainly intended for use by the Highly Efficient Record Processor (HERP) filter and Delegation Response Processor (DeRP) filter for internal delegation processing within Repose. However, it can be exposed to the origin service under certain configurations.

Request Body Changes

This filter does not modify the request body.

This filter is not strictly required by any other filters. However, the following filters may be useful:

  • Simple RBAC filter - Provides role-based access control to the origin service’s API, making use of the culled X-Roles and X-Map-Roles headers.

  • API Validator filter - Provides role-based access control to the origin service’s API, making use of the culled X-Roles and X-Map-Roles headers.

Response Body Changes

This filter does not modify the response body.

Response Headers Created

This filter does not create/modify any response headers.

Response Status Codes

Table 1. Status Codes
Status Code Reasons

401

Tenant ID validation fails because the request tenant ID does not match any tenant ID in the user data.

403

Endpoint validation fails because the user data does not contain a required endpoint.

500

Valid user data (i.e., tenant-to-roles map and endpoint data) was not found in the request. The most likely cause is that the Keystone v2 Filter had not been set up correctly. Note that the set-roles-in-header and set-catalog-in-header attributes must be set to true for the tenant-to-roles map and endpoints to be forwarded respectively.

Examples

Tenant Validation

This configuration will validate the tenant ID(s) in the request against the tenant ID(s) in the user data. All tenants extracted from the request must have at least one matching tenant in the user data.

keystone-v2-authorization.cfg.xml
<?xml version="1.0" encoding="UTF-8"?>
<keystone-v2-authorization xmlns="http://docs.openrepose.org/repose/keystone-v2/v1.0">
    <tenant-handling (1)
        send-all-tenant-ids="true"> (2)

        <validate-tenant (3)
            strip-token-tenant-prefixes="/foo:/bar-" (4)
            enable-legacy-roles-mode="false"> (5)

            <uri-extraction-regex>.*/servers/([-|\w]+)/?.*</uri-extraction-regex> (6)
            <uri-extraction-regex>.*/clients/([-|\w]+)/?.*</uri-extraction-regex>
            <header-extraction-name>x-expected-tenant</header-extraction-name> (7)
            <header-extraction-name>x-other-tenant</header-extraction-name>
        </validate-tenant>

        <send-tenant-id-quality (8)
            default-tenant-quality="1.0" (9)
            uri-tenant-quality="0.7" (10)
            roles-tenant-quality="0.5"/> (11)
    </tenant-handling>
</keystone-v2-authorization>
1 A container for functionality pertaining to tenant handling.
2 Indicates if all the Tenant IDs from the user and the roles the user has should be sent or not.
Default: false
3 If included, then the user will be authorized if and only if the user data contains a tenant ID matching the tenant ID extracted from the request.
4 A / delimited list of prefixes to attempt to strip from the Tenant ID in the token response from the Keystone v2 Identity service. The post-strip Tenant ID is only used in the Tenant Validation check.
5 If in legacy roles mode, then all roles associated with a user token are forwarded. If NOT in legacy roles mode, then roles which aren’t tied to the tenant provided in the request will NOT be forwarded UNLESS the user has a pre-authorized role.
Default: false
6 Declares that a tenant ID should be extracted from the request URI. A Java Regular Expression with at least one capture group. The first capture group must be around the portion of the URI to extract the Tenant ID from for validation.
7 Declares that a tenant ID should be extracted from the x-expected-tenant header in the request.
8 If this element is included, then include Quality parameters on all the tenant ID headers sent.
9 The default tenant has the highest quality by default. Since this filter does not set the default tenant, this value is not currently used by the this filter.
Default: 0.9
10 Followed by matching request tenants by default (if any).
Default: 0.7
11 Followed by the tenants from the roles by default. Since this filter does not set the roles tenants, this value is not currently used by the this filter.
Default: 0.5 
[WARNING]
====
The `uri-extraction-regex` attribute is considered deprecated.
Consider using the <<url-extractor-to-header.adoc#, URL Extractor to Header Filter>> instead.
====

Endpoint Validation

This configuration will validate that the user data contains a configured endpoint.

keystone-v2-authorization.cfg.xml
<?xml version="1.0" encoding="UTF-8"?>
<keystone-v2-authorization xmlns="http://docs.openrepose.org/repose/keystone-v2/v1.0">
    <require-service-endpoint (1)
        public-url="https://service.example.com" (2)
        region="ORD" (3)
        name="OpenStackCompute" (4)
        type="compute"/> (5)
</keystone-v2-authorization>
1 If included, then the user will be authorized if and only if the user data contains an endpoint matching the configured endpoint.
2 Public URL to match on the user’s endpoint.
3 Region to match on the user’s endpoint.
4 Name of the service to match in the user’s endpoint.
5 Type to match in the user’s endpoint.

Whitelisting URIs

You can configure this filter to allow no-op processing of requests that do not require authorization. For example, a service might want all calls authorized with the exception of the call for WADL retrieval. In this situation, you can configure the whitelist as shown in the example below. The whitelist contains a list of Java Regular Expressions that Repose attempts to match against the full request URI. If the URI matches an expression in the white list, then the request is passed to the origin service. Otherwise, authorization is performed against the request.

keystone-v2-authorization.cfg.xml
<?xml version="1.0" encoding="UTF-8"?>
<keystone-v2-authorization xmlns="http://docs.openrepose.org/repose/keystone-v2/v1.0">
    <white-list>
        <uri-regex>/application\.wadl$</uri-regex> (1)
    </white-list>

    <tenant-handling>
        <validate-tenant>
            <header-extraction-name>x-expected-tenant</header-extraction-name>
        </validate-tenant>
    </tenant-handling>
</keystone-v2-authorization>
1 The Java Regular Expression to allow matching URI’s to pass without requiring authorization.

Pre-authorized Roles

Pre-authorized roles can be configured to allow a user to bypass authorization if the user data contains a role matching one of the pre-authorized roles.

keystone-v2-authorization.cfg.xml
<?xml version="1.0" encoding="UTF-8"?>
<keystone-v2-authorization xmlns="http://docs.openrepose.org/repose/keystone-v2/v1.0">
    <pre-authorized-roles> (1)
        <role>racker</role> (2)
    </pre-authorized-roles>

    <tenant-handling>
        <validate-tenant>
            <header-extraction-name>x-expected-tenant</header-extraction-name>
        </validate-tenant>
    </tenant-handling>
</keystone-v2-authorization>
1 Contains pre-authorized roles.
2 Defines a role for which authorization is not performed.

Delegation

In some cases, you may want to delegate the decision to reject a request down the chain to either another filter or to the origin service. This filter allows a request to pass as either Confirmed or Indeterminate when configured to run in delegating mode. To place the filter in delegating mode, add the delegating element to the filter configuration with an optional quality attribute that determines the delegation priority. When in delegating mode, the filter sets the X-Identity-Status header with a value of Confirmed when a user has been authorized by the this filter and to Indeterminate when a user was not authorized by this filter. The the X-Identity-Status header is in addition to the regular X-Delegated delegation header being created.

keystone-v2-authorization.cfg.xml
<?xml version="1.0" encoding="UTF-8"?>
<keystone-v2-authorization xmlns="http://docs.openrepose.org/repose/keystone-v2/v1.0">
    <delegating quality="0.7"/>  (1) (2)

    <tenant-handling>
        <validate-tenant>
            <header-extraction-name>x-expected-tenant</header-extraction-name>
        </validate-tenant>
    </tenant-handling>
</keystone-v2-authorization>
1 If this element is present, then delegation is enabled. Delegation will cause this filter to pass requests it would ordinarily reject along with a header detailing why it would have rejected the request.
2 Indicates the quality that will be added to any output headers. When setting up a chain of delegating filters the highest quality number will be the one that is eventually output to the logging mechanisms.
Default: 0.7