Akamai EdgeWorkers

Overview

This guide walks through deploying Centinel Analytica server-side validation on Akamai using EdgeWorkers. Property Manager changes take 15-30 minutes to propagate across the Akamai network.

Have an existing EdgeWorker?

If your property already runs an EdgeWorker on the requests you want to protect, follow Run alongside an existing EdgeWorker instead of attaching a second one.

Prerequisites

Centinel secret key
Akamai Control Center access, with the EdgeWorkers add-on enabled
Property Manager read-write access for the property you want to protect
The Advanced Metadata privilege (open a support ticket if your account lacks it)

Install

Download the package

Download centinel-akamai-edgeworker.tgz.
Extract the archive to get main.js and bundle.json.

Create the EdgeWorker

Log into Akamai Control Center.
Go to CDN → EdgeWorkers.
Click Create EdgeWorker ID.
Enter a name (e.g. centinel-protection).
Select your Group, and choose Dynamic Compute (Tier 200) as the resource tier.
Click Create EdgeWorker ID.

Upload and activate the code

Select the EdgeWorker you just created.
Click Create Version.
Upload the main.js and bundle.json files.
Click Create Version.
Activate the new version on the staging and production networks.

Configure

Rule order

Keep the Centinel rules at the bottom of your rule tree. When two rules set the same behavior, the bottom-most match wins, so a later origin or caching rule would override them.

Configure the validator route

Route /centinel-validate to the Centinel API.

Go to CDN → Properties and select your property.
Click Edit New Version to create a draft.
Under Property Configuration, click Add Rule.
Name the rule Centinel Validator.
Add a Criteria:
- Match Type: Path
- Match Operator: matches one of
- Value: /centinel-validate
Add a Behavior → Origin Server:
- Origin Server Hostname: validator.centinelanalytica.com
- Forward Host Header: Origin Hostname
- Origin SSL Certificate Verification: Yes
Add a Behavior → Allow POST:
- Behavior: Allow
- Allow POST without Content-Length header: No
Add a Behavior → Modify Outgoing Request Path:
- Action: Replace Entire Path
- Replace With: /validate
Add a Behavior → Caching:
- Caching Option: No Store
Click Save.

Watch out

Do not apply the EdgeWorker behavior to the /centinel-validate rule.

Set Property Manager variables

In your property configuration, go to Property Variables.
Add:

Variable	Value
`PMUSER_EW_CENTINEL_SECRET_KEY`	Your Centinel secret key
`PMUSER_EW_CENTINEL_FLOW`	Leave empty

(Optional) Add additional variables from the configuration reference below.
Click Save.

Variable visibility

Set variables to Hidden (not Sensitive) in Property Manager.

Attach the EdgeWorker

Under Property Configuration, click Add Rule and name it Centinel Protection.
Add a Criteria:
- Match Type: File Extension
- Match Operator: is not one of
- Case Sensitive: Off
- Value: the file types Centinel skips:

avi avif bmp css eot flac flv gif gz ico jpeg jpg js json
less map mka mkv mov mp3 mp4 mpeg mpg ogg ogm opus otf png
svg svgz swf ttf wav webm webp woff woff2 xml zip

Add a Behavior → EdgeWorkers and select your centinel-protection EdgeWorker ID.
Add a Behavior → Advanced with this metadata:

<edgeservices:cookie.pass-set-cookie-policy>ALWAYS</edgeservices:cookie.pass-set-cookie-policy>

Click Save.

Your pages stay cacheable. The EdgeWorker checks every request before the cache lookup and adds the _centinel cookie to each response after it, so the cookie is never stored in the cache.

Scope

To protect only part of your site, add a Path criterion to this rule.

Activate the property

Click Activate in Property Manager.
Select Staging for initial testing, or Production when ready.
Add activation notes and click Activate.
Wait for activation to complete (15-30 minutes).

Run alongside an existing EdgeWorker

Akamai runs one EdgeWorker per request. To add Centinel to rules that already run your own EdgeWorker, use Akamai flexible composition: your EdgeWorker imports Centinel as a module.

Activate Centinel without attaching it

Create, upload, and activate the Centinel EdgeWorker as described in Install.
Complete the Configure steps above, but leave the EdgeWorkers behavior out of the Centinel Protection rule. Your EdgeWorker stays on its own rule. If that rule covers only part of the property, add its criteria to Centinel Protection.

Add Centinel as a dependency

In your EdgeWorker's bundle.json, add a dependencies entry, keep your existing fields, and bump edgeworker-version as usual. Replace 12345 with the Centinel EdgeWorker ID. The key centinel is the module name you import in the next step.

