How to protect streams with token authorization by using the Wowza Streaming Cloud REST API

You can use the Wowza Streaming Cloud™ service REST API to restrict access to a stream by applying token authorization to a stream target. Token authorization allows only viewers who have the token, which is hashed and appended to the playback URL, to access the stream. You can use token authorization with Wowza stream targets to make the stream playback URL unavailable after a certain length of time, to limit access to approved IP addresses, or apply other restrictions. A common use is to protect pay-per-view content to only paying viewers.

About token authorization


Token-based authorization uses a multipart token that consists of a delimited list of string fields. One field is an HMAC, or keyed-hash message authentication code. HMAC is a common mechanism for message authentication that uses cryptographic hash functions. The HMAC portion of the token hashes a trusted shared secret that you create in Wowza Streaming Cloud. It is short-lived and secures initial access to the stream.

The second part of the token, a cookie, is valid for duration of stream and protects segments that are delivered during playback. It restricts access to the stream according to query parameters that you specify. For example, you can expire the stream after a certain length of time or only allow whitelisted IP addresses to access it.

You append the token to the stream target's playback URL, and then Wowza Streaming Cloud only lets viewers receive the content after it verifies the presence and validity of the token.

Token authorization is managed by the browser. No configuration is required for the player. However, token authorization requires that the viewer's browser supports cookies.

Notes:
  • Token authorization only works in Safari if the security preference Accept Cookies is set to Always. Otherwise, the protected stream can't be played.
     
  • Token authorization works with third-party players and with Wowza Player Builder. It doesn't work with a player created in the Wowza Streaming Cloud live stream workflow and embedded in a hosted or third-party webpage.
  • If using Wowza Player Builder, enable the withCredentials configuration property. See Player Builder configuration settings for Wowza Player for more information.

Add a Wowza stream target for Apple HLS playback


First, add a Wowza stream target configured to play streams from a Wowza CDN over Apple HLS or Apple HLS and Adobe HDS.

Stream target parameters

Parameter Data Type Description
name string A descriptive name for the stream target. Maximum 255 characters.
provider string Specify akamai_cupertino (for HLS-only playback) or akamai (for HLS and HDS playback).
use_cors Boolean (Optional) CORS, or cross-origin resource sharing, allows streams to be safely delivered across domains. For example, they can be sent to providers such as Peer5, Viblast, and Streamroot, which implement a peer-to-peer grid delivery system. Specify true to enable CORS. The default is false. Available if the provider is akamai_cupertino.
use_secure_ingest Boolean (Optional) Specify true to deliver the HLS stream securely between the transcoder and the target. The default is false. Available if the provider is akamai_cupertino.

Example request and response

Notes:

  • For [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
  • For [version], substitute the version number of the API that you're using. For the current version, use v1.2.

The following request generates a Wowza stream target for Apple HLS playback:

curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "wowza_stream_target": {
     "name": "MyHLSTarget",
     "provider": "akamai_cupertino"
   }
 }' "https://api.cloud.wowza.com/api/[version]/stream_targets/wowza"

The details of the configured target are listed in the response, which should look something like this:

{
  "wowza_stream_target": {
    "created_at": "2016-02-23T16:04:23.170Z",
    "hls_playback_url": "https://[wowzasubdomain]-i.akamaihd.net/hls/live/[appname]/[streamname]/playlist.m3u8",
    "id": "1234abcd",
    "name": "MyHLSTarget",
    "primary_url": "http://[wowzasubdomain]-i.akamaihd.net/[appname]/[streamname]",
    "provider": "akamai_cupertino",
    "stream_name": "st1r2eam",
    "updated_at": "2016-02-23T16:04:23.170Z",
    "use_cors": false,
    "use_secure_ingest": false
  }
}

Create token authorization for the target


Create token authorization for the Wowza stream target.

Token authorization parameters

Parameter Data Type Description
enabled Boolean Specify true to permit token authorization for the target.
trusted_shared_secret string Provide a trusted shared secret for the token authorization. Must contain only hexadecimal characters and be an even number of characters equal to or less than 32.

Example request and response

The following request enables token authorization for the target 1234abcd:

curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "token_auth": {
     "enabled": true,
     "trusted_shared_secret": "12345678abcdefgh"
   }
 }' "https://api.cloud.wowza.com/api/[version]/stream_targets/1234abcd/token_auth"

