Java/Tomcat-Jetty
How to install the Java Module
With Maven
Update your pom.xml file with the following content:
<project>
...
<dependencies>
...
<dependency>
<groupId>co.datadome.module</groupId>
<artifactId>datadome-java-module</artifactId>
<version>1.18.0</version>
</dependency>
...
</dependencies>
...
</project>
Manual Installation
- Download and extract the archive:
wget https://package.datadome.co/linux/DataDome-Java-latest.tgz
tar zxvf DataDome-Java-latest.tgz
- The downloaded archive includes sources, so you can directly install it to your local Maven repository.
By default it is built with servlet-api-3.1
. If your installation is dependant on servlet-api-3.0
or servlet-api-4.0
, you need to build it manually with a different profile:
cd DataDome-JavaModuleDome-*
mvn install
cd DataDome-JavaModuleDome-*
mvn -P servlet-api-3.0 install
- Copy the target/datadome-java-module-xx.jar file to the server lib directory, similarly to the below:
/lib
Usage
The filter has been tested on Jetty, Tomcat and should work with Jboss as well as other servers supporting Servlet API.
Tomcat 8 or earlier
If you're using Tomcat (version 8 or earlier) as Java Servlet Container for your java application you should set the following Tomcat system property to true to enable the DataDome JAVA module to 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 a 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 earlier) uses legacy cookie processor (LegacyCookieProcessor) which implements a strict interpretation of the cookie specifications. Due to various interoperability issues with browsers, not all strict behaviors are enabled by default.
Refer to https://tomcat.apache.org/tomcat-8.0-doc/config/cookie-processor.html
Starting from version 9, Tomcat uses a more lenient cookie parser than the legacy one (Rfc6265CookieProcessor) by default. In particular:
- The '=' and '/' characters are always permitted in a cookie value.
Refer to https://tomcat.apache.org/tomcat-9.0-doc/config/cookie-processor.html
To use the filter you need to add it to web.xml as first server.
Example:
<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 specify additional parameters likes hostname or timeout.
List of possible init parameters:
Settings | Description | Default |
---|---|---|
datadome.apikey | License key to access API | |
datadome.hostname | API server's hostname Available endpoints | 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 connections to the API server | 100 |
datadome.proxy_server | Host that will be used as proxy server See here | |
datadome.proxy_port | TCP port at the proxy server See here | |
datadome.proxy_ssl | Is the connection to the proxy established through TLS See here | false |
datadome.skip_ips | IPv4 or IPv6 subnetwork list on which datadome validation is not executed, e.g.: "2a03:2880:1000::/36,124.66.0.0/17" |
You can use environment variables inside the DataDome filter's param-value.
For example, if you have the system environment variable DATADOME_API_KEY with your API key, you can input it in web.xml
as follows:
<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?
The DataDome filter adds the 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, such as sending spent_time value to your monitoring system, etc.
Can DataDome API be called via outbound proxy?
The DataDome module can be used with outbound proxy. Two options are available for proxy configuration:
-
Use system settings such as
-Dhttp.proxyHost=1.2.3.4 -Dhttp.proxyPort=8080 -Dhttps.proxyHost=1.2.3.4 -Dhttps.proxyPort=8443
when running your java application. -
Use optional DataDome init parameters
datadome.proxy_server
,datadome.proxy_port
,datadome.proxy_ssl
in web.xml.
Note: using the DataDome module with outbound proxy can slow down the total time spent calling DataDome API and increase timeouts. Please adjust timeout settings accordingly.
Updated 3 months ago