Viewer Authentication API

Introduction

Viewer Authentication API lets you implement custom authentication for authenticating viewers of live and recorded videos served by IBM Cloud Video.

Viewer authentication flows

The Viewer Authentication API provides two flows for authenticating viewers:
  • Basic: Authentication happens inside the IBM Cloud Video player. The player will require the viewer to enter a username and a password.
  • Advanced: Lets you implement a fully custom authentication.

You need the following before you start implementing viewer authentication:

  • Channel, which you can create on the Your channels page of your IBM Cloud Video dashboard
  • Client id, which you can obtain on the API/SDK access page of your IBM Cloud Video dashboard
  • Token, which you obtain through the IBM Cloud Video authorization endpoint
  • Secret key, a string that will be used to create the hash in the authentication response your service passes to the IBM Cloud Video player.

Basic viewer authentication flow

  1. Viewer credentials entered in the IBM Cloud Video player are passed to your service endpoint in an authentication request.
  2. Your service endpoint validates the request and passes an authentication response to the player.
  3. If the authentication was successful, the player passes the authentication response to IBM Cloud Video infrastructure in a validation request.
  4. The IBM Cloud Video infrastructure validates the authentication response received from your service and passes a validation response to the player. If this response is positive, the viewer can start watching the video.

This flow requires less work on your end but your possibilities are limited. You can only authenticate your viewers with a username and a password.

Creating an authentication service endpoint

To implement the basic viewer authentication flow you need to create an authentication service endpoint for validating authentication requests.

The IBM Cloud Video player calls the URL of the endpoint to pass the authentication request to your service. It is called in the background by passing the username and password in GET parameters. The parameters are called "user" and "pw".

For example, if the URL of your endpoint is http://mydomain.com/authentication.php, the call will be:

http://mydomain.com/authenticaiton.php?user=debbiehamilton&pw=lYOWp8tn

When called, the endpoint should validate the authentication request and pass an authentication response back to the player. The authentication response must be a JSON encoded value.

  • If the authentication fails: false
  • If the authentication is successful: an array which contains the following:
    • list of parameters that have been hashed
    • the MD5 hash of the string that has been created by concatenating the parameters and the shared secret key with pipe "|" characters

An example array:


[
   {
      "userName": "testuser"
   },
   {
      "someString": "someValue"
   },
   {
      "hash": "56a8835175d33c368955dac6bdaf00de"
   }
]
        
The order of the parameters should match their order in the array when generating the hash.

Example service endpoint script in PHP


<?php

// This is a simple script to showcase an authentication service endpoint.

// We assume that you have a config file loaded from somewhere.

// This is your shared secret key.
$SHARED_SECRET_KEY = "testMyHash";

// The script has to validate if provided user credentials are correct.
// For simplicity in this example we only check if user name is “testuser”.
// You should implement a more advanced validation,
// eg. checking the user name and the password against a database.
if (isset($_GET["user"]) && $_GET["user"] == "testuser") {
	// On success the response has to be an array of parameters
	// and a hash.

	// We create the array of paramters.
	// The parameters can be anything.
	$userData = [
		"username" => $_GET["user"],
		"someString" => "someValue"
	];

	// We create the hash by hashing the array contents
	// and the secret key concatenated together with a pipe character.
	$hash = md5(implode('|', $userData) . '|' . $SHARED_SECRET_KEY);

	// We put the array of parameters and the hash into the response.
	$response = array_chunk(
		array_merge($userData, ["hash" => $hash]),
		1,
		true
	);
} else {
	// On failure the response has to be false.
	$response = false;
}

// We encode the output into JSON format.
$json = json_encode($response);

// We create the JSONP callback.
echo isset($_GET['jsoncallback'])
	? "{$_GET['jsoncallback']}($json)"
	: $json;
        

Setting up basic viewer authentication

PUT https://api.ustream.tv/channels/CHANNEL_ID/locks/hash/basic.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
url string REQUIRED URL of authentication service endpoint
secret string REQUIRED Secret key
Response

HTTP response codes returned when the action is successful:

HTTP response code Error conditions
201 Created Basic viewer authentication has been set up on the channel with the new hash.
204 No Content Basic viewer authentication has been set up on the channel by updating the existing hash with the new one.

Specific error codes returned when the action failed:

error value HTTP response code Error conditions
invalid_request 400 Bad Request One or more required parameters are missing or the user has no access to the video.
invalid_type 400 Bad Request The specified type is invalid or unsupported.

