Show search and navigation.

 

Token-Based Authentication Frequently Asked Questions

Applies To:
HTTP LargeThis platform has been optimized to cache and deliver static content (e.g., HTML, CSS, JavaScript, ISO, multimedia, and software downloads, etc.) over HTTP or HTTPS.
HTTP SmallLegacy. If you are currently serving traffic over this platform, then you may continue to do so. However, we recommend that you serve your traffic over our more robust HTTP Large platform.
ADNThe Application Delivery Network platform has been optimized to deliver dynamic content (e.g., login credentials, account information, etc.) over HTTP or HTTPS. Typically, user-specific and database-driven content are served over this platform.
TBAThe Token-Based Authentication feature enforces authentication prior to content delivery. Authentication takes place via an encoded token value that must be included in the request URL. This token value is then decrypted on an edge server. The requested content will only be delivered when the user meets the requirement(s) defined in the token.

General

ClosedWhat is Token-Based Authentication?

The Token-Based Authentication feature requires authentication before the delivery of content via the CDN. If Token-Based Authentication has been applied to the requested content, then the following two requirements must be met before it will be delivered:

  • The URL must contain a token.
  • The requester must satisfy the requirements defined in the encrypted token.
ClosedCan I limit authentication to a file type or an individual file?

Yes. By default, Token-Based Authentication may be applied recursively to a directory. However, Rules Engine allows Token-Based Authentication to be enabled/disabled by request type. Leverage this capability to tailor the set of requests that will require authentication.

Encryption Key

ClosedWhat is the difference between the primary key and the backup key?

Both keys provide the same set of functionality.

ClosedWhy is there a backup key?

A backup key provides the means through which you can ensure uninterrupted access to your content when updating an encryption key.

Learn more.

ClosedWhat is the recommended method for generating an encryption key?

Use the OpenSSL tool to generate a hexadecimal encoded encryption key.

Syntax:

rand -hex KeyLengthReplace this term with the desired key length (e.g., 32).

Learn more.

Tokens

ClosedCan a token be decrypted by any key?

No. It can only be decrypted by the key used to encrypt it. Use the Token Generation executable to decrypt tokens generated with an old encryption key.

Learn more.

ClosedWhat is the maximum length of a token?

The total length of a token cannot exceed 512 characters.

ClosedIs there a limit to the number of parameters used to generate a token?

No. However, the resulting token cannot exceed 512 characters.

ClosedCan I use the same token to secure different files?

Yes, unless both of the following conditions are true:

  • The ec_url_allow parameter was used to generate the token.
  • The requested file does not meet the requirements defined in the ec_url_allow parameter.
ClosedCan I reuse tokens across various platforms?

A token can be used across platforms when the same encryption key has been defined for each platform.

ClosedHow do I prevent the reuse of tokens?

Make sure to always include both of the following parameters:

  • ec_url_allow: This parameter can tie a token to a folder or even a specific file.
  • ec_expire: This parameter expires your token after a given date/time.

Token-Based Authentication Versions

ClosedWhat are the differences between the various versions?

The differences between the various versions are described below.

Version Description

1

This is the original version of Token-Based Authentication.

This version has a known security vulnerabilityTo protect the integrity of customer data, details on the exact security vulnerability cannot be shared at this time. Although we highly value transparency, this policy provides customers additional time to prepare and implement the transition to version 3.. You should upgrade to Token-Based Authentication 3.0.
Learn how to upgrade.

2

This version was introduced to address a security vulnerability in version 1.

This version has a known security vulnerabilityTo protect the integrity of customer data, details on the exact security vulnerability cannot be shared at this time. Although we highly value transparency, this policy provides customers additional time to prepare and implement the transition to version 3.. You should upgrade to Token-Based Authentication 3.0.
Learn how to upgrade.

3

This version, which leverages a state-of-the-art cryptographic algorithm and additional security measures to harden token encryption/decryption, introduces the following differences:

  • The executable, binaries, and source code now support version 2.0 and 3.0 token encryption/decryption.
  • The following changes were applied to the Token Auth page:
    • Key Setup: A key-specific option called "Minimum encryption version" determines whether the key will support encryption/decryption using version 2.0 & 3.0 or only version 3.0.
    • Encrypt Tool: The Encryption version option determines the encryption version that will be used to generate tokens.
    • Decrypt Tool: This tool decrypts all tokens regardless of encryption version.
  • The Update Primary Key method (REST API) was updated to include a parameter that defines the minimum encryption version that will be assigned to the new primary key.
  • The Encrypt Token Data method (REST API) was updated to include a new parameter that determines the encryption version that will be used to generate a token.

Learn how to upgrade.

ClosedHow can I tell which version I'm using?

