Control access to a stream by setting a referer policy that allows or blocks access, depending on the domain that’s requesting (the referer) the access. When you enable and configure the referer policy, clients and players requesting access to the stream must send a Referer header and must meet the policy requirements you've set for the stream target to gain access. You can use this functionality to prevent unauthorized websites from hosting a stream you own.
You can only set a referer policy for a Wowza CDN on Fastly stream target and only using the Wowza Video REST API.
For more information about the Referer header, see the HTTP specification.
Before you start
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.
1. Create a Wowza CDN on Fastly stream target with configured referer policy
Enable and configure the referer policy when you create a Wowza CDN on Fastly stream target.
The following sample request generates a Wowza CDN on Fastly stream target for HLS playback with a referer policy that allows requests from two domains to access the stream.
Note: While less secure, if you know you'll have viewers with a client or player that won't send a Referer header, you can specify true for referer_allow_empty to allow an empty Referer header so those viewers can still access the stream.
Sample request
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
"stream_target_fastly": {
"name": "MyHLSTarget",
"referer_enabled": true,
"referer_allow_empty": false,
"referer_policy": "allow",
"referer_domains": "example.com, example2.com"
}
}' "${WV_HOST}/api/${WV_VERSION}/stream_targets/fastly"
About referer_domains
We recommend you enter the simplest form of the domain as possible, however you do need to build out the domain to the level of subdomains you want to allow or deny. You can fully express to the subdomain (mysubdomain.example.com) to specify that single, specific subdomain or you can use a wildcard (*) to cover all subdomains at a specific level (*.example.com).
Example: example.com, *.example.com, *.mysubdomain.example.com
If you entered the above example value for referer_domains, and referer_policy is allow, the following domains are allowed access to the stream:
- https://example.com
- https://subdomain.example.com, https://subdomain2.example.com, etc.
- https://subdomainA.mysubdomain.example.com, https://subdomainB.mysubdomain.example.com, etc.
Sample response
The details of the configured target are listed in the response, which should look something like this:
{
"stream_target_fastly": {
"id": "1234abcd",
"name": "MyHLSTarget",
"state": "activated",
"stream_name": "st1r2eam",
"playback_urls": {
"hls": [
{
"name": "default",
"url": "https://[subdomain].wowza.com/1/[stream_id]/[stream_name]/hls/live/playlist.m3u8"
}
]
},
"force_ssl_playback": false,
"token_auth_enabled": false,
"token_auth_playlist_only": false,
"geoblock_enabled": false,
"referer_enabled": true,
"referer_allow_empty": false,
"referer_policy": "allow",
"referer_domains": "example.com, example2.com",
"created_at": "2021-02-23T16:04:23.170Z",
"updated_at": "2021-02-23T16:04:23.170Z"
}
}
If you change referer_enabled to false after configuring the referer policy, then later re-enable it, you'll need to re-configure the other referer policy values as well.
Related requests
- PATCH /stream_targets/fastly/[ID] — Set or update the referer policy for an existing Wowza CDN on Fastly stream target.
- GET /stream_targets/fastly/[ID] — Get the details of the referer policy for an existing Wowza CDN on Fastly stream target.
2. Assign the stream target to a transcoder
Assign the configured stream target to a transcoder's output rendition. This topic assumes you have a transcoder and output renditions for the transcoder, as you'll need their IDs in the following sample request.
The following request adds the configured stream target 1234abcd to the output rendition whose ID is 5678efgh for the transcoder 9012ijkl.
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/9012ijkl/outputs/5678efgh/output_stream_targets/"
Sample response
The details of the configured target are listed in the response, which should look something like this:
{
"output_stream_target": {
"stream_target_id": "1234abcd"
}
}
More resources
- Security features in Wowza Video
- Create an ABR stream and send it to a target with the Wowza Video REST API — Provides examples for creating a transcoder and outputs.
