1. OpenRepose
  2. Home
Search

Valkyrie Authorization Filter

The Valkyrie Authorization filter performs three distinct functions:

  • Per-Device Authorization: Compares the request method with the user’s device permissions to determine whether or not the requested action is allowed.

  • Response Collection Resource Culling: Values from the origin service’s response will be removed based on the user’s device permissions. Consequently, the user may only view items they have permission to view.

    Currently, only JSON bodies are supported. If you would like to request XML support, please contact us!

  • Account Permission to Role Translation: Takes the user’s account level permissions and translates their names into the standard X-Roles and X-Map-Roles headers allowing Role-based access control (RBAC) to be used on the request. This includes translating the user’s device permission for the device specified in the X-Device-Id header (when the request contains one).

Each function is optional, and as many or as few as desired can be used. All functions involve making one or more call(s) to the Valkyrie service to ascertain a user’s permissions. The results of these calls are cached to cut down on the traffic generated by repeat requests.

General filter information

  • Name: valkyrie-authorization

  • Default Configuration: valkyrie-authorization.cfg.xml

  • Released: v7.1.0.2

  • Bundle: repose-filter-bundle

  • Schema

Prerequisites & Postconditions

Required Request Headers

  • X-Contact-Id

  • X-Tenant-Id

  • X-Device-Id (Only required for per-device authorization)

Required Preceding Filters

While there are no preceding filters that are strictly required, the following filters may be useful:

Request Headers Created

  • X-Roles - Only created if this filter is configured to translate-permissions-to-roles. The value of this header will be the names of the user’s permissions.

  • X-Map-Roles - Only created if this filter is configured to translate-permissions-to-roles. The value of this header will be a base 64 encoded JSON map between the presented tenant id and the user’s permissions. If this header already exists the new values will be added to the existing map.

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 roles translated by the Valkyrie filter.

  • API Validator filter - Provides role-based access control to the origin service’s API, making use of the roles translated by the Valkyrie filter.

Response Body Changes

If the collection-resources element is configured, this filter will perform culling on the response body. Culling is used to restrict the data transmitted to the user from the origin service. Technically, culling is the removal of fields from the response body, and the updating of corresponding field counts. Currently, only JSON content is supported.

This filter may also remove the response body if culling cannot be completed successfully. See the [Response status codes] section for more details.

Response Headers Created

  • Retry-After - Only created if this filter is rate limited by the Valkyrie service. See the official HTTP specification for more information about this header.

Response Status Codes

Response Code Reason

401

  • X-Contact-Id or X-Tenant-Id are missing or blank

  • The Valkyrie service returns a 401

403

  • The user is a non-dedicated user (unless pass-non-dedicated-tenant is enabled)

  • The user does not have permission to take the requested action on the requested device

  • The Valkyrie service returns a 403

404

  • When 403 masking is enabled and a 403 would be returned

413

  • The Valkyrie service returns a 413

429

  • The Valkyrie service returns a 429

500

  • The Valkyrie service returns a 400

  • device-id-mismatch-action is configured to fail, and a device ID cannot be parsed

502

  • The Valkyrie service returns a 500

  • There is a problem communicating with the Valkyrie service

503

  • The Valkyrie service returns a 503

For more information about specific response codes that Repose will receive from the Valkyrie service, please refer to the Valkyrie documentataion.

Account Admins

If a user has the account_admin role in Valkyrie, when enable-bypass-account-admin is configured to be true, the Valkyrie filter will pass the request along regardless of whether or not the device permission check fails. Culling will also not be performed when configured in this manner. The Valkyrie filter can add the user’s permissions to the X-Roles header, but it is left to a subsequent filter or the origin service to validate the request.

Examples

Basic Example

This configuration will authorize users against Valkyrie.

valkyrie-authorization.cfg.xml
<valkyrie-authorization xmlns="http://docs.openrepose.org/repose/valkyrie-authorization/v1.0">
    <valkyrie-server uri="http://theserver:8080"/> (1)
</valkyrie-authorization>
1 Specifies the URI of the Valkyrie service.

