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
- Download wse-plugin-referervalidate.zip.
- 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).
- Restart Wowza Streaming Engine.
Configuration
To enable the RefererValidate module, do the following:
- Add the following module definition to you application. See Configure modules.
NameDescriptionFully Qualified Class NameRefererValidate Validate player connections. com.wowza.wms.plugin.RefererValidate - 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.
- Add the following HTTP Provider definition to the <HTTPProviders> section:
BaseClassRequestFilterAuthenticationMethodcom.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.
- 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.
- 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) |
- ${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
