Token Generation

When redirecting a client to a CDN, the ESB3024 CDN Director can optionally include a token in the redirected request. The CDN uses the token to make sure 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.

There are two algorithms available for generating the tokens:

• The internalToken algorithm generates tokens that are recognised by the AgileTV streamers.
• The luaFunction algorithm lets a Lua function generate the token. This allows users to implement new algorithms and to place the tokens in locations other than a query parameter.

Common Configuration Parameters

Token generation is configured under services.routing.tokens.generation. The configuration contains some options that are common for both algorithms and some options that are specific to the chosen algorithm. The common parameters are:

• name - The name of this token generation configuration.
• algorithm - Which algorithm to use when generating the tokens. It can be internalToken or luaFunction.
• secretId - The ID of the secret that is associated with this token configuration. See the Secret Store.

The Internal Token Algorithm

The internalToken algorithm has the following additional options:

• variant - The internal token algorithm has three variants: default, withSession and custom. They are described below.
• customFormat - The format to use when the custom variant is selected.
• tokenQueryParam - The name of the query parameter where the token is stored. Default is token.
• defaultStartLimitSeconds - The default lifetime of the internal token. If 0, it will be the same as the session lifetime.
• defaultExpiresSeconds - The default lifetime of the session that will be created by the token.

The lifetimes of the internal token and the generated session are decided by various factors which are not described here. defaultStartLimitSeconds and defaultExpiresSeconds only set their defaults.

Token generation needs to be enabled per host group. This is done by putting the name of the token generation configuration in services.routing.hostGroups.<group>.tokenName.

Default Variant

The default variant can be used together with AgileTV streamers if they are configured to require signatures with the default algorithm.

“With session” variant

The withSession variant is similar to the default algorithm but also includes a session ID that AgileTV streamers recognize.

The withSession algorithm will only work properly if services.routing.hostGroups.<group>.createStreamerSession is set to true. See CDNs and Hosts for more information.

Custom variant

The custom variant allows for greater control of which parameters that are covered by the generated token. It is configured in customFormat, which contains a list of descriptors that start with a % sign. The following descriptors are recognized:

Any text in customFormat that is not a descriptor is copied literally into the token.

The Lua Function Algorithm

The luaFunction algorithm lets the user write Lua code that generates a token and places it in the response that is sent to the client.

It has one additional option:

• luaFunction - The Lua code that generates the token.

See token generation function for more information.

Examples

The CDN Director has the following base configuration:

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

confcli services.routing.hostGroups
{
    "hostGroups": [
        {
            "name": "streamer",
            "type": "host",
            "httpPort": 80,
            "httpsPort": 443,
            "headersToForward": [],
            "queryPassThrough": {
                "policy": "accept",
                "exceptions": []
            },
            "createStreamerSession": true,
            "addUrlPrefix": false,
            "tokenName": "test-token",
            "hosts": [
                {
                    "name": "streamer-interface1",
                    "hostname": "streamer1.example.com",
                    "ipv6_address": "",
                    "healthChecks": []
                }
            ]
        }
    ]
}

The Internal Token Algorithm

Below is an example token generation configuration that uses the internalToken algorithm.

confcli services.routing.tokens.generation
{
    "generation": [
        {
            "name": "test-token",
            "algorithm": "internalToken",
            "variant": "withSession",
            "customFormat": "",
            "secretId": "test-secret",
            "defaultStartLimitSeconds": 0,
            "defaultExpiresSeconds": 86400
        }
    ]
}

With the above configuration, the request

curl https://director1.example.com/film1/index.m3u8

can cause this redirect:

https://streamer1.example.com/session/director1-ba185d-22d0f2c14c3149b4$h1.0$default/film1/index.m3u8?token=352662c2684ce0bfe66bfb6e9561f15f_1782491083_1782491083

The token token=352662c2684ce0bfe66bfb6e9561f15f_1782491083_1782491083 has been appended to the URL.

The Lua Function Algorithm

The example below shows how a Lua function that returns the secret in the X-Secret header can be configured. Note that the secret is not meant to be exposed like this, it is only for illustrative purposes.

confcli services.routing.tokens.generation
{
    "generation": [
        {
            "name": "test-token",
            "algorithm": "luaFunction",
            "luaFunction": "return HTTPResponse({Headers={{'X-Secret', Secret}}})",
            "secretId": "test-secret"
        }
    ]
}

This will cause the request

curl -i https://director1.example.com/film1/index.m3u8

to be redirected without a token in the Location header, but instead in the X-Secret header.

HTTP/1.1 302 Found
Access-Control-Allow-Origin: *
Content-Length: 0
Location: https://streamer1.example.com/session/director1-ba185d-22d0f2c14c3149b4$h1.0$default/film1/index.m3u8
X-Secret: a-secret-password