Token Verification

The ESB3024 CDN Director can be configured to require that requests from clients contain a token. The purpose of the token is to ensure that the client has permission to stream the requested content. The token contains information about what the client is allowed to request and is signed with a secret. The CDN Director will verify that the token is valid before replying to the request. Requests that fail validation will be rejected with HTTP 403 FORBIDDEN by the CDN Director.

Note: The older way of using Lua-verified tokens is still available, but it is highly recommended to use the method described here.

Prerequisites

In order to use token verification there should be:

• A stored and configured secret. See the Secret Store.
• A configured token verification.

If different accounts need different token verification configurations, accounts need to be configured.

Algorithms

There are two algorithms available for verifying tokens:

• The externalToken algorithm is the standard algorithm used by the ESB3008 Convoy Request Router.
• The luaFunction algorithm lets a Lua function verify the token. This allows for implementing new algorithms and for taking the tokens from locations other than a query parameter.

Default and Overrides

Token verification is configured under services.routing.tokens.verification, which has two parts:

• default - The token verification that applies to every account. This includes the account default, which a request is classified into when it does not match any configured account.
• overrides - A list of token verifications that replace the default for specific accounts.

When a request arrives, the CDN Director looks at the account that the request has been classified into. If an override lists that account, the override is used. Otherwise the default is used.

Since the default covers all accounts, enabling it ensures that no request can avoid verification by being classified into an account that has no token verification configured. An account that should not be verified, for instance one that serves free content, needs an override with enabled set to false.

Initially, the default verification is disabled and the list of overrides is empty, so no tokens are verified.

The following rules apply:

• If the default is disabled, requests to accounts that are not listed in any override are not verified.
• If an override is disabled, requests to the accounts it lists are not verified, even if the default is enabled.
• If an account is listed in more than one override, the last of those overrides is used and the CDN Director logs a message about it. Avoid listing an account in more than one override.

Common Configuration Parameters

The default and the overrides contain some parameters that are common for both algorithms and some parameters that are specific to the chosen algorithm. The common parameters are:

• enabled - Enables or disables a verification.
• algorithm - Which algorithm to use when verifying the tokens. It can be externalToken or luaFunction.
• excludedSessionGroups - Specify session groups that are excluded from verification.
• secretIds - A list of secrets that are associated with this token verification. Multiple secrets can be useful during transit from one secret to a new one.

Each override also has the following parameters:

• name - The name of this override.
• accounts - The accounts that this override applies to.

The default has neither name nor accounts, since it applies to all accounts.

The External Token Algorithm

The externalToken algorithm has the following additional options:

• floatingSessions - Allows sessions to change IP addresses (see below).
• tokenQueryParam - Sets the name of the query parameter in the request URL where the token is located.

Floating Sessions

By default a token is locked to one client IP address. When floating sessions are enabled, the address is not included in the token. This allows sessions to transition between client devices.

The Lua Function Algorithm

The luaFunction algorithm lets the user write Lua code that verifies the token. The token can be located anywhere in the request, it is not limited to a query parameter in the request URL.

It has one additional option:

• luaFunction - The Lua code that verifies the token.

See token verification function for more information.

Examples

The CDN Director has the following base configuration:

confcli integration.secrets
{
    "secrets": {
        "enabled": true,
        "refreshIntervalSeconds": 60,
        "secretStore": [
            {
                "id": "sec-1",
                "type": "file",
                "resourceName": "sec-1.txt"
            }
        ]
    }
}

confcli services.routing.classifiers
{
    "classifiers": [
        {
            "name": "my-streaming-service",
            "type": "hostName",
            "inverted": false,
            "patternType": "stringMatch",
            "pattern": "my-streaming-service.example.com"
        }
    ]
}

confcli services.routing.sessionGroups
{
    "sessionGroups": [
        {
            "name": "my-streaming-service",
            "classifiers": [
                "my-streaming-service"
            ]
        }
    ]
}

confcli services.routing.accounts
{
    "accounts": [
        {
            "name": "my-streaming-service",
            "sessionGroups": [
                "my-streaming-service"
            ]
        }
    ]
}

Verify All Accounts

With the above base configuration applied, the following configuration verifies the tokens of all requests with the externalToken algorithm:

confcli services.routing.tokens.verification
{
    "verification": {
        "default": {
            "enabled": true,
            "floatingSessions": false,
            "algorithm": "externalToken",
            "tokenQueryParam": "token",
            "excludedSessionGroups": [],
            "secretIds": [
                "sec-1"
            ]
        },
        "overrides": []
    }
}

Use a Lua Function for One Account

The following configuration verifies the tokens of requests to the account my-streaming-service with a luaFunction verification, while all other accounts use the externalToken verification from the default:

confcli services.routing.tokens.verification
{
    "verification": {
        "default": {
            "enabled": true,
            "floatingSessions": false,
            "algorithm": "externalToken",
            "tokenQueryParam": "token",
            "excludedSessionGroups": [],
            "secretIds": [
                "sec-1"
            ]
        },
        "overrides": [
            {
                "name": "lua-verification",
                "enabled": true,
                "algorithm": "luaFunction",
                "accounts": [
                    "my-streaming-service"
                ],
                "excludedSessionGroups": [],
                "secretIds": [
                    "sec-1"
                ],
                "luaFunction": "return request_headers['X-Token'] == to_hex_string(hmac_sha256(Secrets[1], request.path))"
            }
        ]
    }
}

Exempt One Account From Verification

The following configuration verifies the tokens of all requests, except the ones to the account my-streaming-service:

confcli services.routing.tokens.verification
{
    "verification": {
        "default": {
            "enabled": true,
            "floatingSessions": false,
            "algorithm": "externalToken",
            "tokenQueryParam": "token",
            "excludedSessionGroups": [],
            "secretIds": [
                "sec-1"
            ]
        },
        "overrides": [
            {
                "name": "free-content",
                "enabled": false,
                "floatingSessions": false,
                "algorithm": "externalToken",
                "tokenQueryParam": "token",
                "accounts": [
                    "my-streaming-service"
                ],
                "excludedSessionGroups": [],
                "secretIds": []
            }
        ]
    }
}

Verify Only One Account

The following configuration verifies the tokens of requests to the account my-streaming-service only. Requests to all other accounts are not verified, since the default is disabled:

confcli services.routing.tokens.verification
{
    "verification": {
        "default": {
            "enabled": false,
            "floatingSessions": false,
            "algorithm": "externalToken",
            "tokenQueryParam": "token",
            "excludedSessionGroups": [],
            "secretIds": []
        },
        "overrides": [
            {
                "name": "verification-1",
                "enabled": true,
                "floatingSessions": false,
                "algorithm": "externalToken",
                "tokenQueryParam": "token",
                "accounts": [
                    "my-streaming-service"
                ],
                "excludedSessionGroups": [],
                "secretIds": [
                    "sec-1"
                ]
            }
        ]
    }
}