How to change the authentication method for the Wowza Streaming Engine REST API

The Wowza Streaming Engine™ media server software REST API can be used to configure, manage, and monitor the media server through HTTP requests. This article describes how to change the way REST API requests are authenticated.

Note: Wowza Streaming Engine software version 4.5.0.03 or later is required for the remote HTTP and digest-file authentication methods.

Installation


If you updated your Wowza Streaming Engine software to version 4.5.0.03 or later using a ZIP file, your software installation may need to manually add the properties required to configure additional authentication methods for the REST API.

Configuration


There are five supported authentication configurations: none, basic, digest, remotehttp, and digestfile. To change the authentication configuration, open the [install-dir]/conf/Server.xml in a text editor, and change the <RESTInterface>/<AuthenticationMethod> value. For more information, see:

Digest authentication
Disable authentication
HTTP basic authentication
Digest password file authentication Remote HTTP authentication

Digest authentication

This is the default REST API authentication method for Wowza Streaming Engine software. It uses a plain-text username/password format in a digest password file ([install-dir]/conf/admin.password). When using this method, the <RESTInterface>/<AuthenticationMethod> property looks like this:

<AuthenticationMethod>digest</AuthenticationMethod>

Disable authentication

The REST API authentication can be disabled by setting the <AuthenticationMethod> to none in the Server.xml.

Set the <RESTInterface>/<AuthenticationMethod> property to:

<AuthenticationMethod>none</AuthenticationMethod>

When the <AuthenticationMethod> is set to none, requests to the REST API aren't authenticated.

HTTP basic authentication

To enable HTTP basic authentication, set the <RESTInterface>/<AuthenticationMethod> property to:

AuthenticationMethod>basic</AuthenticationMethod>

With the basic authentication method, the usernames and passwords are encoded with Base64. This change doesn't affect any stored passwords, rather it just changes how HTTP requests made to the REST API are authenticated.

Notes:
 
  • Wowza Streaming Engine Manager doesn't support basic authentication. If you're using the basic authentication method, all attempts to log in to Wowza Streaming Engine Manager will fail.
     
  • Because the usernames and passwords are stored as Base64-encoded values, the basic authentication method isn't considered secure.

Digest password file authentication

This method enables you to use digest passwords rather than passwords stored in plain text.

Set the <RESTInterface>/<AuthenticationMethod> property to:

AuthenticationMethod>digestfile</AuthenticationMethod>

To use the digestfile authentication method, you must generate a digest password and add it to the [install-dir]/conf/admin.password file:

  1. To generate a digest password, you need to create a MD5 signature of username:Wowza:password. For example, if you were to set a username and the password to test, this would generate an MD5 value of 881BA46BDC734BEFFD5B467470B68F85. Note that you must include the : and Wowza when generating the MD5.
     
  2. Add the username and generated digest password to the authentication file ([install-dir]/conf/admin.password), and save your changes. Using the example above, the entry in the admin.password file for the user would be:

    test 881BA46BDC734BEFFD5B467470B68F85 admin 
Note: When using this method, if you have a valid username/password at the administrator level, the Wowza Streaming Engine Manager automatically adds digest passwords when users are added.

Digest password file authentication for HTTP Providers

If you enable the use of digest passwords (the digestfile method) for the REST interface, you may also want to enable digest password authentication for the HTTP providers configured within your [install-dir]/conf/VHost.xml file. This is configured for each HTTP Provider individually. The following example demonstrates how to configure an HTTP Provider to use a digest password rather than passwords stored in plain text.

Set the <HTTPProvider>/<AuthenticationMethod> property to admin-file-digest:

<HTTPProvider>
	<BaseClass>com.wowza.wms.http.HTTPServerInfoXML</BaseClass>
	<RequestFilters>serverinfo*</RequestFilters>
	<AuthenticationMethod>admin-file-digest</AuthenticationMethod>
</HTTPProvider>

To use the admin-file-digest authentication method for HTTP Providers, you must generate a digest password and add it to the [install-dir]/conf/admin.password file. For more information on generating digest passwords, see generate a digest password.

Remote HTTP authentication

