Akamai Edge Worker
Akamai integration for Bot Protection
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
- Access the EdgeWorkers Management screen at: https://control.akamai.com/apps/edgeworkers
- Click on the Create EdgeWorker ID button at the top-right
- The Create EdgeWorker ID modal is shown
- Set the name of the EdgeWorker to EW_DataDome_Protection
- The Group refers to which set of access permissions are you going to apply to the newly created EdgeWorker
- Set the Resource Tier to Basic Compute
- A new row will be added in the EdgeWorker table
By default the EdgeWorker is not enabled in either Staging or Production
- Click on the respective ID, the EdgeWorker ID details page will be shown
- Click on the Create Version button, the Create version modal will be shown
- Drag and drop the provided tar file in the droppable area
- The droppable area should validate the dropped bundle
- Click on the Create version button on the bottom-right of the modal
- A row will be added to the Versions table
- Click on the last version added, the EdgeWorker version details page will be shown
- Click on the Activate version button, the Activate version modal will be shown
- 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
- 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.
- Kindly wait until the progress bar is full and green, and the version is marked as active in that environment.
Changes in the Property Manager
Step 0: Create a new version of your Akamai property
- Go to your Akamai property you would like to protect with DataDome
- Create a new version of this property to be able to update it
You need to 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 and their respective value in the Property Variables section
Please note that Akamai prepends the variables with βPMUSER_β - no need to re-add it.
Variable Name | Description | Security Settings | Notes |
---|---|---|---|
EW_DD_LICENSE_KEY | Datadome Server Side Key | Hidden | Value of your Server Side Key available in DataDome Dashboard > Management > Integrations |
EW_DD_DOMAIN | DataDome API Endpoint | Hidden | Value: api-akamai.datadome.co |
EW_DD_ENABLE_LOGGING | Used to enable log inside X-DataDome-log header | Hidden | Value should be true or false Default value is false . |
EW_DD_TIMEOUT | DataDome Timeout | Hidden | Value : 300 (in ms) |
EW_CLIENT_IP | Used to get the client IP | Hidden | |
EW_TLS_VERSION | Used to retrieve the TLS version | Hidden | |
EW_TLS_CIPHER_NAME | Used to retrieve the TLS Cipher name | Hidden | |
EW_DD_FLOW | Used as a flow control variable | Hidden | |
EW_DD_LOG_HEADER | Used to retrieve the X-DataDome-log header | Hidden |
Step 2: Enable the EdgeWorker
- Scroll down to the Property Configuration Settings panel and click on +Rules
- 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
- 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.
- Add the following criteria in the Criteria panel - this will not forward static file requests to the EdgeWorker
- Criteria :
Match All
- Case Sensitive:
Off
- Condition _: If
File extension
is not one of
- Criteria :
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
- Add the following behaviors in the Behaviors panel:
Please note that the behaviors need to be added in the order specified in the table
Order | Type | Settings |
---|---|---|
1 | Set Variable | - Variable: PMUSER_EW_CLIENT_IP - Create Value From: Expression - Expression: {{builtin.AK_CLIENT_REAL_IP}} - Operation: None |
2 | Set Variable | - Variable: PMUSER_EW_TLS_VERSION - Create Value From: Expression - Expression: {{builtin.AK_TLS_VERSION}} - Operation: None |
3 | Set Variable | - Variable: PMUSER_EW_TLS_CIPHER_NAME - Create Value From: Expression - Expression: {{builtin.AK_TLS_CIPHER_NAME}} - Operation: None |
4 | EdgeWorkers | - Enable: On - Identifier: EW_DataDome_Protection |
- Click on the Save button at the top-right or bottom-right
Step 3: Forward 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
- Scroll down to the Property Configuration Settings panel and click on +Rules
- The Add Rule modal will be shown; search for Blank Rule Template. For the purpose of this documentation we will be naming the rule OriginConnectivity_DD_Rule. Click on the Insert Rule button when done
- By default, Akamai adds new rules at the very end of the configuration settings, scroll to the very bottom of the list and drag this new rule before the previously created EW_DD_Rule as can be seen in the below screenshot.
-
Click on the newly added rule. Both the Criteria and the Behaviors panels should be empty.
-
Add the following Criteria
- Criteria :
Match All
- Condition _: If
Path
matches one of
/validate-request
- Criteria :
- Click on the +Behavior button (top-right of the Behaviors panel) and add the following:
Type | Settings |
---|---|
Origin 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: NoOrigin SSL Certificate Verification - Verification Settings: Choose Your Own - Use SNI TLS Extension: YesPorts - HTTP Port: 80 - HTTPS Port: 443 |
- Click on the Save button at the top-right or bottom-right
Step 4: Bypass mPulse
Please note that this step only applies if the mPulse module is configured in your property
Due to the size of mPulse Javascript and Akamai limitation on EdgeWorker, when DataDome respond a captcha, we need to disable mpsulse. We only disable it for the captcha and block page.
- Under the Property Configuration Settings Section, find the Augment Insights >
mPulse RUM rule.
- In the Criteria section, add the following rule:
- Criteria :
Match All
- Condition: If
Path
matches one of
/validate-request
- Criteria :
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
Step 5: Activate the changes
- Following completion of the above steps, activation is required to test the setup. Switch to the Activate tab at the top.
- 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
- 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.
- Kindly wait until the progress bar is full and green, and the version is marked as active in that environment.
Troubleshooting
Unresponsive page and 301 (redirect) responses
If after installation your page is unresponsive, seems to be blocked on the EdgeWorker and you are not seeing any traffic on Datadome, make sure you do not have any Policy redirecting all the traffic to some kind of default path.
If it is the case, please make sure the /validate-request path is not included, so the calls will go to Datadome API.
No traffic sent to DataDome
- Validate the variables have been correctly defined inside INITIAL VALUE column and not DESCRIPTION column
- Validate the Akamai Edge Worker is executed and the version matches our current version :
Execute a curl on a specific url with Akamai Pragma Header :
Pragma:akamai-x-get-client-ip, akamai-x-cache-on, akamai-x-cache-remote-on, akamai-x-check-cacheable, akamai-x-get-cache-key, akamai-x-get-extracted-values, akamai-x-get-nonces, akamai-x-get-ssl-client-session-id, akamai-x-get-true-cache-key, akamai-x-serial-no, akamai-x-get-request-id, akamai-x-ew-debug
In the curl response, you would be able to see if the EdgeWorker have been executed (and the version of the EdgeWorker which was executed. Eg : Here in the example v1.1.0). If it is not executed, please verify the rule to call the edge worker is correctly set up (Step 3)
< x-akamai-edgeworker-onclientresponse-info: ew=81212 v1.1.0:EW_DataDome_Protection; status=Success
< x-akamai-edgeworker-onclientrequest-info: ew=81212 v1.1.0:EW_DataDome_Protection; status=Success
Traffic received by DataDome but Captchas are not displayed
- Enable DataDome integration logging by adding inside Akamai property the variable
EW_DD_ENABLE_LOGGING
with the valuetrue
. Redeploy your Akamai property - Inspect the http response header and look for header
x-datadome-log
. If you see
x-datadome-log: Error: RangeError: Response body length exceeds limit of 2048
It means the captcha page we return is too large (> 2048 Characters). This is a product limit of Akamai EdgeWorker
- It is probably due to Akamai muPulse Monitoring enabled for this property. (mPulse add a lot of Javascript content inside the page to be able to monitor it). You need to disable it for our api calls
- Redeploy Akamai property with mPulse exclusion.
FAQ
How can I exclude IPs and not send traffic to DataDome?
- Akamai allows ClientIP match based on an IP address, a range of IP addresses, or a CIDR block.
- The IP values can be added separated by space, comma, or carriage return.
- For more information, please check Akamai's official documentation page.
Updated 5 days ago