Integrate using Akamai EdgeWorkers

This guide describes how to use Akamai EdgeWorkers to integrate Detection and Response services into your web app. For more information about Akamai EdgeWorkers, see Akamai'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

Your web application must be integrated with Akamai and you should be able to create new Akamai EdgeWorkers.

Step 1: Get client credentials

Client credentials are used to identify your app and generate access tokens for authorizing Transmit 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 Transmit 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: Create new EdgeWorker ID

Start by setting up a new EdgeWorker that will execute the code that initializes Detection and Response SDK, collects events, and feed them to Transmit.

  1. Login to your Akamai dashboard and navigate to EdgeWorkers.
  2. Select Create EdgeWorker ID and provide details such as name (e.g., Transmit Detection and Response), group, and resource tier.

Step 3: Create and activate bundle

An EdgeWorker you've just created is still inactive and doesn't contain any code to execute. To enable the worker, create a new version for it, provide the code bundle, and then activate the version for your application environment. The bundle consists of bundle.json and main.js.

  1. Go to the EdgeWorker ID details and select Create version .
  2. Provide a version number and description in the bundle.json .
  3. Add the sample code below to the main.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.
  4. Select Activate version to enable the EdgeWorker.
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';

// Some headers aren't safe to forward from the origin response through an EdgeWorker on to the client
// For more information, see the tech docs on create-response: https://techdocs.akamai.com/edgeworkers/docs/create-response
const UNSAFE_RESPONSE_HEADERS = ['content-length', 'transfer-encoding', 'connection', 'vary',
  'accept-encoding', 'content-encoding', 'keep-alive',
  'proxy-authenticate', 'proxy-authorization', 'te', 'trailers', 'upgrade'];

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").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: 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]',
    },
  }
);