User Authentication for Wowza Streaming Engine®
Related articles
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.
Comments
Erion Cuni
Mon, 04/21/2014 - 10:20
Hello,
streamtoolbox
Tue, 04/22/2014 - 21:29
Hi Erion! Having analyzed the
Ricardo
Wed, 04/23/2014 - 19:15
Hi! This plugin is great but
streamtoolbox
Wed, 04/23/2014 - 20:34
Hi Ricardo! You are right,
Ricardo
Thu, 04/24/2014 - 01:49
All fixed with the new
Adam
Thu, 06/05/2014 - 21:34
What are the chances that if
Glenn
Wed, 06/11/2014 - 14:26
So, I am assuming that for
Glenn
Wed, 06/11/2014 - 14:30
What happens when a user in
streamtoolbox
Wed, 06/11/2014 - 15:01
Hi Glenn, yes, check
Dan
Tue, 06/24/2014 - 14:21
Hi! Great plugin! I have a
streamtoolbox
Tue, 06/24/2014 - 14:32
Hi Dan! Thanks for pointing
Guy
Sun, 10/26/2014 - 22:37
Hello,
anguemo2000x@gm...
Thu, 10/30/2014 - 10:07
hi dear developer
voip
Mon, 11/03/2014 - 23:54
Great module !
streamtoolbox
Tue, 11/04/2014 - 07:21
Hi voip! The setup is pretty
streamtoolbox
Tue, 11/04/2014 - 07:20
In Guy's case the issue was
Voip
Tue, 11/04/2014 - 20:00
We have tested on Windows
voip
Tue, 11/04/2014 - 21:55
wowzatoolbox, actually i
streamtoolbox
Tue, 11/04/2014 - 21:57
That's good news, thanks for
voip
Tue, 11/04/2014 - 22:29
:)
streamtoolbox
Wed, 11/05/2014 - 17:09
Good question, I admit that
Aram T
Wed, 11/05/2014 - 22:38
I have developed and
kodo
Mon, 01/19/2015 - 22:14
I'm testing the plugin and it
streamtoolbox
Tue, 01/20/2015 - 05:51
Hi kodo, thanks for the
WoozAn0o0obie
Sun, 02/01/2015 - 14:51
Hey, I'm trying to configure
streamtoolbox
Sun, 02/01/2015 - 15:22
Hi, can you send me over your
Simo
Mon, 06/01/2015 - 22:19
Its working with Wowza Media
nikk
Thu, 07/02/2015 - 15:04
I am struggling to understand
Glenn Olsen
Sat, 07/11/2015 - 06:14
Before I give Wrench a try,
streamtoolbox
Sat, 07/11/2015 - 07:03
Hi Glenn, yes, videojs also
Amin Eshtiaghi
Thu, 08/06/2015 - 14:04
Hello, you note that Wrench
streamtoolbox
Thu, 08/06/2015 - 14:29
It's 25 concurrent users.
jason
Tue, 10/27/2015 - 14:15
Hello ,
streamtoolbox
Tue, 10/27/2015 - 20:18
Hi Jason, I have replied to
xlxuxt
Fri, 01/22/2016 - 12:11
Hi, I'm getting "Refusing
streamtoolbox
Fri, 01/22/2016 - 12:14
Hold on, let me check the
Vineet
Fri, 02/12/2016 - 11:46
Hi there,