Token Verification

The 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 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 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 account. See Accounts. Note that if a request is not classified to any account, it will be classified to the account name default, even when no accounts are configured.
• A configured token verification.

Configure a Token Verification

Each token verification must be connected to at least one account. After configuring secrets and accounts:

$ confcli services.routing.tokens.verification -w
Running wizard for resource 'verification'

Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string

verification : [
  verification : {
    name (default: ): verification-1
    enabled (default: True):
    floatingSessions (default: False):
    algorithm (default: externalToken):
    tokenQueryParam (default: token):
    accounts <List of account names this token verification applies to. (default: [])>: [
      account (default: ): account-1
      Add another 'account' element to array 'accounts'? [y/N]:
    ]
    excludedSessionGroups <Session groups excluded from token verification. (default: [])>: [
      excludedSessionGroup (default: ):
      Add another 'excludedSessionGroup' element to array 'excludedSessionGroups'? [y/N]:
    ]
    secretIds <List of secret IDs used for token verification. (default: [])>: [
      secretId (default: ): sec-1
      Add another 'secretId' element to array 'secretIds'? [y/N]:
    ]
  }
  Add another 'verification' element to array 'verification'? [y/N]:
]
Generated config:
{
  "verification": [
    {
      "name": "verification-1",
      "enabled": true,
      "floatingSessions": false,
      "algorithm": "externalToken",
      "tokenQueryParam": "token",
      "accounts": [
        "account-1"
      ],
      "excludedSessionGroups": [
        ""
      ],
      "secretIds": [
        "sec-1"
      ]
    }
  ]
}
Merge and apply the config? [y/n]: y

• name any name
• enabled enables disables individual verifications. Disabling a verification temporarily, could be useful during debugging.
• floatingSessions allow floating client IPs. (See below.)
• algorithm currently the only supported algorithm is externalToken
• tokenQueryParam configures a custom query parameter name (other than token) to be used in the request URL.
• accounts the accounts protected by this token. If no accounts are configured, then the verification can still be used by specifying default here.
• excludedSessionGroups within account certain session groups can be excluded from verification
• secretIds a list of secrets. Multiple secrets can be useful during transit from one secret to a new one.

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. To allow this, simply configure:

"floatingSessions": true