The DataDome Developer Hub

Welcome to the DataDome developer hub. You'll find comprehensive guides and documentation to help you start working with DataDome as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Java Module Setup

About

The DataDome Java Module is a custom servlet filter which intercepts the request and response and sends it to DataDome servers to detect bot traffic.

Installation

With Maven

<project>
...
    <repositories>
    ...
        <repository>
            <id>bintray-datadome-org-datadome</id>
            <name>DataDome bintray repo</name>
            <url>http://dl.bintray.com/datadome-org/datadome</url>
        </repository>
    ...
    </repositories>
    <dependencies>
    ...
        <dependency>
          <groupId>co.datadome.api</groupId>
          <artifactId>datadome-java-module</artifactId>
          <version>1.6</version>
        </dependency>
    ...
    </dependencies>
...
</project>

Manual Installation

  1. Download archive
https://package.datadome.co/linux/DataDome-Java-latest.tgz
  1. The downloaded zip file includes sources, so you can directly install it to your local maven repository:
    mvn install
    

By default it build with servlet-api-3.1 and if you're used application server with servlet-api-3.0
you should build it by hands with different profile:

mvn -P servlet-api-3.0 install

Usage

Filter has been tested on jetty, tomcat and should work with Jboss and other servers supporting servlet api.

Tomcat 8 or lower

If you're using Tomcat (version 8 or lower) as Java Servlet Container for your java application you should set
the following tomcat system property to true to make datadome JAVA module work properly:

org.apache.tomcat.util.http.ServerCookie.ALLOW_EQUALS_IN_VALUE=true

If this property is set to true Tomcat will allow '=' characters when parsing unquoted cookie values. If false, cookie values containing '=' will be terminated when the '=' is encountered.

To set system property in tomcat you can modify your tomcat start script and add new system property to JAVA_OPTS.

Example :

export LANG="en_US.UTF-8"
export JAVA_OPTS="$JAVA_OPTS -Duser.language=en -Duser.country=US -Dorg.apache.tomcat.util.http.ServerCookie.ALLOW_EQUALS_IN_VALUE=true"
export CATALINA_PID=${CATALINA_HOME}/temp/tomcat.pid
export CATALINA_OPTS="$CATALINA_OPTS  -Xmx${JAVA_MAXMEMORY}m -DjvmRoute=${TOMCAT_JVM_ROUTE}  -Dtomcat.maxThreads=${TOMCAT_MAXTHREADS}  -Dtomcat.minSpareThreads=${TOMCAT_MINSPARETHREADS}  -Dtomcat.httpTimeout=${TOMCAT_HTTPTIMEOUT}  -Djava.security.egd=file:/dev/./urandom"

Explanation :

Tomcat (version 8 or lower) uses legacy cookie processor (LegacyCookieProcessor) which implements a strict interpretation of the cookie specifications. Due to various interoperability issues with browsers not all strict behaviours are enabled by default.

See https://tomcat.apache.org/tomcat-8.0-doc/config/cookie-processor.html

Starting from version 9 Tomcat by default uses more lenient cookie parser than the legacy one (Rfc6265CookieProcessor). In particular:

  • The '=' and '/' characters are always permitted in a cookie value.

See https://tomcat.apache.org/tomcat-9.0-doc/config/cookie-processor.html

To use the filter you just need add it to web.xml as first server.

For eample:

<web-app>
...
    <filter>
        <filter-name>datadome-filter</filter-name>
        <filter-class>co.datadome.api.servlet.DataDomeFilter</filter-class>
        <init-param>
            <param-name>datadome.apikey</param-name>
            <param-value>YOUR_SECRET_LICENSE_KEY</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>datadome-filter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
...
</web-app>

You can also specified additional parametrs likes hostname or timeout.

List of possible init parametrs:

Settings Description Default
datadome.apikey License key to access API
datadome.hostname Hostname of API server api.datadome.co
datadome.ssl Use SSL between the filter and the API server true
datadome.regex Inclusion regex ""
datadome.exclusion_regex Exclusion regex \.(js|css|jpg|jpeg|png|ico|gif|tiff|svg|woff|woff2|ttf|eot|mp4|otf)$
datadome.connection_timeout Connection timeout (in ms) 150
datadome.read_timeout Read timeout (in ms) 50
datadome.max_connections Maximum open connection to the API server 100
datadome.proxy_server Host that will be used as proxy server
datadome.proxy_port TCP port at the proxy server
datadome.proxy_ssl Is the connection to proxy in TLS false

You can use environment variables inside DataDome filter's param-value.

For example if you have system environment variable DATADOME_API_KEY with your API key, you can put to web.xml:

        <init-param>
            <param-name>datadome.apikey</param-name>
            <param-value>${DATADOME_API_KEY}</param-value>
        </init-param>

FAQ

How can I log the time spent calling DataDome API?

DataDome filter adds attribute datadome.spent_time (number of milliseconds spent for
building request/getting response from DataDome API) so it could be easily retrieved inside your servlet.

Here is how you can use it:

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        resp.getWriter().println("Example servlet");
        System.out.println("Time spent by DataDome:" + req.getAttribute("datadome.spent_time"));
        resp.setStatus(200);
    }

Note : the above example is for demonstration purposes only.
Your use case could be different for example sending spent_time value to your monitoring system etc.

Can DataDome API be called via outbound proxy?

DataDome module can be used with outbound proxy. To configure proxy two options are available :

  • use system settings like -Dhttp.proxyHost=1.2.3.4 -Dhttp.proxyPort=8080 -Dhttps.proxyHost=1.2.3.4 -Dhttps.proxyPort=8443 when running you java application

  • use optional datadome init parameters datadome.proxy_server, datadome.proxy_port, datadome.proxy_ssl in web.xml

Note: using DataDome module with outbound proxy can slower total time spent calling DataDome API and increase timeouts. Please adjust timeout settings accordingly.

Java Module Setup