Manage user authentication for Apple HLS streams with the Wowza Streaming Cloud REST API

When you broadcast an Apple HLS stream using the  Wowza Streaming Cloud™ service, you have control over  whether or not the source encoder must use user authentication in order to publish an RTMP or RSTP stream. User authentication provides a secure connection from the source encoder into the ingest origin server for Wowza Streaming Cloud and prevents third parties from connecting to and altering your stream.

This article shows how to use the Wowza Streaming Cloud REST API to create a live stream or transcoder with user authentication for RTMP and RTSP streams that are delivered to Wowza Streaming Cloud with a push or pull connection. It also provides information on configuring a source encoder so that it can be authenticated for connection, and it points to information on securing Apple HLS streams during playback.

Create a live stream with user authentication


You can use a live stream workflow or a transcoder workflow in Wowza Streaming Cloud. The live stream workflow allows you to configure more settings in one API request, while the transcoder workflow allows more modular configuration of settings using multiple API requests. Start with this section if you choose the live stream workflow.

Push stream

Follow these steps to create a live stream with a push connection and user authentication. A push stream indicates that your video source will push the stream to Wowza Streaming Cloud.

  1. If you are using the live stream workflow, use the Wowza Streaming Cloud REST API to create a live stream, keeping the following in mind:
    • When you create a live stream with a push connection over RTMP or RTSP, user authentication is required by default. You don't have to configure any parameters to enable it.
    • You can choose to configure your own username and password values for authentication. The username and password values are case-sensitive and can only contain alphanumeric, period (.), underscore (_), and hyphen (-) characters. If you don't include them in your request to create the live stream, Wowza Streaming Cloud will assign username and password values for you and return them in the response.
    • Ensure that delivery_method is set to push.
    Note: You can also use user authentication if you have set up and enabled an Akamai stream source that sends your stream to Wowza Streaming Cloud using RTMP. If you are using a stream source, the delivery_method defaults to cdn when creating or updating your live stream.
    See Live Streams from the Wowza Streaming Cloud API reference for more information on available settings for a live stream.

    Example request and response

    The following request generates a live stream with a push connection that uses a generic RTMP source encoder as the video source and includes a player and hosted page.

    Notes:
    • For [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
    • For [version], substitute the version number of the API that you're using. For the current version, use v1.2.

    Create a live stream

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{ 
     "live_stream": { 
      "aspect_ratio_height": 1080, 
      "aspect_ratio_width": 1920, 
      "billing_mode": "pay_as_you_go", 
      "broadcast_location": "us_west_california", 
      "encoder": "other_rtmp", 
      "name": "User authenticated live stream", 
      "transcoder_type": "transcoded", 
      "delivery_method": "push", 
      "hosted_page": true, 
      "hosted_page_title": "My Hosted Page", 
      "password": "abcPassword", 
      "player_responsive": true, 
      "player_type": "wowza_player", 
      "username": "clientABC" 
     } 
    }' "https://api.cloud.wowza.com/api/[version]/live_streams" 
    
    Note: If you need to disable authentication, set disable_authentication to true in the request above.

    This request creates a live stream with an id parameter, an associated player, and a hosted page. The details of the live stream's configuration are listed in the response, which should look something like this:

    { 
      "live_stream": { 
        "id": "8bwzg5vj", 
        "name": "User authenticated live stream", 
        "transcoder_type": "transcoded", 
        "billing_mode": "pay_as_you_go", 
        "broadcast_location": "us_west_california", 
        ... 
        "encoder": "other_rtmp", 
        "delivery_method": "push", 
        "delivery_protocol": "hls-https", 
        "target_delivery_protocol": "hls-https", 
        ...
        "source_connection_information": { 
          "primary_server": "rtmp://[wowzasubdomain].entrypoint.cloud.wowza.com/app-1670", 
          "host_port": 1935, 
          "stream_name": "b6232dcb", 
          "disable_authentication": false, 
          "username": "clientABC", 
          "password": "abcPassword" 
        }, 
        "player_id": "zxn5prrj", 
        "player_type": "wowza_player", 
        ...
        "player_embed_code": "in_progress", 
        "player_hls_playback_url": "https://[wowzasubdomain]-i.akamaihd.net/hls/live/687322/979dbcfd/playlist.m3u8", 
        "hosted_page": true, 
        ...
        "stream_targets": [ 
          { 
            "id": "bnlbnb8p" 
          } 
        ], 
        "direct_playback_urls": { 
          "rtmp": ["names, output_ids, and urls returned here"], 
          "rtsp": ["names, output_ids, and urls returned here"], 
          "wowz": ["names, output_ids, and urls returned here"] 
        }, 
        "created_at": "2018-08-03T18:57:59.000Z", 
        "updated_at": "2018-08-03T18:57:59.000Z", 
      } 
    } 
  2. Use details from the source connection information to configure the source encoder or camera. See Configure a source for next steps.

Pull stream

Follow these steps to create a live stream with a pull connection and user authentication. A pull stream indicates Wowza Streaming Cloud pulls your stream from the encoder or IP camera.

  1. Create a live stream using the Wowza Streaming Cloud REST API.

    In your POST /live_streams request, insert your authentication information for the source encoder or IP camera, such as username and password, into the source_url value. Authentication information included in the source_url can only contain alphanumeric, period (.), underscore (_), and hyphen (-) characters. Refer to documentation for your encoder or camera for information on the syntax of the source_url and available methods of source authentication. The source_url for your camera or encoder must include a publicly accessible hostname or IP address. 

    Example request and response

    The following request generates a live stream that uses a RTSP source encoder or camera as the video source.

    Create a live stream

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{ 
      "live_stream": { 
        "aspect_ratio_height": 1080, 
        "aspect_ratio_width": 1920, 
        "billing_mode": "pay_as_you_go", 
        "broadcast_location": "us_west_california", 
        "encoder": "other_rtsp", 
        "name": "User authenticated pull live stream", 
        "transcoder_type": "transcoded", 
        "delivery_method": "pull", 
        "hosted_page": true, 
        "hosted_page_title": "My Hosted Page", 
        "player_responsive": true, 
        "player_type": "wowza_player", 
        "source_url": "rtsp://username:password@123.233.456.205/media/video1" 
     } 
    }' "https://api.cloud.wowza.com/api/[version]/live_streams" 

    This creates a live stream with an id parameter, an associated player, and a hosted page. The details of the live stream's configuration are in the source_url value. The response should look something like this:

    { 
      "live_stream": { 
        "id": "qvkzmjk6", 
        "name": "User authenticated pull live stream", 
        "transcoder_type": "transcoded", 
        "billing_mode": "pay_as_you_go", 
        "broadcast_location": "us_west_california", 
        "recording": false,
        "closed_caption_type": "none", 
        "low_latency": false, 
        "encoder": "other_rtsp", 
        "delivery_method": "pull", 
        ... 
        "source_connection_information": { 
                "source_url": "rtsp://username:password@123.233.456.205/media/video1" 
        }, 
        "player_id": "fbyc5p88", 
        "player_type": "wowza_player", 
        "player_responsive": true, 
        "player_countdown": false, 
        "player_embed_code": "in_progress", 
        "player_hls_playback_url": "https://[wowzasubdomain]-i.akamaihd.net/hls/live/687321/d9ca82ad/playlist.m3u8", 
        "hosted_page": true, 
        ... 
        "stream_targets": [ 
          { 
            "id": "0wy3txlt" 
          } 
        ], 
        "direct_playback_urls": { 
          "rtmp": ["names, output_ids, and urls returned here"], 
          "rtsp": ["names, output_ids, and urls returned here"], 
          "wowz": ["names, output_ids, and urls returned here"] 
        }, 
        "created_at": "2018-08-08T22:19:51.000Z", 
        "updated_at": "2018-08-08T22:19:51.000Z" 
      }
    } 
  2. Next, configure your source. See Configure a source for next steps.

Create a transcoder with user authentication


You can use a live stream workflow or a transcoder workflow in Wowza Streaming Cloud. The live stream workflow allows you to configure more settings in one API request, while the transcoder workflow allows more modular configuration of settings using multiple API requests. Start with this section if you choose the transcoder workflow.

Push stream

Follow these steps to create a transcoder with a push connection and user authentication. A push stream indicates that your video source will push the stream to Wowza Streaming Cloud.

  1. If you are using the transcoder workflow, use the Wowza Streaming Cloud REST API to create a transcoder, keeping the following in mind:
    • When you create a transcoder, user authentication is required by default. You don't have to configure any parameters to enable it.
    • You can choose to configure your own username and password values for authentication. The username and password values are case-sensitive and can only contain alphanumeric, period (.), underscore (_), and hyphen (-) characters. If you don't include them in your request to create the transcoder, Wowza Streaming Cloud will assign username and password values for you and return them in the response.
    • Ensure that delivery_method is set to push.
    Note: You can also use user authentication if you have set up and enabled an Akamai stream source that sends your stream to Wowza Streaming Cloud using RTMP. If you are using a stream source, set your delivery_method to cdn when creating or updating your transcoder.

    Example request and response

    The following request generates a transcoder that uses a RTMP source encoder as the video source.

    Create a transcoder

        curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{    
      "transcoder": { 
        "billing_mode": "pay_as_you_go",      
        "broadcast_location": "us_west_california",      
        "delivery_method": "push",      
        "name": "My user authenticated push transcoder",      
        "protocol": "rtmp",      
        "transcoder_type": "transcoded", 
        "username": "user123", 
        "password": "abcPassword" 
      } 
    }' "https://api.cloud.wowza.com/api/[version]/transcoders" 

    This request creates a transcoder with an id parameter, but no outputs or stream targets. The details of the transcoder's configuration are listed in the response, which should look something like this:

    { 
      "transcoder": { 
        "id": "tmd8ybp2", 
        "name": "My user authenticated push 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": "[wowzasubdomain].entrypoint.cloud.wowza.com", 
        "application_name": "app-ca51", 
        "stream_name": "b40618d9", 
        ...
        "disable_authentication": false, 
        "username": "user123", 
        "password": "abcPassword", 
        "watermark": false, 
        "created_at": "2018-08-03T19:34:26.000Z", 
        "updated_at": "2018-08-03T19:34:26.000Z", 
        "direct_playback_urls": { 
          "rtmp": ["name and url returned here"], 
          "rtsp": ["name and url returned here"], 
          "wowz": ["name and url returned here"] 
        }, 
        "outputs": []
      } 
    } 
  2. 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:
  3. Next, configure the source encoder. See Configure a source for next steps.

Pull stream

Follow these steps to create a transcoder with a pull connection and user authentication. A pull stream indicates that Wowza Streaming Cloud pulls your stream from the encoder or IP camera.

  1. Create a transcoder using the Wowza Streaming Cloud REST API.

    In your POST /transcoders request, insert your authentication information for the source encoder or IP camera, such as username and password, into the source_url value. Authentication information included in the source_url can only contain alphanumeric, period (.), underscore (_), and hyphen (-) characters. Refer to documentation for your encoder or camera for information on the syntax of the source_url and available methods of source authentication. The source_url for your camera or encoder must include a publicly accessible hostname or IP address.

    Example request and response

    The following request generates a transcoder that uses a RTSP source encoder as the video source.

    Create a transcoder

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{    
      "transcoder": { 
        "billing_mode": "pay_as_you_go",      
        "broadcast_location": "us_west_california",      
        "delivery_method": "pull",      
        "name": "My user authenticated pull transcoder",      
        "protocol": "rtsp",      
        "transcoder_type": "transcoded", 
        "source_url": "rtsp://username:password@123.233.456.205/media/video1" 
      } 
    }' "https://api.cloud.wowza.com/api/[version]/transcoders"

    This request creates a transcoder with an id, but no outputs or stream targets. The details of the transcoder's configuration are listed in the response, which should look something like this:

    { 
      "transcoder": { 
        "id": "jxzs0rnh", 
        "name": "My user authenticated pull transcoder", 
        "transcoder_type": "transcoded", 
        "billing_mode": "pay_as_you_go", 
        "broadcast_location": "us_west_california", 
        ...
        "protocol": "rtsp", 
        "delivery_method": "pull", 
        "source_url": "rtsp://username:password@123.233.456.205/media/video1", 
        "delivery_protocols": [ 
          "rtmp", 
          "rtsp", 
          "wowz", 
          "hls" 
        ], 
        ...
        "disable_authentication": false, 
        "watermark": false, 
        "created_at": "2018-08-09T14:27:13.000Z", 
        "updated_at": "2018-08-09T14:27:13.000Z", 
        "direct_playback_urls": { 
          "rtmp": ["name and url returned here"], 
          "rtsp": ["name and url returned here"], 
          "wowz": ["name and url returned here"] 
        }, 
        "outputs": [] 
      } 
    }
  2. 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:
  3. Next, configure the source encoder. See Configure a source for next steps.

Configure a source


  1. Make sure you have the latest firmware for your encoder installed or have upgraded to the latest software updates. See the encoder's user guide for details about how to update firmware as well as how to operate the encoder and how to specify settings such as resolution, bitrate, and frame rate.
  2. Do one of the following, depending on your workflow and stream type:
    Push stream
    • If you created a live stream, see the source connection information from the POST /live_streams response for primary_server, host_port, and other details your encoder may need to connect to Wowza Streaming Cloud. Use the password and username from the response to authenticate your encoder.
    • If you created a transcoder, see the POST /transcoders response for source_port, domain_name, application_name, and stream_name values and other details your encoder may need to connect. Use the password and username from the response to authenticate your encoder.
    Pull stream
    • For an RTMP or RTSP pull connection, such as an IP camera, you configure the source by determining and providing the source_url value when creating the live stream or transcoder.

Test the connection


  1. Once your source encoder is configured, start the live stream or transcoder using the Wowza Streaming Cloud REST API.
    For a pull stream, ensure that your camera and source encoder are streaming when you start the transcoder so that the stream can be pulled into Wowza Streaming Cloud.

    Example requests

    Start the live stream

    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]/start" 

    Start the transcoder

    curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/start" 

Configure secure playback


To increase security on the playback side, see these articles: