Tokens and Secrets

Using Security Tokens

Security Tokens

Security tokens provide a mechanism to authenticate streaming requests. Each streaming client has a unique token for each asset. This token must be generated by the publishing portal. A token may also have an expiry time. 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.

Secrets

A secret is a string that is shared between the portal and the Director. It must be kept secret from all outside parties. The portal uses the secret for token generation, and the Router uses the same token, and secret, to authenticate client requests.

Configuring Security Tokens

In order to use security token verification there should be:

  • A stored and configured secret.
  • 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 Secret

A secret must be written to a secrets file. The entire file content is the secret, i.e: there is one secret per file.

Edit - or just echo - a well kept secret to a file (trailing whitespace is ignored):

$ echo abrakadabra > /opt/edgeware/acd/router/secrets/sec-1.txt

Configure a secret, referring to the same file name:

$ confcli integration.secrets -w
Running wizard for resource 'secrets'

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

secrets : {
  enabled (default: False): true
  refreshIntervalSeconds (default: 60):
  secretStore : [
    secretStore : {
      id (default: ): sec-1
      type (default: file):
      resourceName (default: ): sec-1.txt
    }
    Add another 'secretStore' element to array 'secretStore'? [y/N]:
  ]
}
Generated config:
{
  "secrets": {
    "enabled": true,
    "refreshIntervalSeconds": 60,
    "secretStore": [
      {
        "id": "sec-1",
        "type": "file",
        "resourceName": "sec-1.txt"
      }
    ]
  }
}
Merge and apply the config? [y/n]: y
  • enabled enables/disables all secrets. Disabling secrets will disable polling of, and access to the resources. It will not disable token verification.
  • refreshIntervalSeconds the interval with which to update the cache. Secrets are cached in RAM for efficient token verification.
  • id is any name. It is important, as it will be referred from the verification.
  • type the type of resource holding the secret. Currently the only supported type is file.
  • resourceName the file path under /opt/edgeware/acd/router/secrets; typycally in the form of secret1.txt. The form account1/secret1.txt is also possible. (Absolute paths, with a leading /, are allowed, but risky since paths inside the Podman container can differ from host paths.)

Secrets from Lua

Secrets are typically used by the built-in token verification, see below. It is also possible to access configured secrets from Lua, in order to implement any other custom verification algorithm.

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):
    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]:
    ]
    algorithm (default: externalToken):
    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,
      "accounts": [
        "account-1"
      ],
      "excludedSessionGroups": [
        ""
      ],
      "algorithm": "externalToken",
      "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.
  • accounts the accounts protected by this token. If no accounts are configured, then verification can still be used by specifying default here.
  • excludedSessionGroups within account certain session groups can be excluded from verification
  • algorithm currently the only supported algorithm is externalToken
  • secretIds a list of secrets. Multiple secrets can be useful during transit from one secret to a new one.