• How to validate Akamai server connections with Akamai G2O authorization (AkamaiValidate)

    Akamai servers use special HTTP headers when they request HTTP-based streams from HTTP Origin applications in Wowza Streaming Engine™ media server software. The Akamai servers use these headers to validate the connection and to identify the connection as coming from an Akamai server. If the connection is valid, then it can be accepted. If the connection is invalid or rejected, then an appropriate HTTP response code is returned.

    Contents


    Prerequisites
    Installation
    Configuration
    Properties
    For developers
    More resources

    Prerequisites

    Wowza Streaming Engine 4.0.0 or later is required to use the AkamaiValidate VHost Listener.

    The Akamai features are described in detail in the "Auth: Edge to Origin" in the Akamai Edge Server Configuration Guide. This article provides links to different topics in the Akamai Edge Server Configuration Guide. You must sign-in to your Akamai account to access the guide through these links or to download it from Akamai.

    Installation


    1. Download wse-plugin-akamaivalidate.zip.

    2. Extract the contents from the downloaded (zipped) package, and then copy the lib/wse-plugin-akamaivalidate.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 VHostListenerAkamaiValidate VHost Listener, do the following:

    1. Open the Wowza Streaming Engine Server.xml configuration file [install-dir]/conf/Server.xml in a text editor, and then add the following VHost Listener:
      <VHostListener>
      	<BaseClass>com.wowza.wms.plugin.akamaivalidate.VHostListenerAkamaiValidate</BaseClass>
      </VHostListener>
    2. Save and close the Server.xml file.

    3. Next, open the Wowza Streaming Engine VHost.xml configuration file ([install-dir]/conf/VHost.xml) in a text editor and replace the default HTTP Provider with one that returns a custom response code:

      1. In VHost.xml, navigate to the default streaming hostport section (<HostPortList>/<HostPort>/<Name>Default Streaming</Name>).

      2. In this section of the XML file, in the list of HTTP Providers (<HTTPProviders>...</HTTPProviders>, locate the following HTTP Provider configuration section:
        <HTTPProvider>
        	<BaseClass>com.wowza.wms.http.HTTPServerVersion</BaseClass>
        	<RequestFilters>*</RequestFilters>
        	<AuthenticationMethod>none</AuthenticationMethod>
        </HTTPProvider>
      3. Replace this HTTP Provider with the following:
        <HTTPProvider>
        	<BaseClass>com.wowza.wms.plugin.akamaivalidate.HttpCustomResponseCode</BaseClass>
        	<RequestFilters>*</RequestFilters>
        	<AuthenticationMethod>none</AuthenticationMethod>
        	<Properties>
        		<Property>
        			<Name>responseCode</Name>
        			<Value>403</Value>
        		</Property>
        	</Properties>
        </HTTPProvider>
        This HTTP Provider will cause Wowza Streaming Engine to return an "Authorization failed" response (HTTP 403 status code) to any requests that fail to validate.

    4. Save and close the VHost.xml file, and then restart Wowza Streaming Engine.

    Note: VHost Listeners and HTTP Providers can't be configured in Wowza Streaming Engine Manager, so you must edit the configuration XML files manually.

    Properties


    After enabling the VHost Listener, you can adjust the default settings by adding the following VHost properties to your server. (This can be done in Wowza Streaming Engine Manager.) See Configure properties for details.
    Path
    Name
    Type
    Value
    Notes
    /Root/VHost akamaiValidatorDebugLog Boolean true Enables extra debug logging, which provides detailed logging for every step that's executed. This can help to determine the cause of any issues but it should be turned off on media servers in production environments. (default: false)
    /Root/VHost akamaiValidatorPathPattern String /live.* This property can be used to control which URLs get validated. It accepts a regex pattern to which you can match request paths. Any valid regex pattern should work. This property also accepts the wildcard character (*) as a value to match any path. If the property isn't set, then all paths are validated. The path being checked will start with a forward-slash / character. (default: not set)
    /Root/VHost akamaiValidatorValidateMatchingPaths Boolean true This property controls how the pattern match is used. If set to true, only matching paths are validated. If set to false, only non-matching paths are validated. (default: true)
    /Root/VHost akamaiValidatorAuthType String via Specifies the type of validation to perform. See pages 169 - 173 in the Akamai Edge Server Configuration Guide for configuration on the Akamai side and Validation type details below. Can be set to any of the following values:
    • via (default) - Performs validation on the Via header.
    • userAgent - Performs validation on the User-Agent header.
    • cookie - Performs validation on a specified cookie.
    • signature - Performs validation by using special Akamai headers.

    Note: SSL Client Certificate Authentication isn't implemented.
    /Root/VHost akamaiValidatorCheckViaHeader Boolean true Performs a Via header check before all other validation types. (default: true)

    Validation type details

    Via header check


    The default check is the Via header check. All proxy requests coming from Akamai servers should have the Via header set. It's a basic check that can be used to confirm that the connection is most likely coming from an Akamai server.

    User Agent header check


    The User Agent header check can be used to check the User Agent value that's being sent from the Akamai server. This feature must be configured in your Akamai account and the value should always be Akamai Edge.

    Cookie check


    The following property is used to configure the cookie used for the Cookie check.
    Path
    Name
    Type
    Value
    Notes
    /Root/VHost akamaiValidatorAuthCookie String mycookie=myvalue Must match the Akamai-ID Cookie value set in your Akamai configuration. (default: not set)

    Signature header check


    The following properties are used to configure the Signature header check.
    Path
    Name
    Type
    Value
    Notes
    /Root/VHost akamaiValidatorAuthDataHeader String X-Akamai-G2O-Auth-Data Auth Data header name to use. Only needs to be set if a different value is used. (default: X-Akamai-G2O-Auth-Data)
    /Root/VHost akamaiValidatorAuthSignHeader String X-Akamai-G2O-Auth-Sign Auth Sign header name to use. Only needs to be set if a different value is used. (default: X-Akamai-G2O-Auth-Sign)
    /Root/VHost akamaiValidatorAuthSecret String secret Default secret key to use. This is used if a matching nonce isn't found in the akamaiValidatorAuthNonceSecrets property. (default: not set)
    /Root/VHost akamaiValidatorAuthNonceSecrets String nonce1,secret1|nonce2, secret2 Separate the nonce and secret pair values with commas. Use the pipe (|) character to separate nonce,secret pairs. This allows multiple secrets to be used when transitioning between old and new values. This list is checked before the single akamaiValidatorAuthSecret value above. (default: not set)

    If an akamaiValidatorAuthSecret or akamaiValidatorAuthNonceSecrets secret isn't found (or both lists are empty), then signature auth fails immediately.

    The signature authentication version is determined by the data header. All three Akamai versions are implemented. For more information about authentication versions, see "Signature Header Authentication" in the Akamai Edge Server Configuration Guide.

    A request is valid for 30 seconds and all requests are cached for 60 seconds. This ensures that a second request isn't made with the same values. Wowza Streaming Engine checks to see if the time in the data header is within 30 seconds of the server time. The clock on the server should be set by using Network Time Protocol (NTP) to eliminate any timing issues.

    When a request path is invalid, Wowza Streaming Engine's default response is to pass the request to the default HTTP Provider to see if the path can be matched there. The default HTTP Provider would then return a 200 response. The configuration described in this article replaces the default HTTP Provider with a custom one that returns a 403 response.

    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.

    More resources

    How to set a default custom HTTP response code (HttpCustomResponseCode)
    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: For Wowza Streaming Engine on 01-06-2015.
    Updated: 04-14-2016.

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