Generating Tokens

You should upgrade to Token-Based Authentication 3.0.
Learn more.

A factor that plays into the strength of a token value is the encryption key.
View best practices for defining an encryption key.

A token value is required to access all content protected by Token-Based Authentication. Before you can assign a token value to a link, you will need to generate it with the desired requirements. When generating a token, keep in mind that there is no limit to the number of parameters that can be combined. In other words, a token value can consist of a single or multiple parameters. Additionally, you should also keep in mind that certain parameters support multiple values. This permits a lot of flexibility when determining the requirements that must be met prior to content delivery.

Although there is no limit to the number of parameters that can be combined to form a token, there is a limit of 512 characters for the total length of a token. In order to prevent your clients from being inadvertently denied access to your content, please ensure that your token values never exceed 512 characters.

Generating tokens will not affect your Token-Based Authentication configuration in any way. Additionally, there is no limit to the number of token values that may be generated for a particular encryption key.

A token can be generated via:

• Our MCC
• Our Token Generator application (ectoken3)
• A custom script or application

Token values are not inherently folder or platform-specific. This means that a user that satisfies a token’s requirements can use that token to retrieve content from any protected folder that has been associated with the encryption key used to generate it, as long as the token’s requirements are not specific to that path or asset. This type of configuration makes it possible to gain access to protected content from various folders across different platforms.

Manually Generating a Token

An individual token value may be generated through the MCC. This can be accomplished through the Encrypt Tool section of the Token Auth page. The sole purpose of this section is to generate a token value based on either the primary or backup key.

The Encryption Version option determines whether tokens are encrypted using version 2.0 or 3.0. You should upgrade to Token-Based Authentication 3.0.
Learn how to upgrade.

To manually generate a token

1. Review the available parameters.
2. Assign a value to each parameter that a client must meet before content may be delivered.
3. From the Key to Encrypt option, select the desired encryption key.
4. From the Encryption Version option, select the desired version. The recommended encryption version is 3.0.
5. Click Encrypt to generate a token specific to the selected key. This token value will appear next to the Generated Token label.

6. Modify the desired request to include the above token value as a query string.

   Example:

   http://cdn.mydomain.com/sales.pdf?1234567890abcdefghijklmnop

Using Our Token Generator Application

An alternative method for generating token values is to use the Token Generator application. This application provides the means to generate tokens using a script. The advantage of this approach is that it allows token values to be tailored to content.

The Token Generator application includes the following components:

• Windows executable
• Linux binaries

The Windows version of our executable requires BouncyCastle.Crypto.dll and Blowfish.dll. Please make sure that these assets are stored in the same folder as the encryption executable.

The proper syntax for specifying a single parameter is described below.

Version 2.0 Only: A version 2.0 token will only be generated when the "-2" parameter is the first parameter.
You should upgrade to Token-Based Authentication 3.0.
Learn more.

The proper syntax for specifying multiple parameters is to use an ampersand (&) between parameters. This can be seen in the following syntax example:

For example, if you wanted to generate a token that meets the following requirements:

• Uses an encryption key called "MyKey."
• Expires on 12/31/2015 12:00:00 GMT.
• Only allows access to North American countries.
• Only allows referrers from "TrustedDomain.com."

Then you would use the following syntax:

The token value associated with this configuration would be:

You would then append this token value to your protected content as can be seen below:

The Token Auth page provides an "Encrypt Tool" that can generate tokens. This tool will also display the corresponding call through which our Token Generator application (i.e., ectoken3) can generate the same token. This sample syntax will appear next to the Token Generator Call label.

Building a Custom Token Generator

Leverage our open-source repository to create a custom application to generate token values. This repository, which is hosted on GitHub, contains C, C++, C#, PHP, Perl, Java, and Python source code.

This repository is located at:

https://github.com/edgecast/ectoken