Token Auth

How Does It Work? #

• The request’s query string must contain a token.
  Example:
  https://cdn.example.com/secure/product.pdf?1234567890abcdefgh1234567890abcdefgh
• The request must satisfy all of the requirements defined within the token.
  Using your encryption key(s), Edgio decrypts the token. It will then verify that the request satisfies each parameter defined within the decrypted token.
  • Valid Request: If the request satisfies all parameters, then Edgio will proceed processing the request.
    Our other security solutions may prevent this request from being fulfilled. For example, our Web Application and API Protection solution will still screen the request. If it violates your security policy, then Edgio could potentially apply an enforcement action (e.g., block the request).
  • Invalid Request: If the request does not satisfy all of the conditions defined in the token, then the request will be denied. By default, we will return a 403 Forbidden response. However, you may customize your configuration to return a different status code or even redirect users to another web page.

Getting Started #

1. Define a primary encryption key.
2. Ensure that requests for content that will be protected by Token Auth contain a query string that start with a token.
   This step requires generating encrypted tokens that define the minimum access requirements. For example, you could use a server-side script to generate and inject tokens within links to protected content.
3. Enable Token Auth on the desired requests by adding the Token Auth feature to one or more rule(s).

   

   CDN-as-code: View sample code.
4. Deploy your changes.

Encryption Keys #

• An encryption key may consist of any combination of alphanumeric characters. All other characters, including spaces, are not valid for encryption keys.
• An encryption key is case-sensitive. In other words, the case of an encryption key affects the encryption and decryption of token values.
• The maximum length of an encryption key is 250 characters.
• By default, a token value is only specific to an encryption key. This means that it may be possible for a client to use a single token value to gain access to protected content from various folders. Use the ec_url_allow parameter to ensure that a token may only be used for a specific directory or for a particular file.
• Changes to your encryption key configuration, such as adding or updating an encryption key, require a deployment.
• A standard method for generating random values is to use the OpenSSL tool to perform hexadecimal encoding.
  Syntax: rand -hex <Length>
  Hexadecimal encoding doubles the specified length. For example, specifying a length of 32 will generate a value containing 64 characters.
  Example:
  Bash

  Copy

  1OpenSSL> rand -hex 32
  2Loading 'screen' into random state - done
  370ae02ac9f8270e160eadbaefdd5df37c8e13750d1793dcd55b00943fff3b829

1. Navigate to the desired environment’s Settings page.
   1. From the Edgio Console, select the desired private space or organization.
   2. Select the desired property.
   3. From the left-hand pane, select the desired environment from under the Environments section.
   4. From the left-hand pane, select Settings.
2. From the Token-Based Authentication settings, set the Primary Key option to the desired alphanumeric value.
3. Click Save.
4. Apply this change by deploying to this environment.

Switching Encryption Keys #

• The amount of time it takes to update all of your links to secured content.
• Cached assets whose links contain old token values.

1. Navigate to the desired environment’s Settings page.
   1. From the Edgio Console, select the desired private space or organization.
   2. Select the desired property.
   3. From the left-hand pane, select the desired environment from under the Environments section.
   4. From the left-hand pane, select Settings.
2. From the Token-Based Authentication settings, copy the value from the Primary Key option to the Backup Key option.
3. In the Primary Key option, type your new encryption key.
4. Click Update.
5. Apply this change by deploying to this environment.

Removing an Encryption Key #

• All protected content can now only be requested with a token generated using the new primary encryption key.
• Cached content that leverages an old token is no longer being served. This may require purging cached content.

1. Navigate to the desired environment’s Settings page.
   1. From the Edgio Console, select the desired private space or organization.
   2. Select the desired property.
   3. From the left-hand pane, select the desired environment from under the Environments section.
   4. From the left-hand pane, select Settings.
2. From the Token-Based Authentication settings, set the Backup Key option to a blank value.
3. Click Update.
4. Apply this change by deploying to this environment.
   The backup key will be deactivated upon the completion of the deployment. After which, links that use tokens based off of the old encryption key will be rejected.

Tokens #

• A token may contain one or more parameters. Certain parameters support multiple values.
• The strength of the token is determined by the encryption key. For this reason, we recommend setting the encryption key to a random value generated using the OpenSSL tool.
• A token is limited to 512 characters. Edgio will automatically block requests containing larger tokens.
• Generating tokens does not affect your Token Auth configuration. It only affects the requests to which that token is applied.
• There is no limit to the number of tokens that can be generated for a specific encryption key.
• Generate a token using either of the following tools:
  • Our Token Generator application (ectoken3)
  • A custom script or application

Token Generator Application #

• Windows executable
  BouncyCastle.Crypto.dll and Blowfish.dll must reside within the same folder as the encryption executable.
• Linux binaries

Custom Token Generator #

• C
• C#
• Go
• JavaScript or npm package (@edgio/ectoken)
• Perl
• PHP
• Python
• Ruby
• Rust

Token Decryption #

• One use for this capability is to troubleshoot clients that cannot view your content due to Token Auth.
• You may only decrypt tokens if their encryption key is still active.
• Syntax: ectoken3 decrypt <Encryption Key> <Token>

Token Auth Parameters #

• ec_clientip: Restricts content delivery to requests that originate from a specific IP address.
  • This parameter supports standard IPv4/IPv6 and CIDR notation.
  Example: This example restricts delivery to a client with an IP address of 111.11.111.11:
  ec_clientip=111.11.111.11
• ec_country_allow: Restricts content delivery to the specified countries.
  • Use ISO 3166 country codes to specify countries.
  • Use a comma to delimit multiple country codes.
  Example: This example restricts delivery to requests that originate from within the United States:
  ec_country_allow=US
