This DataDome module is developed in Lua and integrates smoothly with OpenResty.

The module is configured on the initialization phase and makes a call to the DataDome API on the access phase (see details here).

Compatibility

The module has been tested and verified on the following versions:

OpenResty 1.21+

Installation

On the OpenResty server run the following command:

sudo luarocks install datadome-openresty

Configuration

Add the DataDome configuration below to the http block.
By default, the configuration is located on /usr/local/openresty/nginx/conf/nginx.conf

Make sure to replace the datadome_server_side_key
- Available inside your Dashboard > Integrations
Make sure to replace the lua_ssl_trusted_certificate
- For example, Ubuntu certificate path: /etc/ssl/certs/ca-certificates.crt


http {
    # ...

    # DataDome configuration
    resolver 8.8.8.8;

    lua_ssl_verify_depth 3;
    lua_ssl_trusted_certificate /path/to/certs/ca-certificates.crt;
    
    init_by_lua_block {
        require("datadome_openresty").setDatadomeConf({ datadome_server_side_key = "server_side_key",})
    }

    #....
}

Add the following DataDome logic to the location block.
For some OpenResty distributions, this part is not located inside nginx.conf but in /usr/nginx/conf.d/default.conf

server {
   # ...

    location / {
        #...
        
        # DataDome configuration
        access_by_lua_block {
            if ngx.req.is_internal() == false then 
                require("datadome_openresty").validateRequest()
            end
        }
    }
    
    # ...
}

Note: Using ngx.req.is_internal() avoids sending requests to DataDome when the calls are internal.

Reload OpenResty.
The command below will gracefully reload the configuration and apply any changes while serving existing connections.

sudo service openresty reload

Settings

Setting	Description	Required	Default Value
datadome_server_side_key	Your DataDome server side key, found in your dashboard	yes	-
datadome_endpoint	Host of the API Server Available endpoints	no	`api.datadome.co`
datadome_timeout	Timeout for regular API calls	no	`150` (in milliseconds)
datadome_url_pattern_inclusion	Regular expression to include URLs	no	-
datadome_url_pattern_exclusion	Regular expression to exclude URLs	no	List of excluded static assets below
datadome_enable_graphql_support	Boolean to enable GraphQL support - See How can I enable GraphQL support?	no	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|json)$"

Settings example:


http {
    # ...

    # DataDome configuration
    resolver 8.8.8.8;
    init_by_lua_block {
        require("datadome_openresty").setDatadomeConf(
            {
            datadome_server_side_key = "server_side_key",
            datadome_endpoint = "api-eu-france-1.datadome.co",
            datadome_timeout = "200",
            datadome_url_pattern_inclusion = "",
            datadome_url_pattern_exclusion = "\\.(myextension|otherextension|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|json)$",
            }
        )
    }

    #....
}

FAQ

Do you provide a demo?

We provide a Dockerfile with the set up and the configuration to help you to integrate DataDome.

How do I activate debug logs?

The debug level allows you to get DataDome verbose mode.

To activate the debug level, make sure you have an error_log on debug mode on your nginx.conf file

error_log  logs/error.log  debug;

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.
You can find more information here.

Below you can find a simple example based on the official OpenResty page for req.get_headers()

access_by_lua_block {
  if ngx.req.is_internal() == false then 
    require("datadome_openresty").validateRequest()
  end
}

-- LOG PHASE
log_by_lua_block {
  ngx.log(ngx.DEBUG,"X-DataDome-isbot: ", ngx.req.get_headers()["X-DataDome-isbot"])
}

How can I enable GraphQL support?

Starting with version 1.3.0 of DataDome OpenResty module, it is possible to enable GraphQL support:

Add datadome_enable_graphql_support and set it to true inside nginx.conf:

http {
    # ...

    # DataDome configuration
    resolver 8.8.8.8;
    init_by_lua_block {
        require("datadome_openresty").setDatadomeConf(
            {
            datadome_server_side_key = "server_side_key",
            datadome_enable_graphql_support = true,  
            }
        )
    }