Fastly Deployment Guide

Overview

As a Fastly user, you can deploy HUMAN’s Application Integrity solution without modifying your front-end or back-end code.

We leverage Fastly's Compute@Edge technology to integrate our Application Integrity solution. For each request made to your site, one or both of the following actions are performed (according to the agreed-upon configuration): * HUMAN’s detection tag is injected into the HTML of the relevant page(s). * For each protected event submission, a request is sent synchronously from Fastly to the HUMAN Mitigation API. Based on the Fastly configuration and the HUMAN response, one of the following happens: (A) Your request HTTP headers are annotated with the details of the HUMAN response, or (B) the original client request is blocked with a preconfigured HTTP response.

Requirements

To get started, you will need:

  1. A Fastly account with access to the Rust Compute@Edge feature.
  2. A domain name server (NS) record configured to the appropriate Fastly nameserver, as specified in this Fastly Guide.
  3. An integration call with your HUMAN representative to provide details about the interaction(s) you would like to protect (sign-in, sign-up, web form, play/like, etc.) and the mode you would like to deploy (Passive Non-Interactive, Passive Interactive, Active). This information will be used to customize your Fastly Compute@Edge application code for maximum detection results.

Content Retrieval

A HUMAN representative will share the following 3 components with you by email:

  • Wasm package: the Edge application code (tar.gz file),
  • human_security_configuration dictionary: your JSON configuration,
  • your human_security_url to configure the human_security backend server

Deployment

To deploy the Fastly Compute@Edge integration, you’ll need to create a Rust Compute@Edge application, configure the dictionary, configure the origin servers, and activate the service. Optionally, you can also configure the log endpoint prior to activating the service.

Create a Rust Compute@Edge application

Your first step is to create a Fastly Compute@Edge application in Rust. This application will run HUMAN’s web assembly package for every client request received by your server. To create this application:

  1. Log in into your Fastly account.
  2. From the home page, open the Create service drop-down menu and select Wasm service.

Create a Wasm service

  1. Rename the service to something easily recognizable and accessible. Example: “human-contactform” instead of the auto-generated name “white-frog-9e98”.

Rename the service

  1. From the Package tab, select Browse for package to upload the tar.gz package you received from HUMAN.

Upload the HUMAN wasm package

You now have HUMAN’s code in your Edge application. Next, you will need to configure your Edge application with your unique client data.

If you are unable to edit your application because its status is “active” or “locked”, you can clone the latest version to produce a draft version. After you’ve applied your changes to the draft version, select Activate to send to production.

Configure the Dictionary

The Edge application loads its configuration from a Fastly Edge dictionary at runtime. To configure the application dictionary:

  1. Navigate to the Dictionaries tab of the service sidebar, then select Create a dictionary. Enter the name human_security_configuration, then select Add.

Create the dictionary Name the dictionary wo_configuration

  1. Add a single entry with the key “config” and the value of the JSON payload provided by your HUMAN representative. For example, your configuration may look something like this:
{
    "api_key": "",
    "customer_id": "845155",
    "human_security_url": "http://107.22.12.64:8081/",
    "site_id": "active-tyfxks",
    "tag_id": "8451551584148378445000",
    "tag_origin": "https://s.analytics.tyfxks.com",
    "authorization_headers": {
        "some-header-name": "some-header-value"
    },
    "backend_header_key": "X-BACKEND-SRV",
    "override_host_header_key": "X-OVERRIDE-HOST",
    "routes": [
        {
            "included_path_regex": "^/block$",
            "methods": [
                "GET"
            ],
            "event_type": "undefined",
            "action": {
                "type": "talk_to_human_security",
                "username_key": "/asdf",
                "body_fields_to_forward": [
                    {
                        "key": "/a",
                        "type": "raw"
                    },
                    {
                        "key": "/b",
                        "type": "hash"
                    },
                    {
                        "key": "/c",
                        "type": "is_empty"
                    }
                ],
                "oz_source": "headers",
                "oz_session_key": "header-to-store-TC",
                "oz_payload_key": "header-to-store-SG",
                "oz_datatoken_key": "header-to-store-DT",
                "ip_header_key": "Fastly-Client-IP",
                "policy_name": "Policy1",
                "block_with": {
                    "body": "blocked",
                    "status": 401,
                    "headers": {
                        "test": "whatever"
                    }
                }
            }
        },
        {
            "included_path_regex": "",
            "methods": [
                "GET"
            ],
            "event_type": "undefined",
            "action": {
                "type": "deploy_tag",
                "mode": "noninteractive"
            }
        }
    ]
}

