Akamai Edge Worker

DataDome Akamai integration detects and protects against bot activity.

Before the Akamai EdgeWorker processes a client request, the proxy will call the DataDome API through the HttpRequest module. Depending on the API response, the integration will either block the request and return the content provided by DataDome, or let Akamai proceed with the regular process. The module has been developed to protect the users’ experience: if any errors were to occur during the DataDome process or if the call to DataDome reaches a timeout, the integration will automatically assume a 200 for that request, and continue the process normally.

Prerequisites

This article assumes that you already have:
1. Access to the Akamai Dashboard: https://control.akamai.com/apps/home-page/
2. Set up the concerned website as an Akamai Property: https://control.akamai.com/apps/property-manager
3. Enabled access to the Akamai EdgeWorkers from the Akamai Marketplace: https://control.akamai.com/apps/marketplace-ui
4. Ability to create EdgeWorkers: https://control.akamai.com/apps/edgeworkers/

πŸ“˜

We support both Basic and Dynamic Akamai EdgeWorker resource tier. We recommend to use Basic resource tier.

Installation

Setting up the EdgeWorker

  1. Access the EdgeWorkers Management screen at: https://control.akamai.com/apps/edgeworkers
  2. Click on the Create EdgeWorker ID button at the top-right
194
  1. The Create EdgeWorker ID modal is shown
    1. Set the name of the EdgeWorker to EW_DataDome_Protection
    2. The Group refers to which set of access permissions are you going to apply to the newly created EdgeWorker
    3. Set the Resource Tier to Basic Compute
1002
  1. A new row will be added in the EdgeWorker table

πŸ“˜

By default the EdgeWorker is not enabled in either Staging or Production

1294
  1. Click on the respective ID, the EdgeWorker ID details page will be shown
  2. Click on the Create Version button, the Create version modal will be shown
149
  1. Drag and drop the provided tar file in the droppable area
1062
  1. The droppable area should validate the dropped bundle
578
  1. Click on the Create version button on the bottom-right of the modal
  2. A row will be added to the Versions table
  3. Click on the last version added, the EdgeWorker version details page will be shown
  4. Click on the Activate version button, the Activate version modal will be shown
149
  1. Choose a Network to deploy this version to

πŸ“˜

It is recommended that deployments are first done in Staging to be validated, then deployed to Production when all the necessary checks are made

❗️

EdgeWorker environments are updated separately, the activation process needs to be done twice to update both the Staging and the Production environments

595
  1. Click on the Activate version button to proceed; the EdgeWorker version details page will get updated with a notification on the top-right and a progress bar.
1606
  1. Kindly wait until the progress bar is full and green, and the version is marked as active in that environment.
493

Changes in the Property Manager

❗️

This will require that you create a new version of your property, otherwise you will not be allowed to edit a Property version that is already deployed to Staging and/or Production.

Step 1: Add the following variables in the Property Variables section

πŸ“˜

Please note that Akamai prepends the variables with β€œPMUSER_” - no need to re-add it.

Variable NameInitial ValueDescriptionSecurity SettingsNotes
EW_CLIENT_IPUsed to get the client IPHidden
EW_TLS_VERSIONUsed to retrieve the TLS versionHidden
EW_TLS_CIPHER_NAMEUsed to retrieve the TLS Cipher nameHidden
EW_DD_FLOWUsed as a flow control variableHidden
EW_DD_LOG_HEADERUsed to retrieve the X-DataDome-log headerHidden
EW_DD_LICENSE_KEY[parameter_required]DataDome Server Side keyHidden
EW_DD_DOMAIN[parameter_required]DataDome API endpointHiddenapi-akamai.datadome.co
EW_DD_TIMEOUT[parameter]DataDome call timeoutHiddenValue : 150 (in ms)
EW_DD_ENABLE_LOGGING[parameter]Used to enable retrieval of X-DataDome-log headerHiddenValue should be true or false

Default value is false

Used to determine whether the X-DataDome-Log header should be added to the response

Step 2: Enable the EdgeWorker

  1. Scroll down to the Property Configuration Settings panel and click on +Rules
485
  1. The Add Rule modal will be shown; search for Blank Rule Template. For the purpose of this documentation we will be naming the rule EW_DD_Rule. Click on the Insert Rule button when done