{
  "edgeworker-version": "2.0.0",
  "dependencies": {
    "centinel": {
      "edgeWorkerId": 12345,
      "version": "active"
    }
  }
}

Call Centinel from your handlers

In your EdgeWorker's main.js, call Centinel before your own code, so blocked requests never reach it:

import * as centinel from "centinel";

export async function onClientRequest(request) {
  await centinel.onClientRequest(request);
  // Centinel responded: return, or a later respondWith() replaces it.
  if (request.wasTerminated()) return;

  // Your existing onClientRequest code.
}

export async function onClientResponse(request, response) {
  centinel.onClientResponse(request, response);

  // Your existing onClientResponse code, if any.
}

Centinel uses only these two handlers. Leave your other handlers as they are.

Activate your EdgeWorker

Upload the updated bundle as a new version of your EdgeWorker.
Activate it on staging and check it with the steps in Verify.
Activate it on production.

Before you activate, check:

Resource tier: use Dynamic Compute (Tier 200) or higher for your EdgeWorker. Its limits cover your code and Centinel together: 4 HTTP sub-requests, 20 ms of CPU, and 5.5 s of wall time per event handler. Centinel uses one sub-request in onClientRequest and waits up to PMUSER_EW_CENTINEL_TIMEOUT for it.
Property variables: all setVariable() calls in one event handler share a budget of 1,024 characters, names included, and setVariable() throws once it is spent. Centinel uses up to about 950 of them in onClientRequest. If your code also sets variables there, ask your Akamai representative to raise the limit to 4,000.
Updates: with "version": "active", activating a new Centinel version reactivates your EdgeWorker automatically. To decide when Centinel changes, import a fixed revision instead.
Permissions: Akamai lets a parent import children from the same account. Whoever activates your EdgeWorker needs Publisher access to it and Viewer access to the Centinel EdgeWorker.
subWorkers: if your bundle.json sets invoke-for-edgeworker-clients to true, turn the EdgeWorkers behavior off on the Centinel Validator rule, so your EdgeWorker does not run on the validator call.

Configuration reference

Required variables

Variable	Type	Description
`PMUSER_EW_CENTINEL_SECRET_KEY`	`string`	Your Centinel secret key for API authentication.

Optional variables

Variable	Type	Default	Description
`PMUSER_EW_CENTINEL_TIMEOUT`	`number`	`500`	Validator timeout in milliseconds.
`PMUSER_EW_CENTINEL_PROTECTED_PATHS_INCLUSION`	`string`	–	Regex pattern to protect only matching paths. Leave empty to protect all.
`PMUSER_EW_CENTINEL_PROTECTED_PATHS_EXCLUSION`	`string`	–	Regex pattern to skip validation. Static assets are excluded by default.
`PMUSER_EW_CENTINEL_ENABLE_DEBUGGING`	`string`	`false`	Set to `true` to write JSON debug lines to the EdgeWorker log.

Notes

Timeout: 500ms by default, adjustable with PMUSER_EW_CENTINEL_TIMEOUT.
Logging: Uses Akamai's built-in logger module. Check EdgeWorker logs in Control Center.
Fails open: any validator error, timeout, unparseable response, or missing secret key allows the request through. An unreachable validator means unprotected traffic, not blocked traffic.
Challenge size: a block or interstitial page larger than 2000 characters cannot be delivered. Blocks fall back to a generic page, and oversized challenges are skipped entirely.

Verify

Browse your site to confirm traffic flows normally.
Check that static assets (.js, .css, .png, etc.) load without delays.
Confirm a protected response carries a Server-Timing: validator;dur=... header.
On a page Akamai caches, send two requests with a browser User-Agent, no cookies, and the header Pragma: akamai-x-cache-on. The second should show X-Cache: TCP_HIT or TCP_MEM_HIT. Each response should carry its own _centinel value.
If the Server-Timing header is missing, send a GET to /centinel-validate on your protected hostname: it should return 405 Method Not Allowed. Repeat as a POST; a 403 Forbidden means the rule still needs the Allow POST behavior.
For detail, set PMUSER_EW_CENTINEL_ENABLE_DEBUGGING to true and read the JSON log lines in Control Center → EdgeWorkers → Logs.

Changelog

v3.0.5 — Current release, rebuilt from source
v3.0.4 — Fixed challenge cookie delivery
v3.0.2 — Crawler-aware handling
v3.0.1 — Response handling update
v3.0.0 — Fixed timeout, logging refactor
v2.0.1 — Logging and error handling
v2.0.0 — Cookie handling improvements
v1.0.0 — Initial release

Akamai EdgeWorkers

On this page