This article shows a simple way to authenticate the players of your Wowza streams using Wrench module. Authentication means here to associate an identity with the clients, most typically a user name or login name. Knowing the identity of your player allows you to do further authorization checks (has the user the role / permisssion to watch my stream? has the user payed for the service? etc).

This Wowza user authentication tutorial assumes that you have already set up your Wowza application and you have some means to authenticate your users on your website before showing the stream. This can be easily achieved if you are using a CMS like Drupal.

Update: since this article was written, a new out-of-the-box example with detailed instruction video has been created. While you can still use this article as a reference, I suggest you to check out Streamtoolbox Examples on GitHub and watch the below YouTube video.

Install the Wrench module from the toolbox

The Wrench module is a single jar file that you can download from the toolbox. Copy the wrench-xxx.jar file under the lib directory of your Wowza installation (e.g. c:\wowza-x.x\lib) where you can find all the other jar files. Putting this file there will automatically include in on the classpath where Wowza Streaming Engine® can load the module if any application refers to it.

If you copied the jar file to the right place and added it to your Application.xml, you should see this line in your logs:

Starting Wrench 2015.03.26, licensed to ...
Using database url ..., user ....

If you did not put it to the right place, you should see this in the logs:

Module class not found or could not be loaded. Check [install-dir]/conf/live/Application.xml to be sure all Modules/Module/Class paths are correct: name:Wrench class:com.streamtoolbox.Wrench

Caution: you need to restart the OS level process of Wowza to get the jar file loaded. Using the "Restart" button on the web interface is unfortunately not enough.

Add required libraries

Wrench requires the JDBC driver of the database that you are using for storing tokens. Copy this jar file under the lib directory of your Wowza installation. In the FAQ section you can find a table with details for the most common databases.

Set up the table in your database to hold hashed tokens

You need to create a table a database which stores hashed tokens and associated user information. You can create this table in the database that your website uses, e.g. into your Drupal installation's database. The table has to be able to store the hashed token, the username and optionally the IP address of the user. Reason for storing hashed token is that it is a one time password actually, that is not nice to store in cleartext anywhere. An example for MySQL is below:

 CREATE TABLE wtb_tokens (
   ID int(12) NOT NULL AUTO_INCREMENT,
   USER varchar(128) NOT NULL COMMENT 'User name',
   TS timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
   IP varchar(64) NOT NULL,
   TOKEN varchar(128) NOT NULL COMMENT 'Hashed tokens',
   PRIMARY KEY (`ID`) 
)

Generate tokens

Whenever you want to show the stream link or your embedded player on your website, you have to first generate a random token. This acts as a one-time-password, so be careful to make it random in cryptographical sense. A simple example to generate this in PHP is as follows:

  <?php $token = uniqid(); ?>

Having generated the token, you have to store its hash in the above mentioned table together with the username that you should be able to determine from your web application's session information. An example in PHP that can be used in a typical Drupal 7.x node using the PHP filter is as follows:

$ip = $_SERVER['REMOTE_ADDR'];
global $user;

$conn = mysql_connect("localhost:3306/mydb", "user", "pass");
mysql_select_db("mydb", $conn);
mysql_query("INSERT INTO wtb_tokens (IP, TOKEN, USER) VALUES ('$ip', md5('$token'),'$user->name')");
mysql_close ($conn);

The above snippet is just to give you the idea of what needs to be done, you can write it more elegantly in your code. Be careful to store the hashed token in your database.

Pass tokens to player

The unhashed token is passed from the client to Wowza in the connection url. An example setup for the popular JW Player:

jwplayer("cc").setup({ 
   flashplayer: "/player.swf",
   file: 'rtmp://myserver:1935/mystreamingapp/?token=<?php echo $token; ?>/myStream',
   bufferlength: 5
});

(For JW Player 5, there was an other pattern, see FAQ for details)