The REST API authentication can also be configured to use a remote HTTP server to authenticate REST API requests.

Set the <RESTInterface>/<AuthenticationMethod> property to:

AuthenticationMethod>remotehttp</AuthenticationMethod>

In order to configure the remote HTTP authentication method, you must also add the AuthenticationURL and AuthenticationURLSharedSecret configuration parameters to the [install-dir]/conf/Server.xml file immediately below the <AuthenticationMethod> property:

<AuthenticationURL>[remote-URL]</AuthenticationURL>	
<AuthenticationURLSharedSecret>[shared-secret-key]</AuthenticationURLSharedSecret>

Where the [remote-URL] can be HTTP or HTTPS and it must accept POST requests, and the [shared-secret-key] is used to generate a custom digest value and is sent in a HTTP header called WowzaRemoteAuthHash.

For example, if the HTTP requests should be sent to http://192.168.1.10/wseauthentication/ for authentication by the remote HTTP server and your shared secret key is MySharedSecretKey, the additional configuration parameters would be:

<AuthenticationURL>http://192.168.1.10/wseauthentication/</AuthenticationURL>	
<AuthenticationURLSharedSecret>MySharedSecretKey</AuthenticationURLSharedSecret>

A custom digest value is generated using the shared secret as well as some of the the authorization header values.

The authorization header, sent to the remote HTTP server, contains the Username, Response, and URI information. Using this information and the shared secret allows a matching WowzaRemoteAuthHash to be calculated and confirm the request is valid:

WowzaRemoteAuthHash = MD5 (Username+Response+SharedSecret+URI)

You can also get the REST API remote HTTP authentication request to send a server-specific header/value so that you can identify the server making authentication requests. To do this, add the configuration parameter:

<AuthenticationURLIdentity>MyServerIDName</AuthenticationURLIdentity>

This property adds an additional HTTP header that's sent for each remote authentication request called WowzaStreamingEngineIdentity. It's up to the remote authentication system to determine if it uses this header to identify requests. The WowzaStreamingEngineIdentity HTTP header isn't sent if the parameter isn't configured.

If a user is authenticated, the remote authentication service must return a header of AdministratorGroups, which must contain a comma separated list of groups the user is within. If this header isn't returned then the user is considered Read Only.

The following is an example PHP script that can be used on the remote server to authenticate two users: the first user is called cricket has administrator and advanced administrator rights, and the second user is called guest is read-only.

<?php
$realm = 'Wowza';

$users = array('cricket' => 'stumps', 'guest' => 'guest');
$sharedSecret = "MySharedSecretKey";
$serverIdentity = "MyServerIDName";

if (empty($_SERVER['PHP_AUTH_DIGEST']))
{
        header('HTTP/1.1 401 Unauthorized');
        header('WWW-Authenticate: Digest realm="'.$realm.'",qop="auth",nonce="'.uniqid().'",opaque="'.md5($realm).'"');
        exit(0);
}

$data = http_digest_parse($_SERVER['PHP_AUTH_DIGEST']);

if ( !isset($data['username']))
{
        header('HTTP/1.1 401 Unauthorized');
        exit(0);
}

// To create the wowzaHash value we do the following
// username+response+sharedSecret+uri

$validSharedHash = md5($data['username'].$data['response'].$sharedSecret.$data['uri']);

if ( strcmp ( $validSharedHash , $_SERVER['HTTP_WOWZAREMOTEAUTHHASH'] ) != 0 )
        {
        header('HTTP/1.1 401 Unauthorized');
        exit(0);
        }

if ( isset($_SERVER['HTTP_WOWZASTREAMINGENGINEIDENTITY']) )
        {
        if ( strcmp ( $serverIdentity , $_SERVER['HTTP_WOWZASTREAMINGENGINEIDENTITY'] ) !=0 )
                {
                header('HTTP/1.1 401 Unauthorized');
                exit(0);
                }
        }

$A1 = md5($data['username'] . ':' . $realm . ':' . $users[$data['username']]);
$A2 = md5($_SERVER['REQUEST_METHOD'].':'.$data['uri']);

// There are two digest authentication methods.

