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 a server through HTTP requests. By default, all requests are authenticated: The API validates your Wowza Streaming Engine administrator credentials before processing the request. You can change the authentication method to make it more (or less) secure.

Contents


Use digest authentication
Use basic HTTP authentication
Use digest HTTP authentication
Use remote HTTP authentication
     Add remote HTTP fallback authentication
Disable authentication

Use digest authentication


The default authentication method is digest. Digest authentication uses the plain-text username and password in the admin.password file (located in [install-dir]/conf).

Since it's the default, you don’t have to do anything to enable digest authentication, but if you switch to another method you can change back at any time.

  1. Navigate to [install-dir]/conf/ and open Server.xml in a text editor.
  2. Locate the <AuthenticationMethod> property in the <RESTInterface> section.
  3. Specify digest, like this:
<AuthenticationMethod>digest</AuthenticationMethod>
  1. Save your change.

Use basic HTTP authentication


Basic HTTP authentication applies Base64 encoding to the administrator's username and password as they're transmitted in the HTTP request. But although the credentials are encoded, they're not encrypted. As a result, basic HTTP authentication isn't considered secure unless it's used with HTTP over SSL (HTTPS).

Note: Wowza Streaming Engine Manager doesn't support basic HTTP authentication. If you enable basic HTTP authentication, you can't sign in to Wowza Streaming Engine Manager.
  1. Navigate to [install-dir]/conf/ and open Server.xml in a text editor.
  2. Locate the <AuthenticationMethod> property in the <RESTInterface> section.
  3. Specify basic, like this:
<AuthenticationMethod>basic</AuthenticationMethod>
  1. Save your change.

Use digest HTTP authentication


Digest authentication takes basic HTTP authentication one step further: It uses an MD5-hashed password when communicating requests to the API's web server. An MD5 hash encodes (digests) a string of any length into a 128-bit value represented by 32 ASCII-printable characters.

To use digest authentication, first specify digest file as your authentication method and then create the hashed password.

  1. Navigate to [install-dir]/conf/ and open Server.xml in a text editor.
  2. Locate the <AuthenticationMethod> property in the <RESTInterface> section.
  3. Specify digestfile, like this:
<AuthenticationMethod>digestfile</AuthenticationMethod>
  1. Save your change.

Now, generate an MD5-hashed digest password using a website such as md5hashgenerator.com.

  1. Generate a hash from the string

[your-admin-username]:Wowza:[your-admin-password]

For example, if your admin username is solomio and your admin password to secret, generate the hash from

solomio:Wowza:secret

which results in the hashed digest password

43c27fa10ce3ea64d60735c79e9f1c4f

Finally, add the hashed digest password to the admin.password file.

  1. Navigate to [install-dir]/conf/ and open admin.password in a text editor.
  2. Add a line to admin.password that contains the following:

[username][space][hashed digest password][space][group]

Using the example above, the line would be:

solomio 43c27fa10ce3ea64d60735c79e9f1c4f admin

  1. Save your change.
Note: After enabling digest password file authentication, Wowza Streaming Engine automatically creates a hashed digest password for new admin users.

If you use digest password authentication for REST API requests, you may also want to use it to authenticate your HTTP providers. You can add digest authentication to individual HTTP Providers in the VHost.xml file.

  1. Navigate to [install-dir]/conf/ and open VHost.xml in a text editor.
  2. Locate the <AuthenticationMethod> property in the desired <HTTPProvider> section.
  3. Specify admin-file-digest, like this:
<AuthenticationMethod>admin-file-digest</AuthenticationMethod>
  1. Save your change.

Use remote HTTP authentication


Remote HTTP authentication goes one step further than digest HTTP authentication: It uses a remote server to generate a custom digest value from a shared secret. That digest value is then included in an authorization header of your HTTP request to the REST API.

To use remote HTTP authentication, first specify it as your authentication method and then add the remote URL, the shared secret, and the authenticating server to the Server.xml file.

  1. Navigate to [install-dir]/conf/ and open Server.xml in a text editor.
  2. Locate the <AuthenticationMethod> property in the <RESTInterface> section.
  3. Specify remotehttp, like this:
<AuthenticationMethod>remotehttp</AuthenticationMethod>
  1. Add the <AuthenticationURL>, <AuthenticationURLSharedSecret>, and <AuthenticationURLIdentity> properties below the <AuthenticationMethod> property, like this:
<AuthenticationURL>[remote-URL]</AuthenticationURL>	
<AuthenticationURLSharedSecret>[shared-secret-key]</AuthenticationURLSharedSecret>
<AuthenticationURLIdentity>[authenticating-server-name]</AuthenticationURLIdentity>

For example, if the HTTP requests should be sent to http://192.168.1.10/wseauthentication/ for authentication by the remote HTTP server, your shared secret key is MySharedSecretKey, and the server requesting authentication is MyServerIDName, the additional properties would look like this:

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

Note: The remote URL can be HTTP or HTTPS and it must be able to accept POST requests.

  1. Save your change.

After configuring remote HTTP authentication on your Wowza Streaming Engine server, write a script that instructs the remote server to generate the custom digest value, includes the value in the authorization header, and authenticates a user.

The script should create the custom digest value WowzaRemoteAuthHash from the Wowza Streaming Engine user's username, the shared secret you added to the Server.xml file, and the requesting server's URI. It also includes a computed response that proves the user knows the password. The formula for the Wowza hash value looks like this:

WowzaRemoteAuthHash = MD5 ([username]+[response]+[shared secret]+[URI])

If a user is authenticated, the remote server should respond with an AdministratorGroups header that contains a comma-separated list of the groups the user is in. If this header isn't returned, the user is given read-only privileges.

The following PHP code provides an example script that can be used on a remote server to authenticate two users, an administrator named cricket and a read-only user named guest.

Note: For more information on writing HTTP digest authentication requests, see the IETF's HTTP Digest Access Configuration memo.

<?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;
}
?>

Add remote HTTP fallback authentication

With Wowza Streaming Engine 4.6.0.02 and later, you can configure remote HTTP authentication to use digest password file authentication under certain circumstances, such as a failure to connect to the remote service or the return of a specific HTTP status code that indicates the HTTP service isn't available.

By default, fallback authentication is disabled. You can enable it by using the following properties:

Property Description
<AuthenticationURLBackupFile> When true, instructs the remote HTTP authentication mechanism to use the digest password in the admin.password file when the specified <AuthenticationURLBackupFileConditions> are met.
<AuthenticationURLBackupFileConditions> A required, comma-separated list of conditions that determine when the fallback authentication method is used. 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 fallback mechanism.
<AuthenticationURLBackupFileRetry> The frequency, in milliseconds, at which the authentication system checks the remote HTTP service for availability. The default is 30000. The specified value can't be less than 10000. This property is only required if you want to use a frequency other than the default.

Important: To use fallback authentication, you must first create a digest password in the admin.password file. For instructions, see Use digest HTTP authentication.

Add the fallback properties to the authentication method between the <AuthenticationURL> and the <AuthenticationURLSharedSecret> in the Server.xml file, like this:

<AuthenticationURL>http://192.168.1.10/wseauthentication/</AuthenticationURL>
<AuthenticationURLBackupFile>true</AuthenticationURLBackupFile>
<AuthenticationURLBackupFileRetry>30000</AuthenticationURLBackupFileRetry>
<AuthenticationURLBackupFileConditions>connect,500</AuthenticationURLBackupFileConditions>
<AuthenticationURLSharedSecret>MySharedSecretKey</AuthenticationURLSharedSecret>
<AuthenticationURLIdentity>MyServerIDName</AuthenticationURLIdentity>

Disable authentication


You can turn off authentication so that API requests aren't authenticated.

  1. Navigate to [install-dir]/conf/ and open Server.xml in a text editor.
  2. Locate the <AuthenticationMethod> property in the <RESTInterface> section.
  3. Specify none, like this:
<AuthenticationMethod>none</AuthenticationMethod>
  1. Save your change.

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