This guide explains how to generate a token, and the required and optional fields for tokens.
To create a token, you compose a string to sign, which we refer to as a signed value in this guide. The signed value includes parameters that describe the content you are protecting, the expiration time of the signed value, and so forth.
You use the signed value while creating a token string. You create a token string by composing the parameters for the token, such as a symmetric-key hash-based message authentication code (HMAC) of the signed value.
Media CDN uses the final composed token to help protect your content.
Create a token
Create a signed value by concatenating a string that contains the required token fields and desired optional token fields. Separate each field and any parameters with a tilde
~
character.Sign the signed value with either an Ed25519 signature or a symmetric-key HMAC.
Compose the token by concatenating a string that contains the required token fields and optional token fields. Separate each field and any parameters with a tilde
~
character.When composing the token, the values for each of the parameters are the same between the signed value and the token string, with the following exceptions:
FullPath
Headers
The following code sample shows how to programmatically create a token:
Python
To authenticate to Media CDN, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
To authenticate to Media CDN, set up Application Default Credentials.
For more information, see
Set up authentication for a local development environment.
Java
The following sections describe the fields used by tokens.
Required token fields
The following fields are required for every token:
Expires
- One of any of the following:
PathGlobs
URLPrefix
FullPath
- One of either of the following:
Signature
hmac
Unless otherwise specified, parameter names and their values are case-sensitive.
The following table explains each parameter:
Field name / aliases | Token parameters | Signed value |
---|---|---|
|
Integer seconds that have elapsed since the Unix epoch (1970-01-01T00:00:00Z) | Expires=EXPIRATION_TIME , after which the
token is no longer valid. |
|
A list of up to five path segments to grant access to. The segments
can be delimited by either commas (
Path parameters, denoted using semicolons ( For these reasons, ensure that your URL does not contain the following
special characters: |
PathGlobs=PATHS |
URLPrefix |
A web-safe base64 encoded URL including the protocol
For example, some valid URLPrefix values for `https://example.com/foo/bar.ts` are `https://example.com`, `https://example.com/foo`, and `https://example.com/foo/bar`. |
URLPrefix=BASE_64_URL_PREFIX |
FullPath |
None. When specifying FullPath in a token, don't duplicate
the path you specified in the signed value. In a token, include the field
name without an = . |
FullPath=FULL_PATH_TO_OBJECT |
Signature |
A web-safe base64 encoded version of the signature. | Not applicable |
hmac |
A web-safe base64 encoded version of the HMAC value. | Not applicable |
PathGlobs
wildcard syntax
The following table explains PathGlobs
wildcard syntax.
Operator | Matches | Examples |
---|---|---|
* (asterisk) |
Matches zero or more characters in the URL's path, including
forward slash (/ ) characters.
|
|
? (question mark) |
Matches a single character in
the URL's path, not including forward slash (/ )
characters.
|
/videos/s?main.m3u8 matches
/videos/s1main.m3u8 . It doesn't match either of
/videos/s01main.m3u8 or /videos/s/main.m3u8 .
|
Globs must start with either an asterisk (*
) or a forward slash (/
)
for URL paths.
Because *
and /*
match all URL paths, we don't recommend
using either in your signed tokens. For maximum protection,
ensure that your globs match the content that you intend to grant access to.
Optional token fields
Unless otherwise specified, parameter names and their values are case-sensitive.
The following table explains parameter names, any aliases, and details for optional parameters:
Field name / aliases | Parameters | Signed value |
---|---|---|
|
Integer seconds since the Unix epoch (1970-01-01T00:00:00Z) | Starts=START_TIME |
IPRanges |
A list of up to five IPv4 and IPv6 addresses in CIDR format for
which this URL is valid in web-safe base64 format. For example,
to specify the IP ranges "192.6.13.13/32,193.5.64.135/32", you specify
IPRanges may not be helpful to include in tokens when clients are
at risk of WAN migrations or cases where the network path to your
application frontend is different than the delivery path.
Media CDN rejects clients with an The following are cases that may result in Media CDN
rejecting clients with an
All of these factors can contribute to a given client having a
non-deterministic IP address during a video playback session. If the
client IP address changes after you have issued access, and the
client attempts to then download a video segment into their playback
buffer, they receive an |
IPRanges=BASE_64_IP_RANGES |
|
An arbitrary string, useful for logs analysis or playback tracing. To avoid creating an invalid token, use %-encoded or web-safe
base64-encoded strings. The following characters must not be used for
|
SessionID=SESSION_ID_VALUE |
|
An arbitrary string, useful for logs analysis. To avoid creating an invalid token, use %-encoded or web-safe
base64-encoded strings. The following characters must not be used for
|
data=DATA_VALUE |
Headers |
A comma-delimited list of header field names. Header names are case-insensitive for lookups in the request. Header names in the signed values are case-sensitive. If a header is missing, the value is the empty string. If there are multiple copies of a header, they're comma-concatenated. | Headers=HEADER_1_NAME=HEADER_1_EXPECTED_VALUE,
HEADER_2_NAME=HEADER_2_EXPECTED_VALUE |
Examples
The following sections show examples for generating tokens.
Example using FullPath
Consider the following example using the FullPath
field:
- Item requested:
http://example.com/tv/my-show/s01/e01/playlist.m3u8
- Expiration time: 160000000
The signed value is:
Expires=160000000~FullPath=/tv/my-show/s01/e01/playlist.m3u8
To create a token, sign the signed value with either an Ed25519 signature or a symmetric-key HMAC.
The following are example tokens created from a signed value:
Ed25519 signature
Expires=160000000~FullPath~Signature=SIGNATURE_OF_SIGNED_VALUE
Where SIGNATURE_OF_SIGNED_VALUE is the ED25519 signature of the signed value previously created.
Symmetric-key HMAC
Expires=160000000~FullPath~hmac=HMAC_OF_SIGNED_VALUE
Where HMAC_OF_SIGNED_VALUE is the symmetric-key HMAC of the signed value previously created.
In the preceding examples, FullPath
is provided in the token, but the value
isn't repeated from the path specified in the signed value. This lets you to
sign the full path of the request without duplicating the request in the token.
Example using URLPrefix
Consider the following example using the URLPrefix
field:
- Item requested:
http://example.com/tv/my-show/s01/e01/playlist.m3u8
- Expiration time: 160000000
The signed value is:
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4
In the preceding example, we replaced the path to the requested item,
http://example.com/tv/my-show/s01/e01/playlist.m3u8
with the path to the item
in web-safe Base64 format,
aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4
.
To create a token, sign the signed value with either an Ed25519 signature or a symmetric-key HMAC.
The following are example tokens created from a signed value:
Ed25519 signature
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~Signature=SIGNATURE_OF_SIGNED_VALUE
Where SIGNATURE_OF_SIGNED_VALUE is the ED25519 signature of the signed value previously created.
Symmetric-key HMAC
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~hmac=HMAC_OF_SIGNED_VALUE
Where HMAC_OF_SIGNED_VALUE is the symmetric-key HMAC of the signed value previously created.
Example using Headers
Consider the following example using the Headers
field:
- Item requested:
http://example.com/tv/my-show/s01/e01/playlist.m3u8
- Expiration time: 160000000
- PathGlobs value:
*
- Expected request headers:
user-agent: browser
accept: text/html
The signed value is:
Expires=160000000~PathGlobs=*~Headers=user-agent=browser,accept=text/html
To create a token, sign the signed value with either an Ed25519 signature or a symmetric-key HMAC.
The following are example tokens created from a signed value:
Ed25519 signature
Expires=160000000~PathGlobs=*~Headers=user-agent,accept~Signature=SIGNATURE_OF_SIGNED_VALUE
Where SIGNATURE_OF_SIGNED_VALUE is the ED25519 signature of the signed value previously created.
Symmetric-key HMAC
Expires=160000000~PathGlobs=*~Headers=user-agent,accept~hmac=HMAC_OF_SIGNED_VALUE
Where HMAC_OF_SIGNED_VALUE is the symmetric-key HMAC of the signed value previously created.
In the preceding examples, Headers=user-agent,accept
is provided in the token,
but the expected header values aren't repeated from the signed value. This lets
you sign specific request header key-value pairs without duplicating the values
in the token.