Or you can put the tokens into your HTTP stream link for iOS and Android devices:

<a href="<?php echo 'http://myserver/mystreamingapp/streamName/playlist.m3u8?token='.$token; ?>">Watch video</a>

Let me emphasize again that the clear token has to be passed to the player. Wrench will do the hasing on its side using the configured wrench.token.hashing algorithm and substitute the hash into the token resolver query's :hashedtoken placeholder.

Configure Wrench in your Wowza application

In Wowza terminology, an "application" is a unit of configuration that can serve multiple streams. You create a new application by creating an empty folder with the desired application name under Wowza's application directory. Create the same named directory under conf and copy the default conf/Applicaton.xml there, or if you already have your application configured, then just add the following module definition under <Modules>

<Modules>
  ...
  <!-- Make sure Wrench is the last configured module -->
  <Module>
    <Name>Wrench</Name>
    <Description>Wrench provides user authentication to your application</Description>
    <Class>com.streamtoolbox.Wrench</Class>
  </Module>
</Modules>

The above snippet enables the module on your application. You also need to specify the settings for Wrench as follows:

<Properties>
  <Property><Name>wrench.db.driver</Name><Value>com.mysql.jdbc.Driver</Value></Property>
  <Property><Name>wrench.db.url</Name><Value>jdbc:mysql://localhost:3306/somedatabase</Value></Property>
  <Property><Name>wrench.db.user</Name><Value>john</Value></Property>
  <Property><Name>wrench.db.pass</Name><Value>secret</Value></Property>

  <Property><Name>wrench.dbcp.initial.size</Name><Value>1</Value></Property>
  <Property><Name>wrench.dbcp.max.size</Name><Value>10</Value></Property>
  <Property><Name>wrench.dbcp.test.on.borrow</Name><Value>true</Value></Property>
  <Property><Name>wrench.dbcp.test.sql</Name><Value>select 1 from wtb_tokens</Value></Property>


  <Property><Name>wrench.encoder.token</Name><Value>ncoder</Value></Property> 
  <Property><Name>wrench.token.url.parameter</Name><Value>token</Value></Property>
  <Property><Name>wrench.token.hashing</Name><Value>md5</Value></Property>
  <Property><Name>wrench.token.resolver.sql</Name><Value>select user as username,ip from wtb_tokens where token=:hashedtoken</Value></Property>
  <Property><Name>wrench.connect.authorization.sql</Name><Value>select 1 from wtb_permissions where user=:username and allow=1</Value>
</Property>

The meaning of each property above is more or less self describing. In this article I skip defining them, just let me emphasize the main points:

• When the client connects to Wowza, the token is parsed from the connection query string
• The clear token is hashed and Wrench tries to identify the connection by executing the wrench.token.resolver.sql
• The resoler query should return at least the username (and optionally IP and timestamp)
• At this point we know who's coming
• Wrench allows you to perform authorization checks with your custom wrench.connect.authorization.sql query. Based on the result set you can allow or reject the connection

The details and all the other features can be found in the reference documentation

Push your stream into your Wowza application

Download and install for example Flash Media Live Encoder from Adobe's website and set up your source as you like. When setting the FMS URL, point to your Wowza server and your application. Don't forget to add the token you have specified in the wrench.encoder.token property into the URL to bypass any authentication in Wowza. Of course you should use Wowza's other security settings besides this shared secret token to prevent others from pushing content into your application.

If you are using ffmpeg to produce your stream, the way to construct the URL with the token inside is as follows:

ffmpeg ... -f flv rtmp://localhost:1935/live?token=ncoder/mystream

That's it. Having set up all the above, you can see not only the client id's, but the usernames in Wowza log and you can hook stream authorization into your system.

The full reference of Wrench configuration can be found here

Some better examples are being developed on GitHub, check them out!

Please feel free to leave your feedbacks and questions about this tutorial. I'll keep this updated as newer versions of the Wrench module are released.