Webservice Authentication / Authorization

This article shows how to set up Wrench to perform authorization on your stream players with an external arbitrary webservice. 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 Authentication / Authorization

The basic idea of Wrench is that you determine the idenity 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 webservice for authorization or authorization, Wrench offers you basically two ways to go, read on.

Using Wrench for authentication and webservice 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 webservice 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 -->
  <Value>select username from wtb_tokens where token=:hashedtoken</Value>

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", 

The webservice is expected to 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 will allow or deny on its own, based on the value of the wrench.connect.authorization.url.default.result property, which is deny by default.

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

Using Webservice for Authentication and Authorization

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

Update: Starting with version 2015.05.01. Wrench can also use webservice for token resolution, allowing your webservice to return the determined username and role (encoder or player) to Wrench. This allows you to have two separate webservices, 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 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 -->
  <Value></Value> <!-- Setting to nothing to go into no-database mode -->

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


Hello. I want use Wrench mode without db. Wowza version is 4.1.2. But it doesn't work. Here is log: - Starting Wrench 2015.03.26 - Verbose logging mode is on - No JDBC driver is specified, going to no-database mode. SQL dependent features won't work. - Expected token parameter is: token - invoke(onAppStart): java.lang.reflect.InvocationTargetException|at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)|at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)|at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)|at java.lang.reflect.Method.invoke(Method.java:606)|at com.wowza.wms.module.ModuleFunction.invoke(ModuleFunction.java:383)| I can't figure out what is wrong. Please help me. And then I get more errors like: - Error executing authorization: null: java.lang.NullPointerException - invoke(onConnect): java.lang.reflect.InvocationTargetException - invoke(play): java.lang.reflect.InvocationTargetException - invoke(publish): java.lang.reflect.InvocationTargetException - invoke(onDisconnect): java.lang.reflect.InvocationTargetException

Hi, can you send me your Application.xml via email?

Hi, is it possible to add the client IP to the request JSON? In my wrench Application.xml the only authentication is the webservice. I don't want wrench to connect to my MySQL database. So wrench cannot check the IP for me.

Hi Lars, I'll contact you via email, this can be added

hi i want to protect my stream for that pages are not placed in unauthorized Wowza use you think you can help?

I think I can, please contact me via email.

when ussing 'Webservice for Authentication and Authorization' it does post to my webservice url, but post is empty, not even a token What could be the problem?

Hi gerd, I am not sure, to help you I need to see your logs, can you email them to me?

i think your mail got between my spam somehow, can u please email me again, so i know where to send the logs to? thanks

Could u please email me once more, so i know where to send the logs to. sorry for the late responds

I am reachable at help@streamtoolbox.com let's take this offline

Write new comment