Token Generation

When directing a client to a CDN, the CDN Director can optionally include a token in the redirected request. The CDN uses the token to make sure that the client has permissions to stream the requested content. The token contains information about what the client is allowed to request and is signed with a secret.

The tokens are generated using the “internal tokens” algorithm. Each request gets a unique token.

Internal Tokens

The internal token generation is configured under services.routing.tokens.generation. It has the following options:

• name - The name of this token generation configuration.
• algorithm - Which algorithm to use when generating the tokens. The only supported algorithm is internalToken.
• 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.
• secretId - The ID of the secret that is used for protecting the token. See the Secret Store.
• 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.

Example

If the Director has the following configuration:

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

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

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

The request

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

might cause the client to be redirected to:

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.