The structure of the configuration is as follows:

  • human_security_url: The URL of HUMAN’s server. Only required when deploying in Active mode. This value must be consistent with the “human_security” value configured below in Origins.
  • customer_id: Your HUMAN customer ID.
  • api_key: Your HUMAN Mitigation API key.
  • site_id: The site ID provided by your HUMAN representative.
  • tag_id: The tag ID provided by your HUMAN representative
  • tag_origin: The tag origin (protocol, host, and port, e.g. “https://google.com”) provided by your HUMAN representative.
  • authorization_headers: (optional) The JSON object of header name / value pairs to attach to the incoming request.
  • backend_header_key: (optional) The header key to set the backend server (ex: to create stickyness).
  • override_host_header_key: (optional) The header key to set the Host header (useful for service chaining with VCL in front).
  • log_level: Must equal one of the following values. If not defined, it defaults to “ERROR”:
    • OFF
    • ERROR
    • WARN
    • INFO
    • DEBUG
    • TRACE
  • routes: An ordered array of routes. The first route to match the incoming request is used to proceed. If no routes match, the request passes through without any intervention. Each route contains the following subfields:
    • methods: (required) An array of HTTP methods. The incoming request’s method must match one of these to match the route.
    • included_path_regex: (optional) The request URL path must match this pattern to match the route. If absent, defaults to a pattern that matches all possible URL paths.
    • excluded_path_regex: (optional) The request URL path must NOT match this pattern to match the route. If absent, defaults to a pattern that does not match any possible URL path.
    • query: (optional) A JSON object of URL query parameters, mapping string keys to string values. These must be present in the incoming request query parameters to match the route.
    • event_type: (required) One of the following values:
      • undefined
      • account_login
      • account_creation
      • password_reset
      • password_update
      • profile_update
      • reputation_click
      • spin
      • transaction
      • generic_form_fill
      • generic_button_click
      • automatic
    • action: (required) A JSON object describing the mode. Must be one of the following. For the “active” case, the additional fields configure the interaction with the HUMAN Mitigation API.
      • {“type”: “deploy_tag”, "mode": "..."}. The Edge application will deploy the Human Security tag. “mode” must be one of the following.
        • noninteractive (mo=0)
        • interactive (mo=1)
        • active (mo=2)
      • {“type”: “talk_to_human_security”, ...}. The Edge application will make a request to the HUMAN Mitigation API. Additional fields described below can be configured.
        • username_key: (optional) Key in the incoming request body to be referenced as a username for Application Integrity. The key will be used to extract from a URL-encoded body, or from a JSON body as a JSON pointer (e.g. “/username”. Note the preceding “/”). The username will be SHA1-hashed before being forwarded to HUMAN.
        • body_fields_to_forward: (optional) Fields from the incoming request body, either URL-encoded or JSON-encoded, which will be forwarded to HUMAN. Examples:
          • {“type”: “raw”, “key”: “x”} Forward the url-encoded field “x” as-is.
          • {“type”: “hash”, “key”: “/some/key”} Forward the SHA1 hash of the JSON-encoded field “some.key” in the JSON payload.
          • {“type”: “is_empty”, “key”: “/some/key”} Forward a boolean value - true if the JSON-encoded field “some.key” is missing, otherwise false.
        • headers_to_forward: (optional) Headers from the incoming request which will be forwarded to HUMAN. Same format as body_fields_to_forward.
        • cookies_to_forward: (optional) Cookies from the incoming request which will be forwarded to HUMAN. Same format as body_fields_to_forward.
        • oz_source: (optional) A field to specify where to grab the OZ parameters from. Defaults to "body", accepts "headers".
        • oz_session_key: (optional) If oz_source is configured as "headers", specify the header name where to find the OZ_TC parameter.
        • oz_payload_key: (optional) If oz_source is configured as "headers", specify the header name where to find the OZ_SG parameter. Because of the OZ_SG size, the integration will append the sequence "_XX" where XX is a number (from 00 to 99) to the header name to concatenate together the various parts of the full parameter.
        • oz_datatoken_key: (optional) If oz_source is configured as "headers", specify the header name where to find the OZ_DT parameter. Because of the OZ_DT size, the integration will append the sequence "_XX" where XX is a number (from 00 to 99) to the header name to concatenate together the various parts of the full parameter.
        • ip_header_key: (optional) If configured, specify the header where to find the real IP address of the request. In Fastly this is usually correspondent to "Fastly-Client-IP".
        • policy_name: (optional) If configured, specify the name of the policy for the Policy Engine.
        • block_with: (optional) - If set and the HUMAN Mitigation API flags the incoming request as bot, the request will be blocked with a response configured by the following required fields:
          • body: A string to use as the body in the blocking response.
          • status: An integer to use as the HTTP status code in the blocking response.
          • headers: An object, associating HTTP header names / values to use in the response. E.g. {“content-type”: “text/html”, “location”: “https://google.com”}
          • debug_vesper_body (optional): If true, the Vesper response will be formatted at the end of the blocking response body for debugging purposes.

Configure the Origin Servers

The Edge application uses at least two origin servers: * your server, where all requests will be forwarded, * HUMAN’s server, which communicates with the Edge application to flag suspected fraudulent activity.

It is also posssible to configure multiple backend servers and use backend_header_key to redirect requests to the appropriate backend as needed.

To configure these servers:

  1. Navigate to the Origins tab in the service sidebar, then add your server’s hostname to the Hosts section. Note that hostnames should NOT include an HTTP protocol NOR URL path information, e.g. “google.com” is valid, but not “https://google.com” nor “google.com/some/search”.

Create the dictionary

  1. Select the pencil icon to edit the host.

Select the pencil icon

  1. [If you are using a single backend and no redirect based on a header] Edit the Name field of your origin server from its default value (e.g. “Host 1”) to “customer”. This name must be exact, as the wasm package looks for the origin with the hardcoded name “customer” when routing requests.

Change the name to customer

  1. Verify the TLS settings are correct. The defaults (enabled on port 443) will be correct for most use cases.

Verify the TLS settings are correct

  1. In the Advanced settings you can modify the Connection timeout parameter (default 1000ms). This is the maximum amount of time the request will be stalled in the HUMAN verification check. Detection will be skipped if the HUMAN Security Mitigation API takes longer than the timeout to respond.

  2. Select Update to save your changes.

Select Update to save your changes

  1. Repeat the previous steps (1 through 5) for the HUMAN decision server, by setting the hostname as the value of the “humansecurityurl” field (provided to you by your HUMAN representative) and by defining the name “human_security” instead of “customer”.

Configure the Log Endpoint (Optional)

You may wish to configure logging to help you diagnose errors and gain insight into the Edge application’s behavior. Fastly’s remote log streaming supports a variety of integrations (including Amazon S3, Apache Kafka, Elasticsearch, and FTP). For more information about remote log streaming, please consult this Fastly guide.

The HUMAN Compute@Edge wasm package writes logs to the endpoint log_endpoint. To configure this endpoint:

  1. Navigate to the Logging tab in the service sidebar and select your preferred endpoint from the available list.

Create the log endpoint

  1. Name this endpoint log_endpoint.

Confirm the desired log level has been properly configured in the “Dictionary” section, if not it will default to “ERROR”.

Activate the Service

  1. Select Activate in the upper right corner to deploy the service in production.

Activate the service

Integration Validation

Once you’ve configured and validated the Edge application, it is important to validate that the application is running properly and the protected event submission(s) loads as expected. To validate the application:

  1. Visit the webpage where the code was deployed. Make sure to navigate to the page using every possible method (e.g., direct URL, via button, referral link) and by leveraging the following browser states: a. Normal mode b. Private/Incognito mode c. Cleared browser local cache (to ensure the updated version of the website is retrieved) d. Multiple browser types (ex: Chrome, Safari, Firefox)
  2. Each time you visit this webpage, interact with your HUMAN protected event submission(s) (i.e click button, fill form, enter credentials, etc).
  3. Submit the browser request for your protected event(s). It/they should behave as usual. a. If an error message is displayed, please contact your HUMAN representative for support.
  4. Verify that your backend systems are receiving form submission data as expected. a. If you encounter any issues please contact your HUMAN representative for support.
  5. Check the real-time or historic stats in Fastly to ensure you are receiving successful events and requests.

View real-time statistics

  1. If you configured the Log Endpoint, check your log source for any errors.

Monitoring

Fastly offers a web interface and API for historical stats, which you can read more about here. You can access this data by navigating to Stats > Historic in your service.

View historic statistics