How to add Token Authentication

Token Authentication ("Token Auth") is the process of generating tokens, associating them with an authenticated user session, and then validating the stream using these tokens to prevent unauthorized sharing of links to your content.

Token Auth is based on hybrid tokens generated using a “trusted shared secret” between the content owner and the AMD property. There are two tokens involved:
  • The Access Token: Also referred to as the "short token." This is a one-time access token that signifies that the user session is authenticated. This token is generated by the Origin Server and included as a query string, cookie, or header. You supply the trusted shared secret in this behavior for this token, so that AMD can successfully validate it.
  • The Session Token: Also referred to as the "long token." This token is valid for the duration of the media stream to protect stream elements delivered during the session (For example, this includes media keys, manifests, and segments). Akamai automatically generates the session token after the access token is validated, and can associate it with the stream elements using a cookie or query string in the URL of the stream element. The client returns the session token in the request for each subsequent segment. Clients that lack support for (or have disabled) third-party cookies can authenticate using a query string specific to the user or session. In the case of HLS media, you can add support for "cookie-less" Token Auth.

Token Auth is generally seamless to your end users and requires no player changes. However, cookie-based authentication requires that all stream elements reside on the same domain as the stream manifest.

Where does Token Auth fit into the content protection spectrum?

There are multiple levels of access and protection.

  • No protection: Open Access. Anyone can access you content
  • Level 1: Token Auth.
  • Level 2: Geo Protection. This looks to allow access to requesting clients in geographic regions or IP addresses/CIDR blocks you mark as good, or block access to clients in regions or IP addresses/CIDR blocks you mark as bad. You can add it to your property via the Content - Targeting Protection behavior.
  • Level 3: HTTPS Protection. Configure your AMD property to access and send content via secure delivery.
  • Level 4: Media Encryption. This looks to limit access to your content to only those who have a decryption key. For added protection we recommend that you combine Media Encryption along with Token Auth, via the Segmented Media Protection behavior.
  • Most protection: DRM Encryption. This prevents access to only those clients that have been authorized to have a DRM license for the playback environment or content, including additional rights management rules.

How does Token Auth work?

Below is an overview of the interactions that happen between the media player, product servers, and the origin to enforce the delivery of media via Token Auth.

  1. The player requests the target media. An HTTP request is made for the stream manifest which includes the access token in the cookie, query string, or header consistent with the following syntax:
    <URL>?hdnts=<token>
    Note: Before this step can occur, the Origin Server must have delivered the URL+token to the player. Token generation is discussed in greater detail below.
  2. AMD validates the access token. AMD verifies that the HMAC within the access token is valid and ensures that the token hasn't expired.
  3. AMD validates the session policy. AMD checks that the URL or ACL field of the token provides access to the requested URL, and if the token contains an IP address field, it checks that the request is coming from the expected client IP.
  4. AMD creates the session token. If verification succeeds, the AMD server returns the requested manifest along with a session token:
    <URL>?hdntl=<token>
  5. The player reads the manifest. The player reads the manifest and sends a request for the desired content segment. This request returns the session token sent by AMD in the previous step as a cookie or query string.
  6. AMD validates the session token and playback begins. AMD validates the session token returned by the player and, if validation succeeds, it returns the requested content to the player. This process is repeated for each remaining segment of the content.
  7. The session token expires. With respect to Manifest Manipulation, the Time to Live (TTL) for the token in the session is the duration of the media item that was requested, or one day (86400 seconds), whichever is shorter. Once playback completes, the session token will expire, and the link used to access it is invalidated. With respect to cookie-based authentication, browsers may obtain a subsequent token—valid for 24 hours (86400 seconds)—upon request of a new object from the same domain.
Note: The player does not interact with the cookie token sent in this process. (No additional configuration within your player is required.) The browser application handles the cookie, and the cookie appears transparent to the player. If you're relying on cookie-based authentication for session tokens, the following apply:
  • The targeted hardware or application (browser) on the end-user’s workstation must support cookies
  • Stream elements must reside on the same domain as the stream manifest.