Integrate using Fastly Compute@Edge

This guide describes how to use Fastly Compute@Edge services to integrate Detection and Response services into your web app. For more information about Fastly Compute@Edge, see Fastly's documentation.

Note

This guide describes integrating using the new Platform SDK. If you've already integrated using the older Detection and Response SDK, you can find that guide here.

Prerequisites

Make sure you have completed the Fastly setup, including creating a Fastly account, installing Fastly CLI with the JS toolchain and dependencies, and generating an API token for running CLI.

Step 1: Get client credentials

Client credentials are used to identify your app and generate access tokens for authorizing Mosaic requests. To obtain them, you'll need to create an application in the Admin Portal (if you don’t have one yet).

  1. From Applications , click Add application .
  2. Add the friendly application name to display in the Admin Portal.
  3. Add a client display name, and your website URL as a redirect URI (e.g., https://your-domain.com ).
    Note

    These fields are required for all Mosaic apps, but won’t be used for Detection and Response.

  4. Click Add to create your application. This will automatically generate your client credentials.

Step 2: Configure project

Start by setting up a new Compute@Edge project for Detection and Response integration. If you already have an existing Compute@Edge JS-based project and want to use it, you can skip this step.

  1. With Fastly CLI, run the following command to initialize a project:
Copy
Copied
fastly compute init
  1. Provide details about your project including its name and description, and choose a language (JavaScript).

Step 3: Customize JavaScript

In your local development environment, locate src/index.js—it contains the logic for handling requests. To enable integration with Mosaic, add the code that initializes Detection and Response SDK, collects events, and feeds them to Mosaic.

Add the sample code below to the index.js file. You'll need to replace [CLIENT_ID] with the ID you've acquired in Step 1 and [ORIGIN_SERVER] with your application domain in order to be able to get a response from your app. To set the user for all subsequent events in the browser session, replace the [USER_ID] with the actual user ID. To improve detection and response, pass the correlation ID when triggering an action (optional).

Notes
  • The sample below is used to obtain recommendations for login actions, but you can adjust the script to report other sensitive actions. For the complete list of action types, see our recommendations page.
  • Make sure to pass the received actionToken to your backend along with the actual action invocation to ensure you can leverage the recommendation in the next step.
Copy
Copied
import { ReadableStream, WritableStream } from 'streams';
import { httpRequest } from 'http-request';
import { createResponse } from 'create-response';
import { TextEncoderStream, TextDecoderStream } from 'text-encode-transform';

class HTMLStream {
  constructor () {
    let readController = null;
    const drsLoginHandlerStr = `
          // Loads the latest SDK within the major version 1
          // See changelog for details and update version if necessary
          <script src="https://platform-websdk.transmitsecurity.io/platform-websdk/1.x/ts-platform-websdk.js" defer="true" id="ts-platform-script"></script>
          <script>
           console.log("Setting up event listener for script loading");
             // Initialize the Platform SDK
             document.getElementById("ts-platform-script").addEventListener("load", function() {
                 window.tsPlatform.initialize({
                    clientId: "[CLIENT_ID]",
                    drs: { userId: "[USER_ID]" }, // If user ID exists
                 });
             });

            // Trigger the specific actions per page:
            const url = window.location.href;
            if (url.includes("/login")) { // login page
              // Trigger events for the login button and get the actionToken
              document.getElementById("login_button").addEventListener('click', function(e) {
                window.tsPlatform.drs.triggerActionEvent("login", { correlationId: "[CORRELATION_ID]" }).then((actionResponse) => {
                  let actionToken = actionResponse.actionToken;
                  // Add code here to send the received actionToken to your backend
                });
              });
            } else {
              // Clear the set user after the user logs out or the user session expires
              async function onUserLogout(event) {
                window.tsPlatform.drs.clearUser();
              }
              let logoutButton = document.getElementById("logout");
              if (logoutButton) {
                logoutButton.addEventListener('click', onUserLogout);
              }
            }
          </script>
          </head>
    `;
    const headTag = '</head>';
    this.readable = new ReadableStream({
      start (controller) {
        readController = controller;
      }
    });

    // This function injects the code into the page
    async function handleTemplate (text) {
      const startIndex = text.indexOf(headTag);
      if (startIndex != -1 ) {
        text = text.replace(headTag, drsLoginHandlerStr);
      }
      readController.enqueue(text);
    }
    let completeProcessing = Promise.resolve();
    this.writable = new WritableStream({
      write (text) {
        completeProcessing = handleTemplate(text, 0);
      },
      close (controller) {
        completeProcessing.then(() => readController.close());
      }
    });
  }
}

export function responseProvider (request) {
    // Get the actual response from the origin server
    return httpRequest("[ORIGIN_SERVER]").then(response => {
      return createResponse(
        response.status,
        getSafeResponseHeaders(response.getHeaders()),
        response.body.pipeThrough(new TextDecoderStream()).pipeThrough(new HTMLStream()).pipeThrough(new TextEncoderStream())
      );
    });
}

function getSafeResponseHeaders(headers) {
    for (let unsafeResponseHeader of UNSAFE_RESPONSE_HEADERS) {
      if (unsafeResponseHeader in headers) {
        delete headers[unsafeResponseHeader]
      }
    }
    return headers;
}

Step 4: Build and deploy project

Prepare your Compute@Edge project for running on Fastly. To do it, compile it into a WebAssembly module and publish it.

  1. Compile the package by running the following command:
Copy
Copied
fastly compute build
  1. Deploy the Compute@Edge package to Fastly by running the following command:
Copy
Copied
fastly compute deploy

Step 5: Fetch recommendation

You can fetch recommendations for the reported action using the Recommendation API.

These APIs are authorized using an OAuth access token so you'll need to fetch a token using your client credentials (from step 1). The token should target the following resource: https://risk.identity.security. To do this, send the following request:

Copy
Copied
  const { access_token } = await fetch(
    `https://api.transmitsecurity.io/oidc/token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      }
      body: new URLSearchParams({
        grant_type: client_credentials,
        client_id: [CLIENT_ID],
        client_secret: [CLIENT_SECRET],
        resource: 'https://risk.identity.security'
      })
    }
  );

From your backend, invoke the Recommendation API by sending a request like the one below. The [ACCESS_TOKEN] is the authorization token you obtained using your client credentials and [ACTION_TOKEN] is the actionToken received from the SDK in step 3.

Copy
Copied
const query = new URLSearchParams({
  action_token: '[ACTION_TOKEN]',
}).toString();

const resp = await fetch(
  `https://api.transmitsecurity.io/risk/v1/recommendation?${query}`,
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer [ACCESS_TOKEN]',
    },
  }
);