Token Checking Mechanism

The token that travels in the connection URL and subsequent HTTP queries acts as a one time password that is used by Wrench to identify the client making the request and make it’s access control decisions.

To protect the streaming services against various forms of abuse, Wrench can cross-verify the origin of the HTTP request against additional information associated with the token, that can be optionally retrieved via the so called token resolution mechanism. This mechanism can be as simple as running a predefined SQL query against your database or making a HTTP request against a webservice.

An overview of the authentication mechanism can be found here.

Possible checks that you can switch on are:

  • IP checking (with bypass list option)

  • Token expiration checking

  • Duplicate player checking (with configurable limit)

  • Http-Referer header black and whitelisting

  • User-Agent based black and whitelisting

  • Token purpose checking (distinguish player / publisher tokens)

IP checking

IP checking requires that your token resolver query (wrench.token.resolver.sql) or webservice response returns the IP address associated with the token. When the token is resolved and wrench.token.ip.check is set to true Wrench checks that the IP address originally associated with the token is the same (simple string comparison happens) as the IP address of the client connecting to Wowza. Wrench respects the HTTP header X-Forwarded-For or its equivalent, see wrench.ip.override.http.header application property for details.

This can help you to prevent users from transferring the URL with the token to an other computer.

Token Expiration Checking

You can associate a timestamp with tokens that can be optionally fetched by the token resolver query (wrench.token.resolver.sql) or returned by the response JSON object of your token resolver webservice. Wrench compares this timestamp with the system clock by the time the token is being resolved. If the difference is bigger than the configured wrench.token.expiry.sec value, then the token is not accepted. This prevents clients from eagerly generating and saving many tokens for later use.

Http-Referer and User-Agent Checking

Browsers and players might send a Http-Referer and User-Agent HTTP headers to Wowza Streaming Engine. Wrench can compare these to predefined patterns. Please note that these valuels should not be trusted, because many players and tools allow the user to fake these values. If the headers are missing, they are considered to be empty strings when the checks are performed.

See wrench.user.agent.blacklist, wrench.user.agent.whitelist, wrench.http.referrer.blacklist and wrench.http.referrer.whitelist application properties for more details.

Token Purpose Checking

wrench.publish.encoder.flag.check can be turned on combined with encoder/non-encoder information returned by the token resolver query or the webservice response to allow issueing tokens that can only be used for playback or publishing.