Advanced viewer authentication flow

  1. When the viewer clicks the log in button in the IBM Cloud Video player the entry point of your custom authentication flow is displayed in a popup window.
  2. When the authentication is completed your service passes an authentication response to the player.
  3. If the authentication was successful, the player passes the authentication response to IBM Cloud Video infrastructure in a validation request.
  4. The IBM Cloud Video infrastructure validates the authentication response received from your service and passes a validation response to the player. If the response is positive, the viewer can start watching the video.

This flow requires more work on your end but you get full control over the user experience of the authentication flow.

Implementing the authentication response

When the authentication was successful your service has to pass an authentication response to the player. The authentication response must be a JSON encoded array which contains the following:

  • list of parameters that have been hashed
  • the MD5 hash of the string that has been created by concatenating the parameters and the shared secret key with pipe "|" characters

An example array:


[
    {
        "userName": "testuser",
    },
    {
        "someString": "someValue"
    },
    {
        "hash": "56a8835175d33c368955dac6bdaf00de"
    }
]
        
The order of the parameters should match their order in the array when generating the hash.

To pass the response to the player your service has to redirect the page to the IBM Cloud Video return URL with passing the URL encoded hash as a get parameter.

http://www.ustream.tv/embed/hashlock/pass?hash=HASH

Setting up advanced viewer authentication

PUT https://api.ustream.tv/channels/CHANNEL_ID/locks/hash/advanced.FORMAT (format can be json or xml)
Parameters
parameter type importance Description
url string REQUIRED URL of the authentication flow entry point
secret string REQUIRED Secret key
message string REQUIRED Short text above the button on the screen displayed in the player
button_caption string REQUIRED Text of the the button on the screen displayed in the player
popup_width int REQUIRED Width of the popup window with the authenticaion flow
popup_height string REQUIRED Height of the popup window with the authenticaion flow
Response

HTTP response codes returned when the action is successful:

HTTP response code Error conditions
201 Created Advanced viewer authentication has been set up on the channel with the new hash.
204 No Content Advanced viewer authentication has been set up on the channel by updating the existing hash with the new one.

Specific error codes returned when the action failed:

error value HTTP response code Error conditions
invalid_request 400 Bad Request One or more required parameters are missing or the user has no access to the video.
invalid_type 400 Bad Request The specified type is invalid or unsupported.

Managing viewer authentication settings

Getting viewer authentication settings

GET https://api.ustream.tv/channels/CHANNEL_ID/locks/hash.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

Key-value pairs under a "hashlock" key.

Example:


{
    "hashlock": {
        "type": "advanced",
        "url": "https://align.ustream.tv/auth/123",
        "message": null,
        "button_caption": null,
        "popup_width": "0",
        "popup_height": "0"
    }
}
        

Removing viewer authentication

DELETE https://api.ustream.tv/channels/CHANNEL_ID/locks/hash.FORMAT (format can be json or xml)
Parameters

This request has no parameters.

Response

On success the 200 OK HTTP response code is returned.

Hash lifetime and expiration

Once is successfully validated by IBM Cloud Video, the player will store the hash in the end user’s browser. This lets the viewer watch the video when returning to the page without having authenticate again.

You can specify an expiration date for the hash. When the viewer returns to the page after the expiration date, she has to authenticate again.

The expiration date has to be

  • Part of the hash by concatenating it to the rest of the parameters
  • Included in the response object as “hashExpire”.

Expiration date has to be

  • Specified in UNIX timestamp format
  • Include in the response JSON object

An example array:


[
    {
        "userName": "testuser",
    },
    {
        "someString": "someValue"
    },
    {
        "hash": "56a8835175d33c368955dac6bdaf00de"
    },
    {
        "hashExpire": 1333521590
    }
]
        

When validating the authentication response the IBM Cloud Video infrastructure checks

  • If the expiration is a past date
  • If the expiration was hashed properly

This way we can make sure that the expiration date comes from you and it has not been tampered on the client side.

Example script in PHP for specifying hash expiration date


// Expiration date must be specified as UNIX timestamp.
// We create a hash which is valid for one hour.
$expiration = time()+3600;

// We concatenate it to the params, and generate the hash.
$hash = md5(implode('|', $userData).'|'.$expiration.'|'.$SHARED_SECRET_KEY);