Control access to your application by checking referer domain with a Wowza Streaming Engine Java module

The ModuleRefererValidate module for Wowza Streaming Engine™ media server software can be used to control access to your streams based on the referer domain. It uses an image tag or JavaScript that is added to the player webpage to validate the requester.

Note: The spelling of referer is intentional. For information, see Origin of the term "referer."

Contents


Prerequisites
Installation
Configuration
Properties
Usage
For developers

Prerequisites


Wowza Streaming Engine 4.0.3 or later is required.

Installation


  1. Download wse-plugin-referervalidate.zip.
     
  2. Extract the contents from the downloaded (zipped) package, and then copy the lib/wse-plugin-referervalidate.jar file from the package to the lib folder in your Wowza Streaming Engine installation ([install-dir]/lib).
     
  3. Restart Wowza Streaming Engine.

Configuration


To enable the RefererValidate module, do the following:

  1. Add the following module definition to you application. See Configure modules.
     
    Name
    Description
    Fully Qualified Class Name
    RefererValidate Validate player connections. com.wowza.wms.plugin.RefererValidate
  2. Next, open the [install-dir]/conf/VHost.xml configuration file in a text editor and navigate to the <HostPortList>/<HostPort>/<Name>Default Streaming</Name> section.
     
  3. Add the following HTTP Provider definition to the <HTTPProviders> section:
     
    BaseClass
    RequestFilter
    AuthenticationMethod
    com.wowza.wms.plugin.HttpRefererValidate *image.gif none
     
    Notes:
    • The new HTTP provider must be above the last HTTP provider that's used to resolve all requests that aren't handled by other providers.
       
    • The RequestFilter lists the last part of the URL that's checked to see if the HTTP provider can handle the request. It isn't the name of a custom image. To make it harder for someone to detect that this is a referer check, you can change the RequestFilter to your own value, but note that stream extension names that are currently used elsewhere in the server won't work.
  4. Save and close the VHost.xml file, and then restart Wowza Streaming Engine.

Properties


After enabling the module, you can adjust the default settings by adding the following properties to your application. See Configure properties for details.

Path
Name
Type
Value
Notes
/Root/Application refererValidateDebugLog Boolean false If set to true, extra debug logging enabled for the module. For the HTTP provider debug logging, refer to the VHost properties below. (default: false)
/Root/Application refererValidateReferers String *example.com,*mydomain.com A list of referer domains that are allowed. All other domains are rejected. You can use a complete IP address or domain name or prefix a partial domain name with a wildcard (*) character. (default: localhost, 127.0.0.1)
/Root/Application refererValidateAllowBlankReferers Boolean false If set to true, requests with no referer set are allowed. (default: false)
/Root/Application refererValidateSessionValidDuration Integer 60000 Duration (in milliseconds) during which a session is valid. This is the maximum time between when the player loads and when the stream is started. (default: 60000)
/Root/Application refererValidateReturn404OnNotValidated Boolean true If set to true, returns a 404 HTTP status code instead of an image if the session isn't valid. If set to false, returns the image specified by the refererValidateImagePath property. (default: true)
/Root/Application refererValidateImagePath String myimage.png Custom path to image that's returned. See note below. (default: Not Set)
 
Note: If set, the refererValidateImagePath should point to absolute path names on the server for images. If an image can't be found, then the default image is returned. The following variables can be used in the image path to return different images for each stream or for invalid requests:
  • ${com.wowza.wms.context.VHost}
  • ${com.wowza.wms.context.VHostConfigHome}
  • ${com.wowza.wms.context.Application}
  • ${com.wowza.wms.context.ApplicationInstance}
  • ${com.wowza.wms.context.Stream}
  • ${VHost.Name}
  • ${Application.Name}
  • ${ApplicationInstance.Name}
  • ${Stream.Name}
  • ${Valid} - will resolve to true or false, depending on whether the request is valid.

When publishing, the encoder won't be able to pass the referer check, so the module uses the Flash Version String setting in Playback Security in Wowza Streaming Engine Manager.

The HTTP provider can be configured by using the following VHost-level properties.

Path
Name
Type
Value
Notes
/Root/VHost httpRefererValidateSessionCheckInterval Integer 60000 Specifies (in milliseconds) how often the list of current sessions is checked and how often expired sessions are removed. (default: 60000)
/Root/VHost httpRefererValidateDebugLog Boolean false If set to true, enables extra debug logging for the HTTP provider. (default: false)

Usage


Adding an image tag or JavaScript to the embedded player webpage with a specified image path that points towards your Wowza server allows Wowza to validate the requestor and then enable the stream for playback. If the player is configured to start automatically or the page may take longer to load, the image tag should be positioned on the page before the embedded player. For example, you can add the following to the webpage:

<image src="http://[wowza-ip-address]:1935/[stream-path]/image.gif" />

Where the [stream-path] is the stream path in the player (such as [application-name]/sample.mp4 or [application-name]/_definst_/myStream), and the image.gif is the Requestfilter defined in the Default Streaming Hostport section of the [install-dir]/conf/VHost.xml configuration file. See Configuration, above, for more information.

When an HTTP request is sent to a Wowza Streaming Engine media server by an image tag or JavaScript on the player webpage,the RefererValidate module validates it based on the domain from which the request originated. After the requester is validated, the session information is stored and an image is returned; the image can be the default 1x1-pixel transparent GIF or a different image configured for each stream. If the request isn't validated, you can return the default 404 error code or a different HTTP error code that you've configured.

For developers


  • Get the source code on GitHub