Implement HMAC authentication (Beta)

Authenticate DAI streams using an HMAC-based token

Signature-based authentication allows you to limit DAI content authentication for each stream request based on a specific time and content scope. Instead of a static API key string, this method uses a Hash Message Authentication Code (HMAC) generated using the SHA-256 hash algorithm and an authentication key created in Ad Manager.

Learn how to create an authentication key in Ad Manager.

This feature is in Beta
Features in Beta phase might not be available in your network. Watch the release notes for when this feature becomes generally available.

Build HMAC-based authentication tokens

An authentication token needs to be created dynamically for each stream request. Content scope, time scope, and the authentication signature are set using parameters, separated by tilde (~).

Content scope is slightly different for live linear content and on-demand (VOD) content. Both on-demand and live linear content scope can appear in the same signature, but content will not be authorized unless you include all content scope parameters.

Live linear authentication token format
event=<event-code>,<event-code>~exp=<utc-timestamp>~hmac=<signature>

Video on demand (VOD) authentication token format
cmsid=<content-source>,<content-source>~exp=<utc-timestamp>~hmac=<signature>~vid=<video-id>,<video-id>

Token parameters

Parameter Description
event= Content scope for live linear content
Include a comma-separated list of live stream asset key to authorize. This value is listed as the "Asset key" in the "Settings" tab of each Ad Manager live stream.
cmsid=
vid=

Content scope for video on demand (VOD) content
Include a comma-separated list of content source IDs (cmsid) and video IDs (vid=) to authorize. If a user attempts to access an out-of-scope video ID, even if the content source is permitted, the request is not authorized. If the vid= parameter isn't included, no content is authorized.

exp= Time scope
Include a UTC timestamp, such as "1489680000". Only requests received before the time indicated in the exp parameter are authorized.
hmac=

HMAC signature
Include an authentication signature generated using the SHA-256 hash algorithm, encoded as a HEX string. This signature is generated using all other parameters of the token along with the authentication key created in Ad Manager as the "secret key". Parameters must be arranged in alphabetical order when generating the hashed signature.

For example:

  • Message to encode: event=iYdOkYZdQ1KFULXSN0Gi7g~exp=1489680000
  • Secret key, created in Ad Manager: A7490591290583E4B93189DEE7E287C299FC686872ABC7ADC9F9F536443505F
  • HMAC signature output: 8825640909152B9D1678CD477D8760A8E6727DE02EEE57AD2CB9D72AAFC5D7E7

When the video stream is requested, Ad Manager creates it's own encoded signatures using the parameters in your request and active authentication keys to verify that one matches the signature in your request.

Advanced content scoping

Any of the three content scope parameters (event=, cmsid=, or vid=) can include an asterisk (*) to prefix-match, suffix-match, or match any value. This allows broad access to subsets of content using a single signature.

For example, to grant access to all on-demand videos for a particular content source:

cmsid=<content-source>~exp=<utc-timestamp>~hmac=<signature>~vid=*

Or, to grant access to all live events with event code suffix -free-access:

event=*-free-access~exp=<utc-timestamp>~hmac=<signature>

The most permissive value for any parameter takes precedence, so cmsid=news-*,* matches any source.

Implement your authentication token

After you've built an HMAC-based authentication token, you need to update your application to authorize video streams. The authentication token can be implemented in the Authorization request header or passed as a query string or form data parameter.

Option 1: Use the Authorization request header

To authenticate in the Authorization header of your request, add a token= parameter that contains your HMAC-based authentication token. In addition to the token, other parameters can be added, if needed.

Authorization: DCLKDAI
token="event%3Devent-code1%2Cevent-code2~exp%3D1489680000~hmac%3Dabc123def456"

Option 2: Use a query string or form data parameter

To authenticate within a query string or form data, add an auth-token= parameter that contains your HMAC-based authentication token.

https://dai.google.com/linear/hls/event/<event-code>/master.m3u8?auth-token=event%3Devent-code1%2Cevent-code2~exp%3D1489680000~hmac%3Dabc123def456

https://dai.google.com/ondemand/hls/content/<cmsid>/vid/<video-id>/master.m3u8?auth-token=cmsid%3Dcontent-source1%2Ccontent-source2~exp%3D1489680000~hmac%3Dabc123def456~vid%3Dvideo-id1%2Cvideo-id2

 

If you're using the IMA SDK, you should use streamRequest.authToken to set the token.

Was this helpful?
How can we improve it?