Follow the directions provided below to find out version information.

Component Encryption/Decryption Version

Encrypt Tool (Token Auth page)

Tokens will be encrypted/decrypted using either version 2.0 or 3.0 as determined by the Encryption Version option.

Token Generator (Windows Executable/Linux Binaries)

Find out version information by running the following command:

ectoken3 --version

The above command does not work with version 1.0. Please upgrade to the latest version immediately.

Token Generator (Source Code)
  1. Find the zip file for the Token Generator source code currently being used in your project.
  2. Open the readme file from the above zip file.
  3. Look for version information on the first line.

If version information is not provided on that line, then you are using version 1.0. Please upgrade to the latest version immediately.

Update Primary Key (REST API)

By default, a new primary key will be assigned a minimum encryption version of 2.0. An optional parameter called "MinVersion" may be used to define a higher minimum encryption version.

Encrypt Token Data (REST API)

A response body parameter called "TokenVersion" indicates the encryption version used to generate the token.
ClosedHow does the Token-Based Authentication 3.0 update affect my installation?

The introduction of this update does not affect the CDN's ability to authenticate traffic via Token-Based Authentication. Additionally, most Token-Based Authentication components require manual intervention before they will take effect.

More Information

This update was applied to the following components:

Component Description

Encrypt Tool (Token Auth page)

Tokens will be encrypted/decrypted using either version 2.0 or 3.0 as determined by the Encryption Version option.

Token Generator (Windows Executable/Linux Binaries)

This update will not take effect until the following actions take place:

  1. The new version of Token Generator is downloaded from the MCC.
  2. Your custom script/application is updated to call the new version of Token Generator (i.e., ectoken3).

By default, the updated Token Generator will encrypt/decrypt tokens using version 3.0. However, a command-line parameter (e.g., ectoken3 -2 Key Parameters) may be used to generate tokens using version 2.0.

Token Generator (Source Code)

This update will not take effect until the following actions take place:

  1. The new version of Token Generator is requested from your CDN account manager.
  2. Your custom script/application is updated to call the new version of Token Generator (i.e., ectoken3).

Update Primary Key (REST API)

By default, a new primary key will be assigned a minimum encryption version of 2.0. Use the MinVersion parameter to assign a minimum encryption version of 3.0 to the new primary key. This will effectively disable version 2.0 encryption/decryption for tokens generated from the new primary key.

This method should be used with care. The safest method for updating your primary key is to do so through the Token Auth page. Continuous access to your content cannot be guaranteed when a backup key is not used.
Learn the recommended method for rotating keys.

Encrypt Token Data (REST API)

By default, tokens are encrypted using the minimum encryption version assigned to the specified key. Encrypt tokens using version 3.0 by indicating that preference in the TokenVersion parameter.

ClosedHow do I update to the latest version of the Token Generator?

Token-Based Authentication 3.0 leverages a state-of-the-art cryptographic algorithm and additional security measures to harden token encryption/decryption. Use the following procedure to properly update custom scripts/applications.

To upgrade to the latest version of Token-Based Authentication

Steps 2 and 3 may be skipped if your custom script/application only uses the Encrypt Token Data method (REST API) to generate tokens.

  1. Rotate the primary encryption key.
    1. Navigate to the Token Auth page for the desired platform.
    2. Set the Backup Key option to the current primary key.
    3. Make sure that the backup key's minimum encryption version is set to "V2."
    4. Set the Primary Key option to a new primary key.
    5. Set the primary key's minimum encryption version to "V3."
    6. Click Update.
      • It may take up to an hour for this change to take effect.

  2. Download the latest version of the Token Generator.

    • Executable/Binaries: Download it from the Token Generator page or click here.
    • Source Code: Request the updated version from your CDN account manager.

  3. Apply the Token Generator update by performing either of the following steps:

    • Executable/Binaries: Copy the updated Windows executable or Linux binaries to a location that is accessible to your script or application. Update your code to point to the new executable/binary.
    • Source Code: Modify the desired script or application to leverage the updated source code.

  4. Immediately after making the above changes, update the desired script or application to use the new primary key. At this point, version 3.0 tokens will be generated.

    • Do not use the new primary key to generate version 2.0 tokens. Doing so compromises the integrity of the new primary key.
  5. Update all links to content secured by Token-Based Authentication to use the version 3.0 tokens generated in the previous step.
  6. Purge the content updated in step 5.
    • This step prevents the delivery of cached content containing tokens encrypted using version 2.0 or lower.
  7. From the Token Auth page, clear the backup encryption key and click Update.

All of the above steps, with the exception of step 2, must be performed for each platform that authenticates content via Token-Based Authentication.

Learn more about encryption key rotation.

More Information
ClosedFrequently Asked Questions