AWS CloudFront Function
This module is made for AWS CloudFront distributions, using AWS CloudFront Functions.
The DataDome CloudFront Function module protects your CloudFront distribution with two lightweight functions:
- A viewer request function calls the DataDome API for each request. Then it forwards the request to your origin, or it returns DataDome's challenge or block response.
- A viewer response function adds DataDome's cookies and headers to the responses of allowed requests.
Compared with the Lambda@Edge module, this module has several advantages:
- 60% lower cost than the Lambda@Edge
- Sharper detection of bad bots and malicious AI agents, including TLS fingerprinting (JA3 and JA4)
- Enriched logs for faster incident response and SIEM correlation
- Scales to millions of requests per second
The viewer request function calls the DataDome API with CloudFront Functions network calls (cf.fetch()).
Supported runtime
| Module | Runtime | Events |
|---|---|---|
| CloudFront Function | cloudfront-js-2.0 |
|
Installation
Prerequisites
- The server-side key available in your DataDome dashboard
- The module package.
The package contains one file for each function:
datadome-cf-function-viewer-request.jsdatadome-cf-function-viewer-response.js
Both files are already minified, so they fit within the 10 KB code size limit of CloudFront Functions.
All the settings, including your server-side key, are in a configuration block at the top of the viewer request file (see Settings). Do not edit the code outside this block.
1. Add the DataDome API origin to your distribution
The viewer request function can only call an origin configured on the same distribution.
- In the CloudFront console, open your distribution, then Origins > Create origin.
- Set:
- Origin domain:
api-functions.datadome.co - Protocol:
HTTPS only - Minimum origin SSL protocol:
TLSv1.2 - Name:
api-functions.datadome.co
- Origin domain:
- Click Create origin.
A behavior for this origin is not necessary.
2. Create the viewer request function
- Go to Functions > Create function.
- Set the Name (for example,
datadome-viewer-request) and select the cloudfront-js-2.0 runtime. - In the Build tab, paste the content of
datadome-cf-function-viewer-request.js. -
In the configuration block at the top of the code, set your server-side key:
const DATADOME_SERVER_SIDE_KEY = 'YOUR_SERVER_SIDE_KEY';If necessary, change the other settings (see Settings).
- Click Save changes, then Publish > Publish function.
3. Create the viewer response function
- Go to Functions > Create function.
- Set the Name (for example,
datadome-viewer-response) and select the cloudfront-js-2.0 runtime. - In the Build tab, paste the content of
datadome-cf-function-viewer-response.js. No configuration is needed. - Click Save changes, then Publish > Publish function.
4. Create the origin request policy
The viewer request function only receives the CloudFront headers that the behavior's origin request policy forwards. Create a policy that forwards the TLS fingerprints (JA3 and JA4) to the function:
- Go to Policies > Origin request > Create origin request policy.
- Set the Name (for example,
DataDome-CloudFrontFunction). - Under Headers, choose All viewer headers and the following CloudFront headers.
- Select
CloudFront-Viewer-JA3-FingerprintandCloudFront-Viewer-JA4-Fingerprint. - Set Query strings and Cookies to the values that your origin needs (usually All).
- Click Create.
Your behavior already has an origin request policyIf the policy is a custom policy, add the two headers to it. You cannot edit a managed policy. Instead, create a custom policy with the same query string and cookie settings.
If the policy forwards only some headers instead of All viewer headers, add
Refererto use referrer restoration (DATADOME_REFERRER_RESTORATION): without it, your origin never receives the restoredReferer.
5. Associate the functions with your distribution
For each behavior you want to protect:
- Open Behaviors > select the behavior > Edit.
- Under Cache key and origin requests, set the Origin request policy to the policy from step 4.
- Under Function associations:
- Viewer request: function type CloudFront Functions, select the viewer request function.
- Viewer response: function type CloudFront Functions, select the viewer response function.
- Save the changes. Then wait until the distribution deployment is complete.
Advanced configuration
Settings
Settings are constants in the configuration block at the top of datadome-cf-function-viewer-request.js. The block ends with the // ==== End of DataDome configuration ==== comment line. The block is not minified.
To change a setting:
- In the Build tab of the function, edit the value.
- Click Save changes.
- Click Publish > Publish function.
| Constant | Type | Description | Required | Default |
|---|---|---|---|---|
DATADOME_SERVER_SIDE_KEY | Text, in quotes | Your DataDome server-side key | Yes | '' (empty: requests are allowed without protection, fail open) |
DATADOME_URI_REGEX_EXCLUSION | Regular expression, or null | Paths not sent to DataDome (see URL exclusion) | No | null |
DATADOME_REFERRER_RESTORATION | true or false | Restore the original Referer after a challenge (the dd_referrer query parameter is removed and its value set as Referer). The origin request policy must forward the Referer header | No | false |
DATADOME_ENDPOINT_ORIGIN_ID | Text, in quotes | Name of the distribution origin pointing to api-functions.datadome.co | No | 'api-functions.datadome.co' |
DATADOME_STATIC_ASSET_EXCLUSION | Regular expression, or null | Static assets not sent to DataDome (see URL exclusion) | No | See default pattern |
DATADOME_ENCODED_CHAR_INCLUSION | Regular expression, or null | Encoded characters that send a static asset to DataDome anyway (see URL exclusion) | No | /%23|%25|%2f|%3b|%3f/i |
DATADOME_REMOVE_MATRIX_PARAMS | true or false | Remove matrix parameters (;name=value at the end of a path segment, RFC 3986) from the path before matching the URL exclusion patterns | No | true |
Change only the values. Keep the JavaScript syntax of each line: quotes around text, slashes around regular expressions, and null without quotes.
URL exclusion
The patterns are JavaScript regular expression literals. The function matches them against the request path as received: percent-encoded, and without the query string. The i flag makes a pattern case-insensitive. To disable a pattern, set it to null. The function applies the patterns in this order, the same as the Lambda@Edge module:
- A path matching
DATADOME_URI_REGEX_EXCLUSIONis not sent to DataDome. For example,/^\/health/iexcludes/healthand everything below it. - A path matching
DATADOME_STATIC_ASSET_EXCLUSIONis not sent to DataDome, unless it also matchesDATADOME_ENCODED_CHAR_INCLUSION. - Every other path is sent to DataDome.
When DATADOME_REMOVE_MATRIX_PARAMS is true, matrix parameters are removed before matching: /img/logo.png;jsessionid=abc is matched as /img/logo.png. The request sent to your origin is unchanged.
The default static assets pattern is:
const DATADOME_STATIC_ASSET_EXCLUSION = /\.(avi|avif|bmp|css|eot|flac|flv|gif|gz|ico|jpeg|jpg|js|json|less|map|mka|mkv|mov|mp3|mp4|mpeg|mpg|ogg|ogm|opus|otf|png|svg|svgz|swf|ttf|wav|webm|webp|woff|woff2|xml|zip)$/i;Custom logic (hooks)
The configuration block also has two functions, called hooks, for your own logic.
| Hook | Called when | Returns |
|---|---|---|
onAllowedRequest(event, request) | DataDome allows the request. Not called on excluded paths, or when the request is allowed without a DataDome decision (fail open, empty server-side key). | The request sent to your origin (request already has the DataDome headers), or a response object to answer the viewer directly. |
onChallengedRequest(event, response) | DataDome blocks or challenges the request. | The response sent to the viewer. response is DataDome's response, in CloudFront format: statusCode, headers, cookies, body. |
event is the CloudFront Functions event of the viewer request. For example, to add a header to the requests that DataDome allows:
function onAllowedRequest(event, request) {
request.headers['x-protected-by'] = { value: 'DataDome' };
return request;
}- Hooks can be
asyncfunctions. - Hooks cannot make network calls: CloudFront allows one per invocation, and the DataDome API call uses it.
- If a hook throws an error, or returns nothing, the function logs
error: <hook> failed (…), DataDome decision keptand applies DataDome's decision unchanged: a blocked request stays blocked. - Hooks count toward the 10 KB code size limit. About 0.9 KB is left for your code.
onAllowedRequestcannot change your origin's response: the viewer request function runs before the origin.
Logging
The enriched headers returned by DataDome (allowed, blocked, or challenged requests) are written to the viewer-request-log-data field of the CloudFront access logs, for example, x-datadome-isbot=1,x-datadome-botname=curl. To add this field to your standard logging (v2):
- Open your distribution, then the Logging tab.
- Click Add, or edit an existing destination.
- Under Additional settings, in Field selection, select
viewer-request-log-data. - Save the changes.
You can also add the field to real-time logs. CloudFront URL-encodes the value and keeps up to 800 bytes per request (see logCustomData()).
Limitations
- GraphQL and MCP requests are not supported: these requests are still protected, but request bodies cannot be read to get protocol-specific properties.
FAQ
Are challenge and block pages cached by CloudFront?
No. CloudFront does not cache the responses of a viewer request function.
Can I use the same settings for several distributions?
Yes. Associate the same viewer request and viewer response functions with each distribution. Each distribution needs the DataDome API origin, with the Name set in DATADOME_ENDPOINT_ORIGIN_ID. Make sure to also select the defined origin request policy.
Where are DataDome logs, and what do they contain?
In CloudWatch Logs, region us-east-1, log group /aws/cloudfront/function/<function name>. Each protected request writes one line starting with [DataDome]: allowed, blocked, payload over … (optional fields dropped), or fail open with the reason. Configuration problems are logged too:
error: DATADOME_SERVER_SIDE_KEY is empty, fail open: the server-side key is not set in the configuration block. The request is allowed without protection (fail open).error: onAllowedRequest failed (nothing returned), DataDome decision kept: the custom logic failed to return a request object. The process continues ignoring the custom logic hook.
Updated about 7 hours ago