Full Feature Utilization

This configuration will authorize non-admin users, translate permissions to roles, cull the response, and delegate any failures.

valkyrie-authorization.cfg.xml
<valkyrie-authorization xmlns="http://docs.openrepose.org/repose/valkyrie-authorization/v1.0"
        cache-timeout-millis="300000" (1)
        enable-masking-403s="false" (2)
        enable-bypass-account-admin="false" (3)
        connection-pool-id="valkyrie-auth-pool" (4)
        pass-non-dedicated-tenant="false"> (5)

    <delegating quality="0.9"/> (6)

    <valkyrie-server uri="http://theserver:8080"/> (7)

    <translate-permissions-to-roles/> (8)

    <collection-resources device-id-mismatch-action="fail"> (9)
        <resource>
            <path-regex http-methods="GET"> (10)
                /devices/.* (11)
            </path-regex>
            <collection>
                <json> (12)
                    <path-to-collection>$.values</path-to-collection> (13)
                    <path-to-device-id>
                        <path>$.uri</path> (14)
                        <regex capture-group="1">http://core.rackspace.com/accounts/\d*/devices/(\d*)</regex> (15)
                    </path-to-device-id>
                    <path-to-item-count>$.metadata.count</path-to-item-count> (16)
                </json>
            </collection>
        </resource>
    </collection-resources>

    <pre-authorized-roles> (17)
        <role>admin</role> (18)
        <role>openstack:admin</role>
    </pre-authorized-roles>
</valkyrie-authorization>
1 Specifies the time in milliseconds to cache Valkyrie service responses.
Default: 300000 (5 minutes: 5*60*1000)
2 Specifies whether or not to translate 403 responses to 404 responses.
3 Specifies whether or not to bypass the secondary authorization call. If disabled (false), then a secondary authorization call will be made when a permission of account_admin is found. This has the potential to increase the response time. If enabled (true), then the secondary authorization call is bypassed and no culling of the origin service response will occur.
Default: false
4 Specifies the connection pool to use by ID.
Default: default
5 Specifies whether or not to verify that the X-Tenant-Id header starts with hybrid:. If disabled (false), this filter will verify that the X-Tenant-Id header starts with hybrid: (indicating a dedicated tenant) before making a request to Valkyrie. If the header does not start with hybrid: (indicating a non-dedicated tenant), the request is immediately rejected. If enabled (true), the filter will be skipped for non-dedicated tenants allowing processing to continue.
Default: false
6 Specifies whether or not to send a failing response when an invalid state is reach. If present, the filter will not send a failing response. 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. See DeRP Filter and User Access Events for more details.
7 Specifies the URI of the Valkyrie service.
8 Specifies whether or not to translate Valkyrie account permissions to roles, including the specific device permission for requests including a X-Device-Id header.
9 Specifies the action to take when a null or non-matching JSON value is found where a device ID is expected. See the schema in General filter information for available actions.
10 Specifies which request methods this resource path should enable culling for.
11 Specifies a regular expression. All resources matching this regular expression will having culling enabled.
12 Specifies that the response body will be JSON.
13 Specifies the path to the collection to be culled relative to the document root. In this case, JSONPath is used since the response body will be JSON.
14 Specifies the path to the field containing the device ID relative to an object within the collection.
15 Specifies a regular expression used to extract the device ID from the field specified by the path. Also specifies the capture group within the regular expression which captures the device ID.
16 Specifies the path to the field containing the item count for the collection relative to the document root.
17 Specifies a collection of pre-authorized (admin) roles.
18 Specifies the name of a particular pre-authorized (admin) role.

The enable-bypass-account-admin attribute applies to users with the role permission account_admin as well as requests with a X-Device-Id `header value containing a device ID to which the user has `account_admin device permissions. This could unintentionally bypass culling. A X-Device-Id header should not be added or allowed on requests to endpoints where culling is performed.

Additional Information

This filter utilizes Keystone to authenticate with the Valkyrie service. The X-Auth-Token header will be copied from the inbound request to Repose to the outbound request to the Valkyrie service.