Overview

Akamai Technologies is a content delivery network that operates proxy servers around the world to accelerate web traffic and provide other value-added services. Akamai can also integrate with 3rd party services such as Arkose Labs. This document describes the workflow and implementation with Akamai.

The logic to verify the Arkose Labs token when handling a call to a protected endpoint would normally be handled by the web servers of Arkose Labs’ customers. When customers use Akamai to accelerate their traffic, the logic can be offloaded to the CDN. This not only helps streamline the integration of new customers or new endpoints but also shifts malicious traffic to the CDN layer, saving the customer’s web server bandwidth for legitimate traffic. When the Arkose Bot Manager is integrated with Akamai, the CDN layer will take care of the following steps:

Correctly handle the scenario if the arkosesessiontoken header is missing from the request to the protected endpoint.
Otherwise:
- Forward the request to Arkose Labs’ Verify API
- Process the response from the Arkose Labs API and decide whether to block the request (solved=false) or forward it to the origin web server (solved=true)

Workflow

Exchange workflow without Akamai

The client loads a page (for example login form) with an endpoint protected with Arkose Bot Manager (the login request). The page returned by the origin web server includes tags for the Arkose Labs JavaScript API
The client parses the content of the HTML page and loads the page assets including the Arkose Labs JavaScript. The relevant section of the page, for example, the login button, is instrumented to invoke the Arkose Client API to initiate the detection and enforcement process
The JavaScript runs on the client side. It collects various client characteristics, or a fingerprint, and sends it to the Arkose Labs server. The Arkose Labs server creates a session, evaluates the fingerprint, and if a threat is found a signal will be sent back to the client indicating that a challenge must be shown, otherwise the challenge will be suppressed. The challenge type and difficulty depend on the threat and pressure applied to the detection method or telltale.
During the challenge process, several messages are sent to the Arkose Labs server while the user interacts with the challenge. The user interactions are defined as events, such as game loaded or user clicked verify
The user triggers a request to the protected endpoint, by clicking Verify (user clicked verify event ). The Arkose Labs token is sent along with the request. The customer origin web server extracts the token and makes an API call to the Arkose Labs server to get a classification (human or bot). If the Arkose Labs API returns solved=false, the client-side code rejects/denies the request. The same action is taken when the token is missing from the request. Otherwise, if solved=true is returned, it proceeds with the request.

In this model, the Arkose Labs customer must make two changes to integrate with Arkose Bot Manager:

Add the necessary code to instrument the call to the protecting endpoint to invoke the Arkose client API.
Update their back-end logic to make an API call to Arkose labs to verify the token on the protected requests.

Exchange workflow between the client, Akamai, the origin web server and the Arkose verify API:

Exchange workflow with Akamai

The Akamai CDN layer offers plenty of flexibility and gives us the opportunity to offload some of the logic to the Akamai layer, which will help streamline the integration: In particular, we’ll be able to offload the logic to call the verify API on step 5 above to validate the Arkose session token to the Akamai CDN layer. The Akamai edge server will then be able to block sessions that fail to verify from reaching the origin web server, which offer an additional DDoS protection

Steps 1 to 4 of the exchange workflow with the CDN layer are the same as previously described. The main change is step 5 with regards to handling failed and successful verification. The workflow diagrams below show the altered behavior in the case of a failed and successful verifications.

Failed to verify

Following the detect and enforce process, the Arkose Labs server sends a token to the client. this will trigger a callback to the protected endpoint.
The Arkose Labs token is sent along with the request. The Akamai proxy server extracts the token and makes an API call to the Arkose Labs server to get the request classification (human or bot). If the Arkose Labs API returns solved=false, or if the token is missing, the CDN layer will reject/deny the request

Successful Verify

The user triggers a request to the protected endpoint by clicking the Verify button

The Arkose Labs token is sent along with the request. The Akamai proxy server extracts the token and makes an API call to the Arkose Labs server to get the request classification (human or bot). If the Arkose Labs API returns solved=true, the CDN layer will allow the request to proceed to the customer origin web server.

Integration steps

This integration consists of two parts:

Arkose Labs client-side JavaScript additions
The server-side Arkose Labs token verification check is configured using the Akamai Native XML language.

Client-Side Setup

In order to use the Arkose Bot Manager, some JavaScript additions need to be made to the page you want to protect, such as your Login or Registration page. Documentation for the client-side additions can be found in the Arkose Labs Akamai CDN Setup - Client Side integration guides.

Server-Side Setup

Please navigate to Akamai CDN Setup - Server Side Guide to view Documentation and information on how to setup Arkose Verify with an Akamai Property and Akamai EdgeWorkers.

For further assistance setting up the Arkose Labs verification process on Akamai, please contact your Arkose Labs or Akamai services representative.