Send streams securely to Wowza CDN on Akamai with the Wowza Streaming Cloud REST API

With the secure ingest feature, the Wowza Streaming Cloud™ service allows you to secure a stream with a query parameter as it passes from a transcoder to Wowza CDN. When Wowza CDN ingests the stream from the transcoder, it requires the query parameter for processing. This prevents third parties from overriding the contents of your stream with unwanted content. In this article, learn how to enable secure ingest for Wowza CDN on Akamai stream targets using the Wowza Streaming Cloud REST API.

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.

You should complete the following tasks:

  • Install the latest firmware installed for your encoder.

You should have access to the following items:

  • The encoder's user guide for details about how to operate the device or software and how to specify settings such as resolution, bitrate, and frame rate.

Create a transcoder with a secure Akamai stream target

1. Create a transcoder

Create a passthrough or transcoded (adaptive bitrate) transcoder with a push or pull connection, depending on your needs and the functionality available at your broadcast location.

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

  • Set protocol to the transport protocol for the source video.
  • Set broadcast_location to the region that's closest to your video source.
  • Set delivery_method to push or pull.
  • Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.

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 '{  
   "transcoder": {  
     "billing_mode": "pay_as_you_go",  
     "broadcast_location": "us_central_iowa",  
     "buffer_size": 4000,  
     "delivery_method": "push",  
     "name": "My secure ingest transcoder",  
     "protocol": "rtmp",  
     "transcoder_type": "transcoded"  
  }  
}' \
"${WSC_HOST}/api/${WSC_VERSION}/transcoders"

Sample response

The response includes:

  • An ID for the transcoder that you'll use throughout the rest of this task.
  • An empty outputs array that you'll configure in step 3.
  • source_connection_information you'll use in step 4 to configure a source for the stream. 
    • domain_name, source_port, application_name, and stream_name
{  
  "transcoder": {  
    "id": "abcvwp8k",  
    "name": "My secure ingest transcoder",  
    "transcoder_type": "transcoded",  
    "billing_mode": "pay_as_you_go",  
    "broadcast_location": "us_west_california",  
    ... 
    "protocol": "rtmp",  
    "delivery_method": "push",  
    "source_port": 1935,  
    "domain_name": "[wowza-subdomain].entrypoint.cloud.wowza.com",  
    "application_name": "app-B8P6K226",  
    "stream_name": "805e7031",  
    ...    
    "direct_playback_urls": {  
        "rtmp": ["names and urls returned here"],  
        "rtsp": ["names and urls returned here"],  
        "wowz": ["names and urls returned here"],  
        "webrtc": ["names and urls returned here"]  
    },  
    "outputs": [],  
  }  
}

2. Create a Wowza CDN on Akamai stream target

Now that you have created a transcoder, you'll create a stream target that will be associated with the transcoder in the next step.

Note: Secure ingest is only available for Wowza CDN on Akamai stream targets with the provider akamai_cupertino.

Create a Wowza CDN on Akamai stream target by sending a POST request to the /stream_targets/akamai endpoint.

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

  • Set provider to akamai_cupertino, which provides playback over HLS.
  • Set use_secure_ingest to true to deliver the HLS stream securely between the transcoder and the Wowza CDN.
  • Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.

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_akamai": { 
      "name": "My secure target", 
      "provider": "akamai_cupertino", 
      "use_secure_ingest": true 
    } 
  }' \

"${WSC_HOST}/api/${WSC_VERSION}/stream_targets/akamai" 

Sample response

The response includes:

  • A secure_ingest_query_param value, which is used to secure the connection between the transcoder and the CDN. 
{ 
  "stream_target_akamai": { 
     "id": "8cxwdlvg", 
      "name": "My secure target", 
      "provider": "akamai_cupertino", 
      "use_secure_ingest": true, 
      "secure_ingest_query_param": "[automatically generated query string]", 
      "use_cors": false, 
      "stream_name": "bc6859bf", 
      "primary_url": "http://[wowzasubdomain]-i.akamaihd.net/687319/bc6859bf", 
      "delivery_protocols": [
            "hls"
        ],
      "playback_urls": {
            "hls": [
                {    
                    "name": "default",
                    "url": "https://[wowzasubdomain]-i.akamaihd.net/hls/live/687319/bc6859bf/playlist.m3u8"
                }
            ]
        }, 
      "connection_code": "1QAbz9", 
      "connection_code_expires_at": "2018-08-29T13:50:34.000Z", 
      "created_at": "2018-08-28T13:50:34.000Z", 
      "updated_at": "2018-08-28T13:50:34.000Z"
  } 
}

3. Add output renditions and stream targets


Complete the transcoder by adding output renditions and stream targets. For instructions, see one of the following articles, depending on whether you're creating an adaptive bitrate or passthrough transcoder:

Note: You'll need the transcoder ID from step 1.

4. Configure your video source


Use the the domain_name, source_port, application_name, stream_name, username and password values returned when you created the transcoder to configure your RTMP encoder. You'll need to refer to documentation for your specific encoder to determine where to input the stream settings and user credentials for authentication.

If you were configuring OBS as the encoder, you'd enter the following stream settings in OBS:

  • URL is formatted as:
    rtmp://[domain_name]:[source_port]/[application_name]
    Where:
    • [domain_name] is the ingest location of the server
    • [source_port] is the port (by default 1935)
    • [application_name] is the application name for the stream assigned by Wowza Streaming Cloud
       
  • Stream key is the stream_name value, such as b01bda67.
  • Username and Password are the username and password values.

Other encoders might use different names in their user interface, like Address instead of URL and Stream instead of Stream key. Make sure to refer to your encoder's documentation to determine the correct locations.

Tip: This topic uses the push delivery method. If you use the pull delivery method, configure the source by determining and providing the source_url value when creating the transcoder. The source_url must be an RTMP URL with a publicly accessible hostname or IP address.

5. Test the connection


Now that you have configured your source, you can test your transcoder. You'll need the [transcoder_id] returned in step 1.

When you start the transcoder and begin sending the source stream from a configured camera or encoder, Wowza CDN parses the secure_ingest_query_param value to authorize the incoming stream from the transcoder.

  1. Start the transcoder.

    Endpoint Reference

    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/start"
  2. Check the state to make sure the transcoder started.

    Endpoint Reference

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/state"
  3. Start the stream in the RTMP encoder. How you start the encoder varies by device.
  4. Fetch a URL to a thumbnail that you can enter into a browser and visually confirm the stream is playing.

    Endpoint Reference

    curl -X GET \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/thumbnail_url"
  5. Stop the transcoder.

    Endpoint Reference

    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/stop"
  6. Stop the stream in the source camera or encoder.

More resources