Auth Token 2.0 Verification

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

๐Ÿ“˜

Are you using Adaptive Media Delivery (AMD)?

Auth Token 2.0 is supported for use with AMD, but Token Authentication via the Segmented Media Protection behavior is the recommended method for this protection. It provides a higher level of security.

Also, you can't use both behaviors in the same rule in your AMD property. You can use them in separate rules that use different Match criteria.

How it works

This behavior generates unique tokens for use as a query string, a cookie, or in a request header. These tokens are used to validate user requests.

Implementation

Step 1: Enable Token Auth

To start, add the Auth Token 2.0 Verification behavior to the applicable rule in your property, and set the options as necessary:

Option

Required?

Description

Token Location

Yes

Select where the token is located in an incoming HTTP request from the client. Your origin server needs to generate this key and includes it in the applicable location (as a Query String, a Cookie or in a Request Header).

Token Name

Yes

Input the value that will be used as the token_name in the token. (You need to ensure that the value you input here is used when the token is generated.)

Encryption key

Yes

Input a hexadecimal value, comprised of an even number of characters. For example: eee7e9157f81b2f6d471bf2c. You can also click the cycle button () to automatically generate a proper value.
This is the key value you need to use to generate the token for use with your content. Make note of this value for use later in this process.

Action

Yes

Select the desired action to take:

  • **Verify and Deny**. If tokens aren't verified as "matching", a verification error occurs, and the request is denied.
  • **Just Verify**. This sets the verification result in the context and specific actions can be implemented in sub-rules using the [Token Verification Result match](doc:token-ver-result).

Show Advanced Options

No

You can optionally set this slider to On to reveal more options.

Encryption Algorithm

No

To access this option, set the Show Advanced Options slider to On. This is the algorithm you're using for the HMAC (Hashed Message Authentication Code) to generate the token. This setting must match the method chosen in the token generation code.

The algorithms from most to least secure are SHA256, SHA1, and MD5. You shouldn't change the default of SHA256 unless you have a specific reason to do so. For example, you might change it if you have speed requirements or computational limitations on generating tokens at the origin.

Escape token inputs

No

To access this option, set the Show Advanced Options slider to On. Specify whether the token inputs are URL escaped before generating the token. By default, inputs are URL escaped. This setting must match the setting used in your token generation code.

Ignore query string

No

To access this option, set the Show Advanced Options slider to On. Specify whether the query string is included in the URL input into the token. By default, the query string is included. This setting must match the setting used in the token generation code.

Transition key

No

To access this option, set the Show Advanced Options slider to On. Input a second Encryption key to serve as a backup โ€œtrusted shared secretโ€ (either manually input a hexadecimal value, comprised of an even number of characters or auto-generate one using the cycle buttonโ€”(). If the token provided by the user is not valid based on the primary Encryption key, the product checks the token using this key. This ensures that users are not denied access if you are in the process of rotating the primary key. (This assumes that you have transitioned to generating your tokens with the Transition Key for some period of time before updating the Encryption key value here.)

Salt

No

To access this option, set the Show Advanced Options slider to On. Input a value to serve as an additional "secret" that will be added to the token generation to strengthen security of the token. You can either manually input a hexadecimal value, comprised of an even number of characters or auto-generate one using the cycle button ().

๐Ÿšง

Steps 2 and 3 must be performed before enabling a property configuration on the production network that has had Auth Token 2.0 Verification enabled.

Step 2: Generate the access token

You need to generate a one-time access token and apply it to content you want to protect. The token is a delimited list of string fields, with an HMAC to prevent tampering with the strings. Each field consists of a value that is verified by โ€‹Akamaiโ€‹ when a request is made. Among other things, fields in the token include:

String

Description

token_name

Requiredโ€”This must be the same value you input for the Token Name setting in the Auth Token 2.0 Verification behavior for your property configuration.

start_time and end_time

Requiredโ€”Use these to set a time to live for the token.

session_id/sessionId

Optionalโ€”Include this as a unique identifier for a single access session. Create a session identifier using printable ascii characters and ensure that it's no larger than 36 bytes in size.

key

Requiredโ€”The secret used to generate the token. This is the value you set as the Encryption key in the Auth Token 2.0 Verification behavior for your property configuration. (This can also be the Transition key, if applicable, or the Encryption key + Salt/Transition key + Salt if you've set up these optional values in the property.)

๐Ÿšง

Don't include the IP address field in your tokens to tie the token to a specific IP address, unless all requests will only come from that specific address. This can break delivery in a property if requests come from other IP addresses or if you're using an IPv4+IPv6 dual-stacked environment.

โ€‹Akamaiโ€‹ offers Token Auth software development kits (SDK) that you can use to generate this token. They are available for multiple programming languages, and they account for all required and optional fields.

See the README section on these pages for details on how to use the SDKs.

Step 3: Apply the token

The completed token needs to be attached as a query string parameter, cookie, or request header, to the URL for your target content. You must apply it, based on how you've set the Token Location in the Auth Token 2.0 Verification behavior for this property configuration.

Ideally, you should set up your origin server to dynamically generate these tokens for each client request for the content. This way, the IP address could be included as a parameter, and access to the content would be restricted to that single, authorized user.

Tips and best practices

Token authentication generally requires the use of browser cookies to deliver a signed token as a step in the authorization process. This can affect devices and browsers that don't support cookie use (typically Apple Safari and HLS devices).

  • Your end-users can manually enable cookies. Safari end-users must enable cookies. In Safari, set Preferences > Security > Accept Cookies: Always. With this set, no additional interaction is required, and token authorization will work as designed.

Did this page help you?