CloudFront

This module is to be used on the CloudFront distribution, using the Lambda@Edge service: https://aws.amazon.com/fr/lambda/edge/

Before the regular CloudFront process starts, an event is triggered at the viewer's request and executes the DataDome logic in a Lambda@Edge function.
The module makes a call to the closest Regional Endpoints using a Keep-Alive connection. Depending on the API's response, the module either blocks the request or lets CloudFront proceed with its regular process.

Supported runtimes

Node.js
Python

How to install and configure

Connect to your AWS console and go to the Lambda@Edge homepage

📘
AWS automatically selects US-EAST-1 region when you go on Lambda@Edge portal. Please don't change the region. The function must be created on this one.

Click on the "Create function" button, then select "Author from scratch"

In the Basic information section:

Enter a name for your Lambda function, e.g. DataDomeModule-{YOUR WEBSITE NAME}
Select Node.js 18.x or Python 3.9 for the runtime
Click on Create function

In the Function code 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 or datadome.py
The first code block in the file contains the module configuration.
You need to replace DATADOME_LICENSE_KEY with your own License Key, which is available in your DataDome dashboard.

📘
In case you already have an existing lambda function configured, you can refer to How to configure the module without editing the function file below.

In the Runtime settings tab:

Set "datadome.handler" for the Handler

In the Configuration tab and General configuration menu:

Set "Timeout" to 0 min 1 sec
Select an existing role with the required permissions. To confirm that the role has the required permissions, click on View the [ROLE NAME] role and refer to this section.
Click on "Save"

Optional settings are described in the following list below

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".

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"

In CloudFront Distributions at the Errors tab you should create a new error page for HTTP code 403 with minimal TTL 0 without any customization of the content:

Congrats!

Your CloudFront distribution will now deploy the new settings and your DataDome installation is completed!

Settings

Setting	Description	Required	Default
DATADOME_LICENSE_KEY	Your DataDome License key	Yes
DATADOME_TIMEOUT	The request timeout to DataDome API, in milliseconds	Optional	100
DATADOME_URI_REGEX	Processes matching URIs only	Optional
DATADOME_URI_REGEX_EXCLUSION	Ignores all matching URIs	Optional	exclude static asset
DATADOME_LOG_BOT_INFO	Logs the matching bots' info in CloudWatch (premium feature)	Optional	false

Logging

All logs are stored in your CloudWatch dashboards, in the "Logs" section.

FAQ

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 need to return this header : Cache-Control: no-cache="Set-Cookie"

You can find more information about this CloudFront behavior in AWS Documentation. (Section : Disable caching of Set-Cookie headers)

Can I get Bot Name, Bot 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.
This information is recorded in your CloudWatch logs. The list of all headers exposed is available in our Log Enrichment page.

How to only protect part of a CloudFront Distribution ?

In order to only protect part of a CloudFront Distribution, you can :

Set an exclusion based on file extension: modify the DATADOME_URI_REGEX_EXCLUSION in order to exclude hits to the Datadome API. In this case, the Lambda is still executed (and billed) at Amazon infrastructure
Set an exclusion based on path: define behavior in Cloudfront Distribution and attach Lambda only to the needed behavior. In this case, there is no Lambda execution at Amazon infrastructure nor at Datadome API

How to configure the role?

As per AWS documentation, the needed permissions are listed here: documentation

In the role section:

click on the Permissions tab and select Add inline policy

Select the JSON view and paste the following actions:

{
    "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"
    }
  ]
}

Stream lambda logs to Cloudwatch

If the lambda 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 DataDome be integrated on a multi-account architecture?

If you have several CloudFront distributions deployed on different AWS accounts, one Lambda@Edge function per account is required. You can repeat steps 1 to 10 for every account.

How to configure the module without editing the function file?

From version 1.18.0 of the Node.js lambda function, configuration of the module can be defined in an other file. The following example explains how to update a handler in the file index.js.

With the DataDome lambda code imported in the datadome.js file, the steps to follow are:

import the module.

const datadome = require("./datadome");

configure.

// 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 (only serverSideKey is mandatory).
Other keys are shown with their default values.

update the handler to execute the DataDome protection.

exports.handler = (event, context, callback) => {
  // Call DataDome handler
  datadome.handler(event, context, callback);
  // [...] 
}

make sure the handler configured for the lambda use index.handler in the Runtime settings.

How can I use environment variables in the lambda?

While lambda functions allow environment variables, it is not possible to them in Lambda@Edge due to an AWS limitation - see Restrictions on edge functions.