• ec_country_deny: Blocks requests from one or more countries.
  • Use ISO 3166 country codes to specify countries.
  • Use a comma to delimit multiple country codes.
  Example: This example blocks all requests that originate from the United States and Canada.
  ec_country_deny=US,CA
• ec_expire: Defines an expiration date and time (GMT) for the token value.
  • Specify the number of seconds that will pass from Unix time to the expiration date.
  Example: This example expires the token on 12/31/2024 at 12:00:00 GMT:
  ec_expire=1735646400
• ec_host_allow: Restricts delivery to the specified set of hosts.
  • Exclude the protocol portion of the desired URL (e.g., http://).
  • A comparison will be made against the Host request header. Delivery is restricted to requests whose hostname matches a specified value.
  • Use a comma to delimit multiple hosts.
  Example: This example blocks all requests whose host does not match either server1.example.com or the server2.example.com domain root (e.g., it would allow secure.server2.example.com and cdn.server2.example.com):
  ec_host_allow=server1.example.com,*.server2.example.com
• ec_host_deny: Defines the set of hosts that will be blocked.
  • Exclude the protocol portion of the desired URL (e.g., http://).
  • A comparison will be made against the value specified in the Host request header. Delivery is restricted to requests whose hostname do not match a specified value.
  • Use a comma to delimit multiple hosts.
  Example: This example blocks all requests whose host matches either server1.example.com or the server2.example.com domain root (e.g., it would block secure.server2.example.com and cdn.server2.example.com):
  ec_host_deny=server1.example.com,*.server2.example.com
• ec_proto_allow: Restrict delivery to the specified protocol(s). Valid values are:
  http | https
  Example: This example restricts delivery to requests that leverage the HTTPS protocol.
  ec_proto_allow=https
• ec_proto_deny: Denies requests that leverage the specified protocol. Valid values are:
  http | https
  Example: This example restricts delivery to requests that leverage the HTTPS protocol.
  ec_proto_deny=http
• ec_ref_allow: Restricts delivery to the specified set of referrers.
  • Exclude the protocol portion of the desired URL (e.g., http://).
  • The specified value will be compared against the request’s Referer header. This header value must start with a value defined by this parameter.
  • Use a comma to delimit multiple referrers.
  Example: This example allows requests whose referrers start with www1.example.com/obj1 or whose host contains the server2.example.com domain root.
  ec_ref_allow=www1.example.com/obj1,*.server2.example.com
• ec_ref_deny: Defines the set of referrers for which delivery will be denied.
  • Exclude the protocol portion of the desired URL (e.g., http://).
  • The specified value will be compared against the request’s Referer header. This header value must start with a value defined by this parameter.
  • Use a comma to delimit multiple referrers.
  Example: This example denies requests whose referrers start with www1.example.com/obj1 or whose host contains the server2.example.com domain root.
  ec_ref_deny=www1.example.com/obj1,*.server2.example.com
• ec_url_allow: Links a URL path to a token.
  • Only requests that start with the specified URL path will be allowed access.
  • This relative path starts after the hostname. Exclude the protocol and hostname (e.g., https://www.example.com) when using this parameter.
  • Use a comma to delimit multiple paths.
  Example: This example allows requests that meet one of the following criteria:
  • All content stored in the directory tree that starts with /dir1/movie1.
  • All content stored in the directory tree that starts with /dir2.”
  /dir1/movie1,/dir2

Authorizing Requests #

• By default, you must specify this token at the start of the query string.
  Example:
  <img src="http://images.mydomain.com/images/myimage.jpg?c1019f8a6942b46a1ce679e168d5797670f3ee7e39068054ee4534d8a5a859dc06">
  If the request URL contains additional query string parameters, then they should be appended to the token through the use of an ampersand.
  Example:
  <img src="http://images.mydomain.com/images/myimage.jpg?c1019f8a6942b46a1ce679e168d5797670f3ee7e39068054ee4534d8a5a859dc06&width=240&height=480">
• Specify a token as a custom query string parameter by enabling the Token Auth Parameter feature.
  Example: The following example assumes that the Token Auth Parameter feature is set to token:
  <img src="http://images.mydomain.com/images/myimage.jpg?width=240&height=480&token=c1019f8a6942b46a1ce679e168d5797670f3ee7e39068054ee4534d8a5a859dc06">

Securing Content #

• The request URL’s query string must contain a valid token. A token is considered valid if it can be decrypted using either the current primary or backup encryption key.
  Example:
  https://cdn.example.com/secure/product.pdf?1234567890abcdefgh1234567890abcdefgh
• The request satisfies all of the condition(s) defined within the token.

Disabling Token Auth #

Redirecting Unauthorized Users #

• 301: A 301 Moved Permanently response redirects unauthorized users to the URL specified in the Location header.
• 302: A 302 Found response redirects unauthorized users to the URL specified in the Location header. This status code is the industry standard method of performing a redirect.
• 307: A 307 Temporary Redirect response redirects unauthorized users to the URL specified in the Location header.
• 403: A 403 Forbidden response is typically returned when an unauthorized user trys to access content.
• 404: A 404 Not Found response indicates that the HTTP client was able to communicate with the server, but the specified asset was not found.

1. Navigate to the desired environment’s Rules page.
2. Find the rule that enables the Token Auth feature.
3. Add the Token Auth Denial Code feature.
   1. Set the Status Code option to 302.
   2. Set the Header Name option to Location.
   3. Set the Value option to the full URL to the user-friendly error page (e.g., https://www.example.com/purchasecontent.aspx).
   4. Click Apply.