Protect a Wowza CDN on Fastly stream target with token authentication using the Wowza Video REST API

You can use the Wowza Video™ 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.

Before you start

You should complete the following tasks:

• Create a live stream or 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 . We use JSON web tokens for API authentication. See Authentication for more information.
• Environment variables . We use environment variables for the API version and your JWT 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 Video. 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 Video 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.

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 Video 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 .

  Note: MPEG-DASH streams

  • If you've enabled MPEG-DASH on your stream target, token_auth_playlist_only applies to both the playlist.m3u8 for HLS and manifest.mpd for MPEG-DASH.
  • If you're using MPEG-DASH with token_auth_playlist_only enabled and set a time-to-live (TTL) for the token, the TTL must cover the duration of the stream. If it's shorter than the duration of the stream, playback will stop when the token expires.

Sample request

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
   "stream_target_fastly": {
     "name": "My Secure Target",
     "token_auth_enabled": true,
     "token_auth_shared_secret":"12345678ABCDEF",
     "token_auth_playlist_only": true
   }
 }' "${WV_HOST}/api/${WV_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)

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 "Authorization: Bearer ${WV_JWT}" \
-d '{
   "output_stream_target": {
     "stream_target_id": "1234abcd"
   }
 }' "${WV_HOST}/api/${WV_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=[parametersandhashed_token]

For example:

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

Related request

• PATCH/stream_targets/fastly/ID — Update the token authentication applied to a stream target. Assign the stream target to a transcoder