The details of the configured authorization are listed in the response, which should look something like this:

{
  "token_auth": {
    "created_at": "2016-10-23T16:04:22.828Z",
    "enabled": true,
    "stream_target_id": "1234abcd",
    "trusted_shared_secret": "12345678abcdefgh",
    "updated_at": "2016-10-23T16:04:22.828Z"
  }
}

Important: After enabling token authorization, you must contact Support in order for the changes to take effect.

Related requests

View the details of a token authorization:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[wowza_stream_target_id]/token_auth"

Update the token authorization applied to a stream target:

curl -X PATCH --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "token_auth": {
     "enabled": "false"
  }
 }' "https://api.cloud.wowza.com/api/[version]/stream_targets/[wowza_stream_target_id]/token_auth"

Important: After updating token authorization, you must contact Support in order for the changes to take effect.

Assign the stream target to a transcoder


Assign the token-authorized stream target to a transcoder's output rendition(s).

Note: For an adaptive bitrate transcoder, you must assign the target to all of the transcoder's output renditions.

Add stream target parameters

Parameter Data Type Description
id string The unique alphanumeric string that identifies the output rendition that will deliver content to the stream target. You can find the ID in the details of the output's transcoder.
stream_target_id string The unique alphanumeric string that identifies the stream target. You can find the ID in the details of the Wowza stream target you just created.
transcoder_id string The unique alphanumeric string that identifies the transcoder.

Example request and response

The following request adds the token-authorized stream target 1234abcd to the output rendition whose ID is 5678efgh for the transcoder 9012ijkl.

curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "output_stream_target": {
     "stream_target_id": "1234abcd",
     "use_stream_target_backup_url": false
   }
 }' "https://api.cloud.wowza.com/api/[version]/transcoders/9012ijkl/outputs/5678efgh/output_stream_targets/"

The details of the configured target are listed in the response, which should look something like this:

{
   "output_stream_target": {
    "stream_target_id": "1234abcd",
    "use_stream_target_backup_url": false
   }
}

Generate the hashed token


Once enabled, your playback URLs need to include the hdnts query parameter for playback to work. You can write a query in C, Java, PHP, Ruby, or other language. Download and experiment with these query code samples. Various parameters can be used along with the trusted_shared_secret. The following table includes a list of the basic parameters.

Note: All parameters are of the type string.
Parameter Description
algo The algorithm use to generate the token. Options are sha1, sha256 (the default), or md5.
end_time The time that protected access to the stream ends, in UTC seconds. For example, 1478995200 for 13 November 2016 00:00:00 GMT, 24 hours from start_time.
ip The IP address to restrict this token to.
key The trusted_shared_secret from Wowza Streaming Cloud required to generate the token. Using the example in this article, the value would be 12345678abcdefgh.
start_time The time that protected access to the stream begins, in UTC seconds. For example, 1478908800 for 12 November 2016 00:00:00 GMT. Use now for the current time.
 
Note: Go to epochconverter.com to convert human-readable time to UTC Unix timestamps.
token_name Parameter name for the token. The default is hdnts.
token_type Specify 2.0, 2.0.2, PV, or Debug.
url The Wowza Streaming Cloud playback URL, which is the hls_playback_url of the Wowza Streaming Cloud stream target. Using the example in this article, the value would be https://[wowzasubdomain]-i.akamaihd.net/hls/live/[appname]/[streamname]/playlist.m3u8.

Attach the hashed token to the URL of your stream using the format

[playback_URL]?[token_name]=[parameters_and_hashed_token]

For example, for an Apple HLS stream:

http://[wowzasubdomain]-i.akamaihd.net/hls/live/[appname]/[streamname]/playlist.m3u8?hdnts=exp=1461972009~acl=/*~hmac=de43455a65009cbb538495e5bc70c9565a3c559406c0c7bc2a1cfeaff9344706

For an Adobe HDS stream:

http://[wowzasubdomain].akamaihd.net/z/[streamname_angle]@[stream_id]/manifest.f4m?hdnts=exp=1461972009~acl=/*~hmac=de43455a65009cbb538495e5bc70c9565a3c559406c0c7bc2a1cfeaff9344706


If you're having problems or want to discuss this article, post in our forum.