You can set Advanced Options

Click the Show Advanced Options switch button to reveal additional options.



Transition key

This serves as a backup “trusted shared secret.” Input one manually or auto-generate one using the cycle button—. If the token provided by the end-user request is not valid based on the primary Encryption Key, AMD checks the token using this key. This ensures that users aren't denied access if you're rotating the primary key. (This assumes that you've transitioned to generating your tokens with the Transition Key for some period of time before updating the Encryption key value here.)

Salt

This adds an additional "input" during generation of the token to strengthen security. Manually input a value or auto-generate one using the cycle button (). As a best practice, don't override the default value.

Request Headers for Session Token Salt

This allows you to include additional end-user specific properties to strengthen the relationship between the session token and playback session. These properties are communicated via a salt value that AMD generates using various request headers that you specify here. The following apply to these headers:

  • Each header name you specify must consist of alphanumeric characters or hyphens.
  • A specified header must exist in player requests for your content to be used in the salt.
  • If a header is included in a request and it's not specified here, it's ignored. (It's not used to generate the salt.)

Typical values include what's discussed in the table that follows.

Header Description
User-Agent The resulting session token-protected URL can't be shared and played on a device with a different User-Agent (OS/Browser).
X-Playback-Session-Id The following apply to the resulting session token-protected URL:
  • It can't be shared and played on two identical Apple devices or browsers.
  • It can't be shared and played between Apple and non-Apple devices, and vice versa. (This is similar to the User-Agent header.)
Origin The resulting session token-protected URL can only be played by a Javascript based player from your intended website (for example, hls.js).
Note: Use either Salt or Request Headers for Session Token Salt, but not both. If you do define both, the Salt is used, and what is set for Request Headers for Session Token Salt is ignored.

Salts and Long Token Validation

Token Auth verifies the long token found in an HTTP cookie, even if the current request is for an HLS master manifest. This is because the system can't recognize an .m3u8 file as either a master or variant playlist file. This can result in some corner case issues:

  • The long token can be invalidated by a browser update. The HTTP cookie that holds the long token has a time to live (TTL) of 24 hours. If a browser updates between two consecutive playback sessions during this TTL, the long token is invalidated because there's a different string in the User-Agent request header.
  • Using "Request Headers for Session Token Salt" can invalidate the long token. If you use this option, you're incorporating request headers that can change frequently between consecutive playback sessions. If this happens, the long token in an HTTP cookie may be invalid.

We've implemented a fix for these cases. When the long token is read form the HTTP cookie and the verification fails, the system falls back to the short token for verification. However, if the long token is read from any other source, and the long token verification fails, the system continues to deny the request with an HTTP 403.

Where was the long token read from for the incoming request? How is your "Salt" set up? Long Token Validation Result
The HTTP cookie
  • I used the "Salt" field: You've defined a unique value to serve as your Salt.
  • I used the "Request Headers for Session Token Salt" field: You've set up one or more request headers for use in creating the Salt. (The defaults are User-Agent, X-Playback-Session-Id and Origin.)
  • I have a legacy implementation: The User-Agent request header is set up for you to generate the Salt.
 Fallback: If long token validation fails, validation falls back to the short token, if present.
The Query String Same as above. Failure: An HTTP 403 error is returned if long token validation fails.
The URL Path Same as above. Same as above.
The Request Header Same as above. Same as above.