CloudFront
This module is to be used on the CloudFront distribution, using the AWS CloudFront Lambda@Edge service.
Compatibility
- Node.js 14.x+
- Python 3.9+
Installation
Requirements
datadome_server_side_key
available in your DataDome dashboard,- IAM permissions required to associate Lambda@Edge functions with CloudFront distributions as defined by AWS. Refer to this section to help you create them.
Protect your traffic
- Connect to your AWS console and go to the Lambda@Edge homepage.
The function must be created on US-EAST-1 region.
AWS automatically selects US-EAST-1 region when you access the Lambda@Edge portal.
Please don't change the region.
- Click on the Create function button, then select Author from scratch.
You can configure DataDome on an existing Lambda@Edge function
In case you already have an existing Lambda@Edge function configured, you can refer to How to configure the module without editing the function file below.
- In the Basic information section:
- Enter a name for your Lambda function, e.g.
DataDomeModule-{YOUR WEBSITE NAME}
, - Select
Node.js 20.x
orPython 3.11
for the runtime, - Click on Create function.
- In the Code source tab:
- Choose Upload a file from Amazon S3 and paste the following URL for the selected module:
https://s3.amazonaws.com/dd-lambda-edge/datadome-lambda-edge-latest.zip
https://s3.amazonaws.com/dd-lambda-edge/datadome-lambda-edge-py-latest.zip
- Open the file
datadome.js
(ordatadome.py
). - Replace YOUR_DATADOME_LICENSE_KEY with your own DataDome server-side key, available in your DataDome dashboard.
- Scroll down to the Runtime settings tab, click on Edit .
- In the Runtime settings page:
- Enter
datadome.handler
(for the Node.js runtime) ordatadome.lambda_handler
(for the Python runtime) in the Handler field. - Click on Save.
- In the Configuration tab and General configuration menu, click on Edit.
- In the Edit basic settings page:
- Set Timeout to 0 min 1 sec,
- Select an existing role with the required permissions,
- Click on Save.
- Click on Actions and select Publish new version. You can set a version description and click on Publish.
- In the Configuration tab click on Add trigger.
- In the Add trigger page:
- Choose CloudFront as trigger and click on Deploy Lambda@Edge,
- Select the CloudFront distribution that will send events to the Lambda function,
- Select Viewer Request for CloudFront Event,
- Do not check the Include body box,
- Check the Confirm deploy to Lambda@Edge box,
- Click on Deploy.
- Go to your CloudFront distribution general page.
- In the Error pages tab, click on Create custom error response.
- In the Create custom error response page:
- Select HTTP code 403 ,
- Set minimal TTL 0 ,
- Check no for Customize error response.
- Click on Create custom error response.
Congrats! You can now see your traffic in your DataDome dashboard.
Configuration
By default, the configuration is located in the first code block of the datadome.js
(or datadome.py
) file.
Refer to the next Settings section for the full list of possible configuration settings.
Settings
Setting | Description | Required | Default |
---|---|---|---|
DATADOME_LICENSE_KEY | Your DataDome server side key, found in your Dashboard | Yes | |
DATADOME_TIMEOUT | The request timeout to DataDome API, in milliseconds | Optional | 300 |
DATADOME_URI_REGEX | Regular expression to include URIs in the DataDome analysed traffic | Optional | |
DATADOME_URI_REGEX_EXCLUSION | Regular expression to exclude URIs from the DataDome analysis | Optional | List of excluded static assets below |
DATADOME_LOG_BOT_INFO | Boolean to log the requests' bot information in CloudWatch (premium feature) | Optional | false |
DATADOME_ENABLE_GRAPHQL_SUPPORT | Boolean to enable GraphQL support - See How can I enable GraphQL support? | Optional | false |
/\.(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|map)$/i
FAQ
How do I get the logs of the Lambda@Edge?
All logs are stored in your CloudWatch dashboards, in the "Logs" section.
If the Lambda@Edge doesn't trigger any logs in the different region used, please check your IAM role and add the following configuration:
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": [
"*"
]
}
Can I get Bot Name, Rule Type and Bot/Human flags in my application?
The DataDome module can inject headers in the HTTP Request that can be read by your application.
The list of all headers exposed is available in our Log Enrichment page.
These headers are recorded in your CloudWatch logs.
How can I disable CloudFront caching for requests protected by DataDome?
If you are caching dynamic requests (not javascript, css, images) at CloudFront level and these requests are protected by DataDome, you need to change your backend origin to ask CloudFront to not cache these requests if they contain a set-cookie
in the response.
Indeed, by default CloudFront will cache http requests even if the backend returned a cookie. It can lead to unexpected bot detection issue. Your backend/origin needs to return this header : Cache-Control: no-cache="Set-Cookie"
You can find more information about this CloudFront behavior in AWS Documentation, in the Disable caching of Set-Cookie headers section.
How can I protect only a part of a CloudFront Distribution?
In order to protect only a part of a CloudFront Distribution, select one of the possibilities below:
- First option: set an exclusion based on file extension. Modify the value
DATADOME_URI_REGEX_EXCLUSION
insidedatadome.js
(ordatadome.py
) in order to exclude hits to the Datadome API. In this case, the Lambda@Edge is still executed (and billed) at the Amazon infrastructure level. - Second option: set an exclusion based on path. Define a behavior in you CloudFront Distribution and attach the Lambda@Edge only to the needed paths. In this case, there is no Lambda execution at Amazon infrastructure nor at Datadome API.
How can I configure the role?
The needed permissions are listed in AWS documentation.
In the Role section:
- Click on the Permissions tab and select Add inline policy.
- Select the JSON view and paste the following permissions:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"iam:CreateServiceLinkedRole",
"lambda:GetFunction",
"cloudfront:UpdateDistribution",
"lambda:EnableReplication"
],
"Resource": "*"
}
]
}
- Input a name for the permissions and save.
- Click on the Trust relationships tab and Edit the trust relationship.
- Paste the following trusted entities:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"lambda.amazonaws.com",
"edgelambda.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
How can I integrate DataDome on a multi-account architecture?
If you have several CloudFront distributions deployed on different AWS accounts, one Lambda@Edge function per account is required. Repeat steps 1 to 16 of the installation from the Protect your traffic section.
How do I call and configure the module from another function file?
From version 1.18.0 of the Node.js Lambda@Edge, calling and configuring the module can be done inside another file.
The following example explains how to update a handler in the file index.js
.
- Import the DataDome code as mentioned in the installation steps.
- Import the DataDome module inside your
index.js
file:
const datadome = require("./datadome");
- Configure the DataDome module inside your
index.js
file:
// Configure DataDome module
const configuration = {
serverSideKey: 'serverSideKeyValue',
timeout: 300,
maxSockets: 100,
debug: false,
urlPatternInclusion: null,
urlPatternExclusion: /\.(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|map)$/i
};
datadome.configure(configuration);
Update the
configuration
values (onlyserverSideKey
is mandatory).Other keys are shown with their default values.
- Update your handler from the
index.js
file to execute the DataDome protection:
exports.handler = (event, context, callback) => {
// Call DataDome handler
datadome.handler(event, context, callback);
// [...]
}
- Make sure the handler configured for this Lambda@Edge is
index.handler
in the Runtime settings section.
How can I dynamically configure the module?
It is not possible to use environment variables in Lambda@Edge due to an AWS limitation - see Restrictions on edge functions.
However you can still follow the steps to configure the module from another function file and override a configuration depending on AWS Secrets Manager for instance.
Can I use CloudFront Functions?
It is not possible to set up DataDome inside CloudFront Functions as they do not provide network access to call third-party APIs - see Restrictions on CloudFront Functions.
How can I enable GraphQL support?
Since version 1.19.0
of CloudFront Node.js, it is possible to enable GraphQL support:
- Change the value of
DATADOME_ENABLE_GRAPHQL_SUPPORT
totrue
inside thedatadome.js
:
const DATADOME_ENABLE_GRAPHQL_SUPPORT = true;
- Configure the CloudFront distribution behavior:
- Allow
POST
methods
- Include the body of the request in the DataDome Lamda@Edge on the viewer request by checking the corresponding box:
Some headers are missing on viewer requests. How can I get them?
Some custom headers such as X-DataDome-ClientID
for the session by header feature might not be visible on viewer requests.
To make them available, we recommend to change the origin request policy of your CloudFront distribution to include all headers.
You can achieve this by using the managed policy called AllViewer
as described on this AWS documentation.
How can I enable HTTP Client hints?
HTTP Client hints can be collected by the DataDome module to enhance the detection.
For these values to be defined by the browser, Accept-CH
header must be sent by the origin. You can achieve this by using a response header policy .
For the header Accept-CH
set the value:
Sec-CH-UA,Sec-CH-UA-Mobile,Sec-CH-UA-Platform,Sec-CH-UA-Arch,Sec-CH-UA-Full-Version-List,Sec-CH-UA-Model,Sec-CH-Device-Memory
Updated 19 days ago