Content Protection / Using an External URL Tokenizer (StreamClip) | WS.WebTV Documentation | WebTV Solutions

Print

Introduction

Some clients may need to use tokenized URLs for restricting the access to the files/streams. This normally imply generating a unique URL per (authorized) User by adding a token to the original file or stream URL. In order to allow this, we have implemented a simple way for the WebTV to get the tokenized URL for a particular User through an external URL tokenizer script.

How does it work?
1. You develop a script that generates the required token(s) for a given, generic, URL. For example:
- Given -generic- URL: http://www.mymediaserver.com/myfile.mp4
- Tokenized URL: http://www.mymediaserver.com/myfile.mp4?token=uniquetoken
2. You configure the WebTV to use the tokenizer script (by supplying the script URL and a secret key).
3. When specifying the URL to the files/streams (in the "Media" tab of a StreamClip) you must add the [xtok] prefix to the generic URL.
4. At playback time, if the WebTV video player finds the aforementioned prefix in an URL, then it will request the "tokenized" URL before playing it back.

How does the tokenizer script get the details?
The WebTV, in case the User is authorized to access the content, will send the required data to the tokenizer script (generic URL, User ID and User IP) as GET vars (which will be appended to the tokenizer script URL). The data will also include a validation signature (hash). More info below.

1. Implementing the Tokenizer Script

Sample Code

Download a sample tokenizer code in PHP:
Sample tokenizer script

Developing the Tokenizer Script: Receiving the data sent by the WebTV

The WebTV will append the request details to the tokenizer script URL as GET vars. Example:
http://.../external_tokenizer.php?user_id={id_of_the_user}&user_ip={ip_of_the_user}&url={url_to_be_tokenized}&signature={signature}

• user_id -> ID of the User (in the WebTV)
• user_ip -> Detected IP of the User
• url -> URL to be tokenized
• signature -> A signature (hash) for validating the request. The sigtanure is generated with the key entered in the WebTV configuration, using HMAC SHA256.

Validating the request
Before generating the token, you should validate the request using the signature. For doing this you must generate a signature, just like the WebTV does it, and compare it aginst the received one.

Example in PHP:
$key = "the secret key";
$data = array(
     "user_id" => (int)$user_id,
     "user_ip" => $user_ip,
     "url" => $url
);
$signature = base64_encode(hash_hmac('sha256', json_encode($data), $key, true));

Once you have generated the signature, you must compare it against the one sent from the WebTV: If they match, you can continue.

When doing tests during development... if the signatures don't match (and you are sure the data you are receiving has not been altered), verify the keys used to generate the hashes (in the script and WebTV) are the same. If they are the same, verify the received data is being urldecoded and that you are generating the signature exactly as explained in the example above.

Developing the Tokenizer Script: Returning the Tokenized URL

Once you have genrated the tokenized URL you must return the result as a JSON formatted array.

Array indexes required by the WebTV
• error -> (optional) Only if there was a processing error.
• url -> The resulting, tokenized URL.

Examples in PHP:

-Success-
echo json_encode( array(
     "url" => "http://mymediaserver.com/whatever_folder/myfile.mp4?token=uniquetoken"
     ));
-Error-
echo json_encode( array(
     "error" => "An error message..."
     ));

2. Configuring the WebTV to Use the Tokenizer Script

As explained above, this imply supplying the tokenizer script URL as well as a secret key to the WebTV.
Edit the WebTV configuration file (config/Config.inc.php) and add the following variables before the PHP closing tag (?>):
$EXTERNAL_URL_TOKENIZER_URL = "http://mydomain.com/my_url_tokenizer.php"; // The URL to the tokenizer script
$EXTERNAL_URL_TOKENIZER_KEY = "mysecretkey"; // This key will be used to generate a validation signature/hash. It must match the one used in your tokenizer script.

3. Referencing/Playing Back Video Files (for "tokenization") on WS.WebTV

Unsing StreamClip VOD/Live

By this time, you should be familiar on how to create and edit a StreamClip. If this is not the case, please check the "StreamClip VOD" and "StreamClip Live" tutorials before continue reading.

("Media" tab)
Simply add the [xtok] prefix to the file/stream generic URLs into the corresponding slots. Examples:
RTMP: [xtok]rtmp://mymediaserver.com/vod/myfile.mp4
HTTP: [xtok]http://mymediaserver.com/vod/myfile.mp4
HLS: [xtok]http://mymediaserver.com:1935/vod/myfile.mp4/playlist.m3u8
RTSP (Live): [xtok]rtsp://mymediaserver.com/vod/myfile.mp4

Unsing Standard Clip: Integration (Configuration > Video > External Storage)

This is done by introducing the corresponding Base URL formulas into Configuration > Video


Flash Formula
The URL Formula to enter into the corresponding quality (Flash slot) would be like this:
   [xtok]rtmp://mymediaserver.com/whatever_folder/{filename.ext}
Please, note the "[xtok]" at the beginning of the formula and "mp4:" before the special label.

HTML5 Formula
The URL Formula to enter into the corresponding quality (HTML5, or Flash. slot) would be like this:
   [xtok]https://mymediaserver.com/whatever_folder/{filename.ext}
Please, note the "[xtok]" at the beginning of the formula.

Tokenized Download URLs (Clips with video download option enabled)

For WS.WebTV version 2.0 and newer
When you enable the "Download" menu for a Clip, and it has been set as "Yes, WebTV Files" or "Yes, WebTV Files + Other Files", and the HTML5 quality fields reference .mp4 files the system will automatically generate the corresponding (tokenized) download URLs for those files. Although the previous, in case that, in the "Download" menu of a Clip, you want to provide links to files which are different that the ones referenced in the HTML5 qualities fields, and those files also require tokenized URLs then follow steps 1 and 2 of the following section.

For WS.WebTV versions prior to 2.0
If you plan to enable the "Download" menu for a Clip and you want to provide a secured URL to a file -so it can only be downloaded by authorized users-, then you need to use a special URL generated by the WebTV, which will tokenize the URL so that only authorized users can download the file.

In order to enable the "Download" menu for a Clip which uses private CloudFront URLs, follow these steps:
1. On "Show download menu", select "Yes, Other files".
2. Supply manual download link(s): Download links must be genarated using the WebTV Tokenizer URL generator utility of the WebTV. In order to run the utility, open the following URL in a Web browser (replace your WebTV URL):
http://<url_of_your_webtv>/index.php?go=ajax&do=genxtokenizerurl and supply the corresponding generic URL to the file. For example:
The following File URL:
http://mymediaserver.com/whatever_folder/myvideo.mp4
Will be transformed (by the utility) to something like this:
http://<url_of_your_webtv>/index.php?go=ajax&do=getxtokenizedurl&iq=,http%3A%2F%2Fmymediaserver.com%2Fwhatever_folder%2Fmyvideo.mp4&tp=download
The transformed URL will be the one that you must enter into the "Other Files" field