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.

Notes:

• When SSL is enabled for the Wowza Streaming Engine REST API, you may see warnings in the logs indicating that you can't reach the REST API. This is a known issue with the logs and isn't actually a problem with the REST API. For more information, see Erroneous log statements when accessing the Wowza Streaming Engine REST API over SSL.
• To configure the authentication method for HTTP providers, see HTTP provider configuration.

About API authentication

Wowza Streaming Engine 4.8.8.01 and later allows passwords in the admin.password file to be encoded using digest or Bcrypt hash functions. In 4.8.19, Wowza Streaming Engine introduced support for sha256 encryption. The API authentication method must be compatible with the password encoding method. For more information, see Manage users with the Wowza Streaming Engine CLI password tool.

The following table lists the available authentication methods and the password encoding method that each supports:

Note: Due to potential vulnerabilities with md5, we recommend using sha256 with Wowza Streaming Engine.

Use basic HTTP authentication

The default authentication method is basic.

Note: With Wowza Streaming Engine 4.8.5.05 and earlier the default is digest and if you set the <AuthenticationMethod> to basic, you're also disabling authentication for Wowza Streaming Manager and removing the ability to manage and configure the media server software using Wowza Streaming Engine Manager.

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).

Since it's the default, you don’t have to do anything to enable basic 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 basic, like this:

   <AuthenticationMethod>basic</AuthenticationMethod>

   
   
4. Save your change.

Use digest authentication

Digest authentication uses an md5 or sha256 hashed password when communicating requests to the API's web server. An md5 or sha256 hash encodes (digests) a password string into 128 or 256 bits. You will need to set the AuthenticationMethod and PasswordEncodingScheme properties in the Server.xml file (located in [install-dir]/conf). Alternately, you can use the Command Line Interface tool to manage users. Refer to the CLI Tool documentation for more details.

Note: Due to potential vulnerabilities with MD5, we recommend using sha256 with Wowza Streaming Engine. Be aware that currently only Firefox supports sha256. You will only be able to access the REST API via Firefox, but Wowza Streaming Engine Manager is supported by most up-to-date browsers. 

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>

   
   
4. Locate the <PasswordEncodingScheme> property.
   
   
5. Specify either md5 or sha256, like this:

   <PasswordEncodingScheme>sha256</PasswordEncodingScheme>

   
   
6. Save your change.

Use digest HTTP authentication

To use digest HTTP authentication, first specify digest file as your authentication method and then create the hashed password. Alternately, you can use the Command Line Interface tool to manage users. Refer to the CLI Tool documentation for more details.

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>

4. Save your change.
5. Now, generate an MD5 or SHA256-hashed digest password using a website such as md5hashgenerator.com or https://emn178.github.io/online-tools/sha256.html.

5. Generate a hash from the string

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

For example using the md5 authentication method, 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

6. Locate the <PasswordEncodingScheme> property.
7. Specify either md5 or sha256, like this:
   

   <PasswordEncodingScheme>sha256</PasswordEncodingScheme>

8. Save your change.
9. Finally, add the hashed digest password to the admin.password file. Navigate to [install-dir]/conf/ and open admin.password in a text editor.
10. 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
11. Save your changes.

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

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>

4. 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.

5. 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:

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.

Note: If you set the <AuthenticationMethod> to none, you're also disabling authentication for Wowza Streaming Manager and removing the ability to manage and configure the media server software using 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 none, like this:

   <AuthenticationMethod>none</AuthenticationMethod>

4. Save your change.