Protect a Wowza CDN on Fastly stream target with token authentication 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 authentication to a Wowza CDN on Fastly stream target. Token authentication allows only viewers who have the token, which is hashed and appended to the playback URL, to access the stream. You can use token authentication with Wowza CDN on Fastly 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.

Note: This article applies to Wowza CDN on Fastly stream targets only. To secure Wowza CDN on Akamai stream targets with token authentication, see Protect streams with token authorization using the Wowza Streaming Cloud REST API.

Before you start


You should complete the following tasks:

  • Create a transcoder. You'll need the resulting transcoder_id to assign the token-authenticated stream target to the transcoder. View our Connect a source topics to learn how to create a live stream or transcoder for RTMP, RTSP, IP camera, SRT encoder, UDP encoder, WebRTC, and Wowza Streaming Engine.

You should be familiar with the following concepts:

  • API authentication methods. Use HMAC authentication for production environments. For testing or proof of concept purposes only, use API key and access key authentication.
  • Environment variables. We use environment variables for the API version and your API and access keys in the cURL API request examples in this topic to make it easier for you to copy, paste, and run commands in your Terminal or Command Prompt window. If you don't set environment variables for these values, you'll need to manually enter the correct values in the code samples throughout this tutorial. See Tools for testing the API for instructions.

About token authentication


Token-based authentication 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 the duration of the 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 let allowlisted 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 authentication is managed by the browser. No configuration is required for the player. However, token authentication requires that the viewer's browser supports cookies.

Notes:
  • Token authentication 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 Customize Wowza Player with configuration properties for more information.

1. Create a Wowza CDN on Fastly stream target with token authentication enabled


Create a Wowza CDN on Fastly stream target configured for token authentication by sending a POST request to the /stream_targets/fastly endpoint.

You can use the following sample request, making sure to:

  • Set token_auth_enabled to true
  • Set token_auth_playlist_only to true or false. If true, Wowza Streaming Cloud protects the master playlist only and leaves individual media playlists and media segments unprotected. If false, the master playlist, media playlists, and media segments are all protected. This feature enables playback compatibility with media players that don’t support the withCredentials property. It may also be useful when addressing token auth compatibility issues with specific browsers. The default is false.

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "stream_target_fastly": {
     "name": "My Secure Target",
     "token_auth_enabled": true,
     "token_auth_shared_secret":"12345678ABCDEF",
     "token_auth_playlist_only": true
   }
 }' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/fastly"

The response includes:

  • A stream_target_id for the transcoder that you'll use in step 2.

Sample response

{
  "stream_target_fastly": {
    "id": "1234abcd",
    "name": "My Secure Target",
    "state": "activated",
    "stream_name": "st1r2eam",
    "delivery_protocols": [
        "hls"
    ],
    "playback_urls": {
      "hls": [
        {
	  "name": "default",
          "url": "https://[subdomain].wowza.com/1/[stream_id]/[stream_name]/hls/live/playlist.m3u8"
         }
      ]
    },
    "token_auth_enabled": true,
    "token_auth_shared_secret":"12345678ABCDEF",
    "token_auth_playlist_only": true,
    "geoblock_enabled": false,
    "referer_enabled: false,
    "force_ssl_playback": false,
    "created_at": "2019-09-23T16:04:23.170Z",
    "updated_at": "2019-09-23T16:04:23.170Z"
  }
}

2. Assign the token-authenticated 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.

You can use the following sample request, making sure to:

  • Set stream_target_id to the id listed in the response from step 1. 
  • Set transcoder_id to the id for the transcoder.
  • Set output_id to the id for the output rendition.

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "output_stream_target": {
     "stream_target_id": "1234abcd"
   }
 }' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/outputs/[output_id]/output_stream_targets/"

Sample response

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

3. 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 languages. We've provided a Wowza CDN on Fastly Token Authentication examples GitHub repository to help you get started. Various parameters can be used along with the token_auth_shared_secret. To learn more, see the code example Readme.

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

[playback_URL]?hdnts=[parameters_and_hashed_token]

For example:

https://[subdomain].wowza.com/1/[stream_id]/[stream_name]/hls/live/playlist.m3u8?hdnts=exp=1578424041~hmac=0428782df32a8a8b91823889756d8084997cf45c58375d526dc9852808b35721

Related request