• How to control access to your application by checking referer domain (RefererValidate)

    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 is designed for players that aren't RTMP-based, and uses an image tag or JavaScript that is added to the player webpage to validate the requester.

    Notes:
    • The misspelling of "referer" is intentional. For more information, see Origin of the term "referer."

    • RefererValidate is an alternative to the ModuleHotlinkDenial module, which was designed for use with RTMP-based Flash players. Use the RefererValidate module to control access to content on players that aren't RTMP-based.

    Contents


    Prerequisites
    Installation
    Configuration
    Properties
    Usage
    For developers

    Prerequisites


    Wowza Streaming Engine 4.0.3 or later is required.

    The Wowza™ Module Collection build 12557 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.collection.http.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 vod/sample.mp4 or live/_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


    Source code is available on GitHub.

    Wowza Media Systems™ provides developers with a platform to create streaming applications and solutions. See Wowza Developer Tools to learn more about our APIs and SDK.

    Wowza media server software and all components, including modules, source code, and other related items offered on this page, are copyrighted (c) 2006-2016 by Wowza Media Systems, LLC, all rights reserved, and are licensed pursuant to the Wowza Media Software End User License Agreement.

    Originally Published: 06-19-2014.
    Updated: 09-28-2016

    If you're having problems or want to discuss this article, post in our forum.