Token Authentication

This guide explains how to configure and use token authentication (also known as timestamp anti-hotlinking). This security feature is designed to protect your live streaming content from unauthorized access and hotlinking.

By adding an encrypted token and a timestamp to your streaming URLs, you can control who can access your streams and for how long. This ensures that only users with valid, time-limited URLs can view your content, securing your streams and preventing unauthorized distribution.

How It Works

The authentication process involves three main components:

1. Secret Key: A private key that you configure in the console. This key is known only to you and our servers.
2. Timestamp: A timestamp that indicates when the URL expires or when it was generated.
3. Token (Signature):: An encrypted signature (hash) generated on your server using the secret key, the URL path, and the timestamp.

When a viewer tries to access a stream using an authenticated URL, our edge servers will:

1. Receive the request and extract the token, timestamp, and other parameters from the URL.
2. Re-generate the token on the server using the same secret key and logic.
3. Compare the token from the URL with the server-generated token.
4. Check if the URL has expired based on the timestamp.

If the tokens match and the URL has not expired, the viewer is granted access to the stream. Otherwise, the request is denied.

Console Configuration

To enable and configure token authentication, follow these steps:

1. Go to Low Latency Streaming.
2. Select the domain you want to configure.
3. Click Edit Configuration.
4. Navigate to the Timestamp anti-hotlinking (Live) section.

Here is a detailed explanation of each field in the configuration panel:

Validity Period Options Explained

• By Duration: The URL is valid for a fixed period of time set in the Duration field. The expiration is calculated as wsTime (the timestamp in the URL) + the configured Duration. This is the most common and simple method.
• By Absolute Time: The URL expires at a specific, absolute timestamp. Instead of a generation time, your server generates a URL with a parameter (e.g., wsABSTime) containing the exact UNIX timestamp of expiration. The hash is calculated using this absolute expiration time.
• By Valid Time: This method allows you to set the validity period dynamically within the URL itself using the wsKeepTime parameter. This provides flexibility, as your server can generate links with different lifespans without changing the console configuration. The hash calculation includes both wsTime and wsKeepTime.
• Do Not Validate Timestamp: The system will still validate the wsSecret token to ensure the request is signed with the correct key, but it will not check if the timestamp (wsTime) has expired. This is less secure and primarily used to validate the origin of a request without time constraints.

Generating Authenticated URLs

Once you have configured the feature in the console, you need to update your application or backend server to generate the dynamic, authenticated URLs for your users.

The core logic is to create a string based on your chosen Ciphertext Combination Method and then calculate its MD5 hash. Note: The exact components included in the string to be hashed can vary depending on the Validity Period method you choose.

Example: Using “By Duration”

Let’s assume your configuration is as follows:

• KEY: mysecretkey
• Signature Components: KEY+PATH+TIME
• Signature Parameter Name: wsSecret
• Timestamp Parameter Name: wsTime
• Timestamp Format: UNIX timestamp
• Duration: 3600 seconds (1 hour)
• Stream Playback URL: http://your.domain.com/live/stream1.flv

Here’s how to generate the signed URL on your server:

1. Get the URL Path: The path is the part of the URL starting from the publishing point. In this case, it is /live/stream1.flv.
2. Get the Current Time: Get the current time as a UNIX timestamp. For example, 1678886400.
3. Concatenate the Strings: Combine the Key, Path, and Time according to your chosen method.
   Important: The path component must exactly match the URI from the publishing point onwards, including the leading slash.
   string_to_hash = "mysecretkey/live/stream1.flv1678886400"
4. Calculate the MD5 Hash: Calculate the MD5 hash of string_to_hash.
   wsSecret_value = md5("mysecretkey/live/stream1.flv1678886400")
   Let’s say the result is b1b5c2c7e8e5e8e5c2c7b1b5c2c7e8e5.
5. Construct the Final URL: Append the token and the timestamp as query parameters to the original URL.
   http://your.domain.com/live/stream1.flv?wsSecret=b1b5c2c7e8e5e8e5c2c7b1b5c2c7e8e5&wsTime=1678886400

A viewer using this URL will have access to the stream until 1678886400 + 3600 = 1678890000.

Example: Using “By Valid Time”

This method is useful when you want to define the validity duration dynamically for each URL you generate. Let’s assume your configuration is the same as the previous example, but you’ve selected By Valid Time.

• KEY: mysecretkey
• Signature Components: KEY+PATH+TIME (Note: The wsKeepTime value is appended after the timestamp in the hash calculation for this mode).
• Signature Parameter Name: wsSecret
• Timestamp Parameter Name: wsTime
• Timestamp Format: UNIX timestamp
• Desired Validity Duration: 7200 seconds (2 hours)
• Stream Playback URL: https://your.domain.com/live/stream1.sdp

Here’s how to generate the signed URL on your server:

1. Get the URL Path: /live/stream1.sdp.
2. Get the Current Time: 1678886400.
3. Define Validity Duration: 7200.
4. Concatenate the Strings: Combine the Key, Path, current Time, and the validity duration (wsKeepTime value).
   string_to_hash = "mysecretkey/live/stream1.sdp16788864007200"
5. Calculate the MD5 Hash: Calculate the MD5 hash of this new string.
   wsSecret_value = md5("mysecretkey/live/stream1.sdp16788864007200")
   The result is 20722b11be862a6563657a70a8a8167.
6. Construct the Final URL: Append wsSecret, wsTime, and wsKeepTime as query parameters.
   https://your.domain.com/live/stream1.sdp?wsSecret=20722b11be862a26563657a70a8a8167&wsTime=1678886400&wsKeepTime=7200

This approach provides more flexibility by allowing the URL-generating server to set the expiration on the fly.

Example: Using “By Absolute Time”

This method is ideal when you need a link to expire at a precise moment, regardless of when it was generated.

• KEY: mysecretkey
• Signature Components: KEY+Path+Time (Note: The “Time” in the hash is the absolute expiration time).
• Signature Parameter Name: wsSecret
• Timestamp Parameter Name: wsABSTime (This parameter name must be configured in the console).
• Timestamp Format: UNIX timestamp
• Desired Expiration Time: 1678890000 (This is the exact UNIX timestamp when the URL will become invalid).
• Stream Playback URL: https://your.domain.com/live/stream1.m3u8

Here’s how to generate the signed URL on your server:

1. Get the URL Path: /live/stream1.m3u8.
2. Define Absolute Expiration Time: 1678890000.
3. Concatenate the Strings: Combine the Key, Path, and the absolute expiration Time.
   string_to_hash = "mysecretkey/live/stream1.m3u81678890000"
4. Calculate the MD5 Hash: Calculate the MD5 hash of this new string.
   wsSecret_value = md5("mysecretkey/live/stream1.m3u81678890000")
   The result is a3f9b2c8d7e6f5a4b3c2d1e0f9a8b7c6.
5. Construct the Final URL: Append wsSecret and the wsABSTime as query parameters. https://your.domain.com/live/stream1.m3u8?wsSecret=a3f9b2c8d7e6f5a4b3c2d1e0f9a8b7c6&wsABSTime=1678890000

This URL will be valid until the exact timestamp 1678890000 is reached.