How does Wrench authentication and authorization work?

The purpose of this article is to give you an architectural overview on the security (authentication and authorization) mechanism that you can achive using Wrench module.

This diagram below shows the way Wrench associates identity to clients on Wowza side.

The most important thing here is the so-called token, which is practically a one-time random password that is generated on your webserver, after having successfully authenticated your website’s visitor using your custom authentication mechanism. Performing this authentication and generating and inserting the token into the database is completely under your responsibility. If you are familiar with web programming, then it should be a fairly straightforward thing to do.

In the database (which can be any JDBC-compliant RDBMS, as Wrench is completely db-agnostic) you have to store the generated token along with minimally the username and optionally you can store the IP address and the generation timestamp. You can use the IP and the timestamp to perform extra checks upon connection (see wrench.token.ip.check and wrench.token.expiry.sec in the reference docs for details)

The token is sent back to the client in the form of a video link, such as rtmp://mediaserver.com:1935/myapp/mystream?token=a7b54df68f. If you are using an embedded video player like JW Player or equivalent, you need to set up its video link accordingly.

The below diagram shows the possible checking mechanisms that you can enable.

First, Wrench parses the token from the connection url and fetches the associated username (and optionally IP address and timestamp) from the database using the wrench.token.resolver.sql query you configure. If the token is not present, the connection is still accepted if switchable public mode is enabled, and the current state is the public mode. (See wrench.switchable.public for details in the reference docs)

Each of the following checks is optional and can be switched on or off in the Application.xml configuration:

• IP checking: the stored IP address is compared to the IP address of the connecting client. This prevents users from sending the generated link to other people.
• External Web service Checking: Wrench can reach out to an existing web service by sending an HTTP POST with JSON body, containing the connection details (username, stream name, application, etc). The connection request is processed based on the web service response. See the reference docs for details.
• Token expiry check: you can define an expiration time for the generated tokens, and they won’t be accepted later. This prevents people from generating multiple links and pile up them for later usage
• Duplicate player checking: Wrench keeps a record of the users currently playing any stream and can prevent users with the same login to connect simultaneously. (See this article for details)
• Custom authentication query: you can define your custom SQL query that is executed against the database. Based on the query result row count you can reject or accept the connection
• User-Agent and Http-Referer blacklist or whitelist checking: Although relatively easy to spoof, Wrench gives you this additional level of control over the client software and origin domain you accept