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.
Note: Token authentication works with third-party players. It doesn't work with a player created in the Wowza Video live stream workflow and embedded in a hosted or third-party webpage.
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.
Sample request
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)
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
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=[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
- PATCH /stream_tragets/fastly/[fastly_stream_target_id] — Update the token authentication applied to a stream target. Assign the stream target to a transcoder
