Centinel AnalyticaCentinel Analytica
PlatformsCDN / Edge

Akamai EdgeWorkers

Deploy Centinel Analytica on your Akamai property using 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.

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, needed for the cookie behavior in Configure below. Open a support ticket if your account lacks it.

Install

Download the package
  1. Download centinel-akamai-edgeworker.tgz.
  2. Extract the archive to get main.js and bundle.json.
Create the EdgeWorker
  1. Log into Akamai Control Center.
  2. Go to CDN → EdgeWorkers.
  3. Click Create EdgeWorker ID.
  4. Enter a name (e.g. centinel-protection).
  5. Select your Group, and choose Dynamic Compute (Tier 200) as the resource tier. Basic (Tier 100) does not allow enough wall-clock time for the validator call.
  6. Click Create EdgeWorker ID.
Upload the code
  1. Select the EdgeWorker you just created.
  2. Click Create Version.
  3. Upload the main.js and bundle.json files.
  4. Click Create Version.

Configure

Configure the validator route

The EdgeWorker calls the Centinel validator via an internal path. You need to route /centinel-validate to the Centinel API.

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

Watch out

Make sure the EdgeWorker behavior is not applied to the /centinel-validate rule—otherwise you'll create a recursion loop.

Set Property Manager variables
  1. In your property configuration, go to Property Variables.
  2. Add:
VariableValue
PMUSER_EW_CENTINEL_SECRET_KEYYour Centinel secret key
PMUSER_EW_CENTINEL_FLOWLeave empty

PMUSER_EW_CENTINEL_FLOW carries state from the request phase to the response phase. It must be declared, or the worker cannot emit cookies and headers on a block or challenge, and visitors end up looping on the interstitial.

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

Variable visibility

Set variables to Hidden (not Sensitive) in Property Manager. Hidden variables are readable by EdgeWorkers but won't be logged. Sensitive variables can't be read by EdgeWorker code at all.

Attach the EdgeWorker
  1. In your property, add or edit a rule where you want Centinel protection.
  2. Add a Behavior → EdgeWorkers.
  3. Select your centinel-protection EdgeWorker ID.
  4. Click Save.

Scope

Apply the EdgeWorker to your default rule to protect all paths, or add it to specific rules to protect only certain parts of your site.

  1. Add a Behavior → Advanced with this metadata, so Akamai stops stripping the challenge cookie:
<edgeservices:cookie.pass-set-cookie-policy>enabled</edgeservices:cookie.pass-set-cookie-policy>

Without this, visitors loop on the interstitial

Akamai removes Set-Cookie from responses the EdgeWorker generates. The challenge needs that cookie, so without this behavior a challenged visitor is challenged again on every request.

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

Configuration reference

Required variables

VariableTypeDescription
PMUSER_EW_CENTINEL_SECRET_KEYstringYour Centinel secret key for API authentication.

Optional variables

VariableTypeDefaultDescription
PMUSER_EW_CENTINEL_TIMEOUTnumber500Validator timeout in milliseconds.
PMUSER_EW_CENTINEL_PROTECTED_PATHS_INCLUSIONstring–Regex pattern to protect only matching paths. Leave empty to protect all.
PMUSER_EW_CENTINEL_PROTECTED_PATHS_EXCLUSIONstring–Regex pattern to skip validation. Static assets are excluded by default.

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 challenge 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, which shows the EdgeWorker ran.
  • For detail, set PMUSER_EW_CENTINEL_ENABLE_DEBUGGING to true and read the JSON log lines in Control Center → EdgeWorkers → Logs.

Changelog

  • 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

Fastly Compute (Rust)

Add Centinel Analytica bot protection to your Fastly Compute service using the Rust SDK.

AWS CloudFront

Deploy Centinel Analytica on an existing CloudFront distribution via Lambda@Edge.

On this page

OverviewPrerequisitesInstallConfigureConfiguration referenceRequired variablesOptional variablesNotesVerifyChangelog