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.
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>~vid=<video-id>,<video-id>~hmac=<signature>
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 |
Content scope for video on demand (VOD) content |
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 Parameters must be arranged in alphabetical order when generating the hashed signature. Once generated, append the signature to the end of the token using For example:
When the video stream is requested, Ad Manager creates its 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>~vid=*~hmac=<signature>
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~vid%3Dvideo-id1%2Cvideo-id2~hmac%3Dabc123def456
If you're using the IMA SDK, you should use streamRequest.authToken to set the token.