Set referer policy for Wowza CDN on Fastly stream targets with the Wowza Streaming Cloud REST API

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 Streaming Cloud 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. 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.

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

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": "MyHLSTarget",
     "referer_enabled": true,
     "referer_allow_empty": false,
     "referer_policy": "allow",
     "referer_domains": "example.com, example2.com"
   }
 }' "${WSC_HOST}/api/${WSC_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

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

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/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