Using a Token

To use the Triton Digital Secure Token, your application needs to do the following:

• Generate a token, containing the desired attributes.

• Securely sign the token, to prevent tampering and re-use.

• Send the token when requesting media or ads.

• Use the token for your desired use case (access control, variable ad load, targeting).

Generating the Token

The token is simply a mechanism to provide additional parameters, similar to query string parameters on a URL, when retrieving media (e.g., a live stream, podcast) or requesting ads. It is built from a series of attributes (i.e., key-value pairs). Some attributes are always required, but others depend on your use case. See the JWT Payload (Claims Set) section for details on the available attributes, their values, and how to format them into a JWT payload.

First, the token has a Protected Header, containing information necessary to identify the token's format and options:

• Token type (always "JWT").

• Signature algorithm (always "HS256").

• Key ID (provided by Triton).

Then, the token has a payload containing the previously mentioned attributes. Which attributes you include in the token depends on your intended use case.

See the JWT Payload (Claims Set) section for technical details. Note that Triton Digital's token mechanism is very flexible, and if your use case requires additional attributes that are not part of this specification, contact us to discuss the addition of new attributes to support your use case.

A token also has a validity period, so the media's URL cannot be re-used after that period has expired. This prevents, for example, unauthorized people from using a token-equipped URL that has been posted to a forum, website, or aggregator without your permission. It is thus suggested that the token be generated right before it is used (for example, when generating your web page linking to your media), and have a validity period that's as short as practical. The longer your token is valid, the longer an unauthorized party can use it.

Signing the Token

Once the token has been generated, it must be signed by a trusted entity to become a valid token. This is done by generating a secure hash, combining the payload to be signed, and a secret key (issued by Triton Digital), according to the JWS (JSON Web Signature) specification. This signature is then appended to the token and will be validated by the server upon reception. Only if the signature matches the payload and the secret key will the values in the payload be considered valid.

By signing the token, it is impossible to tamper with the contents of the token, so unauthorized users cannot bypass any access control or targeting you've set up for your media. As the token's expiration is also part of the signed payload, it is thus impossible to tamper with the expiration.

Protecting the Secret Key

The obvious question the previous section poses is "how do I keep my secret key secret?" As with most cases, the answer is "it depends." As with everything else, protecting a secret key is always a balance between development effort relative to the level of protection you accord to that key.

The criteria that will help you determine the necessary level of protection of your secret key are:

• Prevention of token tampering;

• Expiry of the token to prevent re-use of your media URLs;

• Protecting the secret key against theft by a third-party;

• Identifying users that re-use a URL;

• Ease of implementation.

While there are many ways of implementing protection of the secret key, the most common ways are:

• Client side, in JavaScript, with key in clear text;

• Client side, in JavaScript, with obfuscated key;

• Client side, in a native application (e.g., mobile or desktop application);

• Server side, with a public dynamic web page;

• Server side, with an authenticated web page;

• Server side, using an authenticated service.

There are trade-offs to each alternative, depending on your use case, and the level of protection you need.

In short, all of these methods will protect your token against re-use of your media URLs when a third-party copies your media URLs. Due to the expiry of tokens, it is always necessary to dynamically regenerate the URLs on a regular basis with a fresh token.

The easiest implementation is obviously to embed the secret key in your client-side JavaScript (or application), but this makes it trivial for a third-party to steal the key (simply by viewing your page's source code). They will still need to generate fresh tokens, but it adds a level of difficulty to anyone who wants to directly link to your media without authorization.

The next level of protection is by obfuscating the secret key in your client-side code using a variety of algorithms, each with a different level of protection. This can range from a simple ROT13, all the way to very complex schemes (e.g., BluRay-style DRM). Obfuscating the key thus requires a corresponding level of reverse engineering by third parties wanting to copy your key. As for native applications (mobile or desktop), they procure some level of obfuscation by their very nature, because they require disassembly or debugging of your software to get the key. Finally, remember that your client-side application will itself need to de-obfuscate the key before using it.

As for generating and signing the token server-side (on a public web page), this makes the key impossible to steal. However, a third party can still scrape your web page to obtain the tokenized media URLs. Again, the URLs are protected against re-use, and third-parties will need to re-scrape the URLs every time the token expires.

Finally, the only truly secure way of generating media URLs is behind an authenticated server-side service or web page. This ensures that only identified users can get the tokenized media URLs. Also, if you embed the user's ID in the token (with the "sub" attribute), it is possible to identify any user that leaks the media URLs.

The following table is an overview of the pros and cons of these alternative:

Sending the Token

Refer to the specification for the service where the token will be provided for details about how to send the token. This is typically done via a query-string parameter on the HTTP URL of the service.

Using the Token

Once a valid signed token has been added to your service’s URL, the server will validate the token to ensure that it has not expired, and has a valid signature (meaning that the correct secret key was used, and the token's payload was not tampered with).

Finally, depending on the configuration of the service, the contents of the token (the attributes you provided when generating the token) can be used to perform the actions and rules explained previously:

• access control;

• varying the ad load;

• ad targeting.

Triton Digital will configure the service to support your specific use case.

Use-case Example: Prevent Stitching Pre-rolls in Podcasts

This use-case example describes an unusual case for on-demand publishers who want to use live, on-demand pre-roll ads with podcasts instead of the typical case where pre-roll ads are stitched to podcasts. It is only relevant for publishers who:

• Have full control of the podcast distribution via their app or web player (i.e., it is not appropriate for podcasts that are distributed via iTunes or similar channels);

• Confine the podcast distribution to streaming mode (i.e., do not allow download of the podcast for later listening);

• Wish to have control over where the pre-roll ad comes from;

• Wish to ensure, and have proof that, the on-demand pre-roll ad is played (and presumably heard by the listener).

Use the Secure Token to control pre-roll ad insertion so that pre-rolls are inserted on-demand, when the podcast is requested, instead of being stitched into the podcast. Doing so calls the ad as a separate file from the podcast and reports the impression immediately, instead of having a single audio file that contains both the ads and the podcast content.

To achieve this, add the td-ads key to the player or app's Secure Token payload, using either the none or nopreroll value. (none = no ad stitching at all; nopreroll = no preroll stitching, but mid-roll and post-rolls can be stitched in the usual manner.)

Result: pre-roll ads are not stitched, but can be inserted on-demand.

Next, configure your podcast as if it were any other on-demand program; apply the Tap campaigns with pre-roll ad flights, etc.