1099
  1. By default, Akamai adds new rules at the very end of the configuration settings, scroll to the very bottom of the list and click on the newly added rule. Both the Criteria and the Behaviors panels should be empty.
  2. Add the following criteria in the Criteria panel - this will not forward static file requests to the EdgeWorker:
If
File Extension
is not one of
avi
flv
mka
mkv
mov
mp4
mpeg
mpg
mp3
flac
ogg
ogm
opus
wav
webm
webp
bmp
gif
ico
jpeg
jpg
png
svg
svgz
swf
eot
otf
ttf
woff
woff2
css
less
js

Case Sensitive: Off
1287
  1. Add the following behaviours in the Behaviors panel:

πŸ“˜

Please note that the behaviours need to be added in the order specified in the table

OrderTypeSettings
1Set Variable- Variable: PMUSER_EW_CLIENT_IP
- Create Value From: Expression
- Expression: {{builtin.AK_CLIENT_IP}}
- Operation: None
2Set Variable- Variable: PMUSER_EW_TLS_VERSION
- Create Value From: Expression
- Expression: {{builtin.AK_TLS_VERSION}}
- Operation: None
3Set Variable- Variable: PMUSER_EW_TLS_CIPHER_NAME
- Create Value From: Expression
- Expression: {{builtin.AK_TLS_CIPHER_NAME}}
- Operation: None
4EdgeWorkers- Enable: On
- Identifier: EW_DataDome_Protection
683 863
  1. Click on the Save button at the top-right or bottom-right
78

Step 3: Map the call from the EdgeWorker to the DataDome API

πŸ“˜

This part of the installation is required because Akamai EdgeWorkers are not allowed to make subrequests to origins that are not on the Akamai network. For this reason the /validate-request path is mapped to forward the requests to the DataDome API: see Akamai documentation

  1. Scroll down to the Property Configuration Settings panel and the find Accelerate delivery > Origin connectivity
462
  1. Click on the Origin connectivity rule and add the following Criteria
If
Path
matches one of
/validate-request
1314
  1. Click on the +Behavior button (top-right of the Behaviors panel) and add the following:
OrderTypeSettings
LastOrigin Server-Origin Type: Your Origin
- Origin Server Hostname: {{user.PMUSER_EW_DD_DOMAIN}}
- Forward Host Header: Custom Value
- Custom Forward Host Header: {{user.PMUSER_EW_DD_DOMAIN}}
- Cache Key Hostname: Origin Hostname
- Supports Gzip Compression: Yes
- Send True Client IP Header: Yes
- True Client IP Header Name: True-Client-IP
- Allow Clients To Set True Client IP Header: No

Origin SSL Certificate Verification
- Verification Settings: Use Platform Settings
- Use SNI TLS Extension: Yes

Ports
- HTTP Port: 80
- HTTPS Port: 443

❗️

Please note that the Origin Connectivity might have other behaviours, it is important that the above behaviour is added at the end

Click on the Save button at the top-right or bottom-right

78

Step 4: Bypass mPulse

❗️

Please note that this step only applies if the mPulse module is configured in your property

  1. Under the Property Configuration Settings Section, find the Augment Insights >
    mPulse RUM rule.
467
  1. In the Criteria section, add the following rule:
If
Path
does not match one of
/validate-request

🚧

Please make sure that the mPulse API key is filled in; this is because the condition set up above will only take effect if this value is provided

This value can be found by following the steps found at: https://techdocs.akamai.com/mpulse/docs/about-edge-injection

975

Step 5: Activate the changes

  1. Following completion of the above steps, activation is required to test the setup. Switch to the Activate tab at the top.
243
  1. Click on the Activate vX on Staging button, the Activate version modal will be shown

🚧

It is recommended that deployments are first done in Staging to be validated, then deployed to Production when all the necessary checks are made

❗️

An email address must be inputted to notify you about the completion of the activation process

360 1093
  1. Click on the Activate vX on Staging button to proceed; the Property version activation details page will get updated with a notification on the top-right and a progress bar.
1871
  1. Kindly wait until the progress bar is full and green, and the version is marked as active in that environment.