Authentication

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

The WSE 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 WSE admin credentials before processing the request. You can update the authentication method to suit your needs.

About API authentication

WSE 4.8.8.01+ allows passwords in the admin.password file to be encoded using digest or Bcrypt hash functions. WSE 4.8.19+ supports 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 table below lists the available authentication methods and the password encoding method that each supports:

Basic authentication

The default authentication method is basic.

Basic HTTP authentication applies Base64 encoding to the administrator's username and password as they're transmitted in the HTTP request. 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.

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.

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.

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 CLI tool to manage users.

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.

6. 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 is secret, generate the hash from:

   solomio:Wowza:secret

   which results in the hashed digest password:

   43c27fa10ce3ea64d60735c79e9f1c4f

7. Locate the <PasswordEncodingScheme> property.

8. Specify either md5 or sha256, like this:

   <PasswordEncodingScheme>sha256</PasswordEncodingScheme>

9. Save your change.

10. Finally, add the hashed digest password to the admin.password file. Navigate to [install-dir]/conf/ and open admin.password in a text editor.

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

12. Save your changes.

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>

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.

$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 WSE 4.6.0.02+, 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:

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.

2. Locate the <AuthenticationMethod> property in the <RESTInterface> element.

3. Set the <AuthenticationMethod> to none:

   <RESTInterface>
     <AuthenticationMethod>none</AuthenticationMethod>
   </RESTInterface>

4. Save your change.