// If qop, cnonce, and nc are present, do this way
if ( isset($data['qop']) && isset($data['cnonce']) && isset($data['nc']) )
{
        $finished = $A1.':'.$data['nonce'].':'.sprintf("%08d",$data['nc']).':'.$data['cnonce'].':'.$data['qop'].':'.$A2;
        $valid_response = md5($finished);
}
// If not, do this way.
else
{
        $valid_response = md5($A1.':'.$data['nonce'].':'.$A2);
}

if ( strcmp ( $data['response'] , $valid_response ) != 0 )
        {
        header('HTTP/1.1 401 Unauthorized');
        exit(0);
        }

// If we got here, we're authenticated.

// The 'cricket' user is given admin and advance administrator permissions.

if ( strcmp($data['username'],"cricket") == 0 )
{
        header('AdministratorGroups: admin,advUser');
}

// The 'guest' user is made a read-only user. You don't have to specify readOnly
// because that's the default if no groups are set. readOnly included here for clarity.

if ( strcmp($data['username'],"guest") == 0 )
{
        header('AdministratorGroups: readOnly');
}

// Taken from PHP site as an example to handle string parsing.
function http_digest_parse($txt)
{
    $needed_parts = array('nonce'=>1, 'nc'=>1, 'cnonce'=>1, 'qop'=>1, 'username'=>1, 'uri'=>1, 'response'=>1);
    $data = array();
    $keys = implode('|', array_keys($needed_parts));
    preg_match_all('@(' . $keys . ')=(?:([\'"])([^\2]+?)\2|([^\s,]+))@', $txt, $matches, PREG_SET_ORDER);

    foreach ($matches as $m)
        {
        $data[$m[1]] = $m[3] ? $m[3] : $m[4];
        unset($needed_parts[$m[1]]);
        }

    return $data;
}
?>

Remote HTTP fallback authentication

With Wowza Streaming Engine 4.6.0.02 and later, is also possible to configure the remote HTTP authentication mechanism to revert back to the digest password file authentication method under certain circumstances, such as a failure to connect to the remote service or the return of a specific HTTP return code that indicates the HTTP service isn't available. By default, this is disabled.

To enable the fallback authentication method, add the following parameters just below the <RESTInterface>/<AuthenticationMethod>:

<AuthenticationURLBackupFile>true</AuthenticationURLBackupFile>
<AuthenticationURLBackupFileConditions>connect,500</AuthenticationURLBackupFileConditions>
<AuthenticationURLBackupFileRetry>30000</AuthenticationURLBackupFileRetry>

Where:

  • <AuthenticationURLBackupFile>, when set to true, causes the remote HTTP authentication mechanism to use the digest password in the [install-dir]/conf/admin.password file when the specified <AuthenticationURLBackupFileConditions> condition(s) are met. Note that the entries in the admin.password must be a digest password (not plain text).
     
  • <AuthenticationURLBackupFileConditions> is a comma-separated list that determines the circumstances in which the fallback authentication method should be used. This parameter is required to configure fallback authentication. Specify connect to enable fallback authentication if the remote HTTP service can't be reached and/or specify HTTP code(s), such as 500, that should trigger the use of the fallback authentication when returned.
     
  • <AuthenticationURLBackupFileRetry> controls the frequency, in milliseconds, at which the authentication system checks the remote HTTP service for availability. The default value is 30000. The specified value can't be less than 10000. This parameter is only required if you want to use a frequency other than the default.

The following is an example of configuring remote HTTP authentication with a fallback authentication method if the authentication server can't be reached or an HTTP 500 error code is returned:

<AuthenticationMethod>remotehttp</AuthenticationMethod>
<AuthenticationURL>http://192.168.1.10/wseauthentication/</AuthenticationURL>	
<AuthenticationURLBackupFile>true</AuthenticationURLBackupFile>
<AuthenticationURLBackupFileRetry>30000</AuthenticationURLBackupFileRetry>
<AuthenticationURLBackupFileConditions>connect,500</AuthenticationURLBackupFileConditions> 

Originally Published: on 10-18-2016.
Updated: For Wowza Streaming Engine 4.6.0.02 on 01-31-2017.
 

If you're having problems or want to discuss this article, post in our forum.