Enable Token Authentication

To enable Token Authentication ("Token Auth"), you need to apply specific settings in the Segmented Media Protection behavior in your AMD property.

Set up Token Auth

  1. Set the Token Authentication slider to On.

  2. Set the Encryption Key. Enter a hexadecimal value to serve as a "trusted shared secret." Comprise it of an even number of characters, but don't exceed 32 total characters. For example: "eee7e9157f81b2f6d471bf2c". You can also click the cycle button ( ) to automatically generate a proper value.

  3. Make note of this value. You use this value as the Key when generating the token.

  1. Don't enable your AMD property on the production network, or test it on staging just yet. Review the optional features you can add to your property, below. Then, you need to generate a token and apply it to your content.

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

Use this 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, and it's not used to generate the salt.

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

HeaderDescription

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 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.

📘

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 a 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 from 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 the long token validation fails, validation falls back to the short token, if present.

The Query String, the URL Path, or the Request Header

Same as above.

Failure. An HTTP 403 error is returned if long token validation fails.

Add Field Carry-Over

Use these options to enable the security controls and fields you want to be carried over from the access token into the session token. These allow for better access control and analysis.

Review this information to determine if including a field benefits your delivery.

FieldDescriptionBenefit/Drawback

Session-Id (Enabled by default)

Enable this to carry-over the session_id from the access token to the session token.

This allows for tracking and counting unique playback sessions for a URL that is protected by a session token.

📘

This needs to remain enabled if you want to use Token-based Access Revocation.

Data/Payload

Once enabled, information is carried over from the data/payload field in the access token to the session token.

This allows access to opaque data for log analysis for a URL that is protected by a session token.

IP

Once enabled, the ip field is carried over from the access token to the session token. This limits access to requesting client access to the specific ip address included in the token.

Only enable this if the IP address used by the player will not change during the playback session. For example, if you're working with mobile clients, they may switch from Wi-Fi to cellular (or vice versa), so the IP address for that device would vary during playback. So, you probably wouldn't want to enable this field for carry-over.

ACL

Once enabled, the acl field is carried over from the access token to the session token. This limits requesting client access to the specific URL or path set in the acl field.

Only enable this if the base path for the master playlist and the variant/bitrate playlists and segments are the same. Playback can fail if this is not the case.

Add "cookie-less" token auth

During the token auth process, multiple tokens are created and exchanged between the requesting client (your media player) and ​​Akamai​. The token auth feature creates one of these tokensa session tokenand by default, it's returned to the player as an HTTP cookie. However, some devices and browsers don't support cookies.

To address this, we offer "cookie-less" token auth. Rather than sending the session token as a cookie, AMD modifies your manifest file to embed this token in the URL path of requests for media segments. So, once cookie-less token auth is enabled, a browser or device only needs to support fetching objects through HTTP.

Add this for DASH streams

📘

DASH support is Limited Availability

Cookie-less token auth for DASH is only available to selected customers. Talk to your ​Akamai​ account team to see if you're eligible.

  1. Set up Token Authentication.
  2. Contact your ​Akamai​ account team. They need to manually set a specific variable in your AMD property to enable support for DASH streams.
  3. Review the caveats and known issues before you go live with your AMD property.

Add this for HLS streams

  1. Set up Token Authentication.

  2. In the Token Authentication Additions for HLS options, set Token in URI to On.

  3. Enter the names of relevant manifest files in Master Manifest Files. You can add or remove filenames as necessary.

    • HLS manifest file names are included. Various common file names that represent HLS Master Manifest files are automatically added.
    • Filenames can contain alphanumeric and dot characters.
    • You can use wildcards in a filename. Use an asterisk to serve as a wildcard to establish a range of filenames.
    • Ensure that the filenames you input can be differentiated from the variant manifest files.
  1. Review the caveats and known issues before you go live with your AMD property.

Caveats and known issues

The following limitations apply to the use of the Token in URI functionality:

LimitationDetail

DASH stream issues with SegmentBase and SegmentList format manifest files

The format of your DASH manifest file can impact support for cookie-less token auth:

  • SegmentTemplate. This format is fully supported.
  • SegmentBase. This format isn't supported if you're also using Media Encryption for DASH. Media encryption doesn't support this format and it's applied before token auth in the request queue. So, if you enable both, requests will be met with a 400 Bad Request. You can use SegmentBase format if you’re not using Media Encryption.
  • SegmentList. This format isn't supported for use. If your manifest uses this format, your content will still be distributed through your AMD property, but cookie-less token auth won't be applied. This format is also not recommended by the DASH-IF.

DASH live streaming media can't use strict token mode

Strict token mode (via_query_string_strict) requires a short token, which has a shorter duration. Live playback continuously requests the manifest, roughly every 30 seconds. A short token won't be valid during the duration of the live stream. VOD traffic supports both non-strict and strict token modes. Talk to your ​Akamai​ account team for help with this.

HLS streams that don't incorporate a master manifest are not supported

This shouldn't be an issue, due to the nature of an adaptive bitrate stream. These streams already include renditions in different bitrates, resolutions, and codecs, and this information is communicated in the master manifest.

Media Encryption from Origin is not supported

If your media is pre-encrypted on your origin, you can't use cookie-less token auth. Since the content is already encrypted, your manifest and the URLs that cookie-less token auth uses can't be updated to include the token.

Absolute segment URLs for HLS segments are not supported

This function modifies the master manifest to embed the session token in the URL of the media playlists. So, the media/variant playlist must use relative segment URLs. (The session token cascades down to the segments.) This reduces overall cost and results in better performance. However, the URLs for the segments must be relative in the bit rate manifest file. The following segment types are affected:

  • Media segments
  • Ad segments
  • Media initialization segments for HLS (This applies to the ones that are indicated via the #EXT-X-MAP tag.)

Generally, this shouldn't be a concern because the bitrate manifest and its corresponding segments are traditionally served from the same origin.

Multi-CDN is not supported, and other delivery configurations are limited

As a request comes in, this feature updates your manifest file, and subsequent URLs for playlists and segments are updated with the token. This is all unique to edge servers in the ​Akamai​ content delivery network (CDN). The feature can’t be applied in other CDNs.

You also can’t have your AMD property leverage delivery of these assets through a different ​AMD property if cookie-less token auth is disabled in that property.

Accommodate for multiple ​Akamai​​-served hostnames

If your manifests have multiple ​​Akamai​​-served hostnames in their contents, the encryption key(s) need to be the same across each one.