Web Service Based Authentication / Authorization

This article shows how to set up Wrench to perform authorization on your stream players with an external arbitrary web service. If you are interested in all the possible checks that you can apply to your streams with this product, check out the How does Wrench work? page and the complete reference manual.

In this tutorial, we assume that you are familiar with the basics of installing Wrench. If not, then it’s worth reading the user authentication article, which guides you through the basic setup.

Web Service Based Authentication / Authorization

The basic idea of Wrench is that you determine the identity of your players by resolving a token that you assing to clients when they log in to your site / open your video page, etc. This token gets saved into your own database and when the player software connects back to your Wowza Streaming Engine®, Wrench reads back this token and uses the configured custom wrench.token.resolver.sql to find out who’s connecting.

To use a web service for authorization or authorization, Wrench offers you basically two ways to go, read on.

Using Wrench for authentication and web service for authorization

One way to go is that you use the token to username resolution mechanism, and let Wrench find out who is coming. In this case, Wrench does the authentication part, and your web service can do the authorization.

You need to define the following in your Application.xml (along with all the other necessary settings):

<!-- Example Application.xml part from the Properties element -->
<Property>
  <Name>wrench.token.resolver.sql</Name>
  <Value>select username from wtb_tokens where token=:hashedtoken</Value>
</Property>
<Property>
  <Name>wrench.connect.authorization.url</Name>
  <Value>http://streamtoolbox.com/streaming/auth-ok.php</Value>
  <!--Value>http://streamtoolbox.com/streaming/auth-nok.php</Value-->
</Property>

When the user connects to your stream, Wrench will execute the wrench.token.resolver.sql first, to determine the username. The Wrench will send a HTTP POST message to the above defined URL, as follows:

{
  "streamName": "mystream", 
  "userName":"john",
  "token":"54ddec75e2294", 
  "applicationName":"live", 
  "applicationInstance":"_definst_",
  "ip":"192.168.1.103"
}

The web service should respond with HTTP 200, sending back one of the below JSON messages:

{"result": "allow"}˙ or {"result": "deny"}

In case of any communication error, non-200 response, JSON parse error, Wrench allows or denies on its own, based on the value of the wrench.connect.authorization.url.default.result property, which is set to deny in error cases by default.

This allows you to integrate Wowza Streaming Engine® with any existing web service you have, and allow users to access your video streams in a controlled way.

Using Web service for Authentication and Authorization

The other way to go is that you simply use Wrench as a bridge between Wowza Streaming Engine® and your web service. Wrench does not need to attempt resolving the token, it will assume anonymous as username and pass the token to your web service just as described above. The stream access will be decided entirely based on the response from your web service.

Update: Starting with version 2015.05.01. Wrench can also use web service for token resolution, allowing your web service to return the determined username and role (encoder or player) to Wrench. This allows you to have two separate web services, one responsible for resolving a token, and a second one to decide about stream access. Having the usernames returned to Wrench will open up using the PPM (pay-per-minute) or the PPV (pay-per-view) features without a database, as well as all other lifecycle functions that require username to work properly. See wrench.token.resolver.url in the reference docs for more details

In this particular case, you don’t need any database under Wrench, so in your Application.xml, you must set the wrench.db.driver explicitly to empty string, because otherwise it defaults to MySQL database JDBC driver classname. You don’t need to specify wrench.token.resolver.sql at all.

<!-- Example Application.xml part from the Properties element -->
<Property>
  <Name>wrench.db.driver</Name>
  <Value></Value> <!-- Setting to nothing to go into no-database mode -->
</Property>
<Property>
  <Name>wrench.connect.authorization.url</Name>
  <Value>http://streamtoolbox.com/streaming/auth-ok.php</Value>
  <!--Value>http://streamtoolbox.com/streaming/auth-nok.php</Value-->
</Property>

The above-described feature allows a very flexible integration between Wowza Streaming Engine® and your streaming solution.