Enforcer frameworksJava

Installation

You can learn how to install the Java Enforcer with this article.

The Java Enforcer is published as two Maven artifacts. Both share the same version number and public API (com.perimeterx.*); choose the artifact that matches your servlet namespace and application server.

ArtifactServlet APIUse when
perimeterx-sdkjavax.servlet (Java EE 8)Spring Boot 2.x, Tomcat 9 and earlier
perimeterx-sdk-jakartajakarta.servlet (Jakarta EE 9+)Spring Boot 3.x, Tomcat 10+

Prerequisites

  • JDK: There are different JDK requirements depending on the artifact:
    • perimeterx-sdk (javax): JDK 1.7 or higher
    • perimeterx-sdk-jakarta: JDK 17 or higher (required by Jakarta Servlet 6/Spring Boot 3).
  • If you are using a Java version earlier than 8u161, you may need to install the JCE Unlimited Strength Policy files to enable unlimited strength cryptography. If you don’t do this, you may see Unlimited Strength Jurisdiction Policy errors on startup. This is enabled by default in Java version 9 and later.
  • Your unique HUMAN information:
    • Your Application ID. You can find this under Platform Settings > Applications > Overview in the HUMAN console. If you have multiple environments, you will also have multiple Application IDs, so be sure to choose the correct ID for the environment you want to install on.
    • Your Server Token. You can find this under Platform Settings > Applications, then selecting an application and navigating to Application settings > Server token.
    • Your Risk Cookie Key. You can find this under Bot Defender > Policies > Policy Settings > Policy Information.

Installation

Use this artifact for Spring Boot 2.x, Tomcat 9 and earlier, and other stacks that still use the javax.servlet namespace.

1

Add the SDK dependency

Add the following dependency to your pom.xml or build.gradle file:

1<!-- Add perimeterx-sdk to pom.xml -->
2<dependency>
3   <groupId>com.perimeterx</groupId>
4   <artifactId>perimeterx-sdk</artifactId>
5   <version>${VERSION}</version>
6</dependency>
2

Integrate the Enforcer as a Servlet Filter

Create a filter that intercepts all incoming requests and verifies them with HUMAN. Be sure to include your HUMAN Application ID, Server Token, and Cookie Key.

You only need to include the responseWrapper section found at the end of the code example if you use Credentials Intelligence.

Integration example
1import com.perimeterx.api.PerimeterX;
2import com.perimeterx.http.RequestWrapper;
3import com.perimeterx.http.ResponseWrapper;
4import com.perimeterx.models.PXContext;
5import com.perimeterx.models.configuration.ModuleMode;
6import com.perimeterx.models.configuration.PXConfiguration;
7import com.perimeterx.models.exceptions.PXException;
8import javax.servlet.*;
9import javax.servlet.annotation.WebFilter;
10import javax.servlet.http.HttpServletRequest;
11import javax.servlet.http.HttpServletResponse;
12import javax.servlet.http.HttpServletResponseWrapper;
13import java.io.IOException;
14
15@WebFilter("/*")
16public class HumanFilter implements Filter {
17   private PerimeterX enforcer;
18   @Override
19   public void init(FilterConfig filterConfig) throws ServletException {
20         try {
21            PXConfiguration config = PXConfiguration.builder()
22                    .appId("<APP_ID>") // replace with your HUMAN Application ID
23                    .cookieKey("<COOKIE_KEY>") // replace with your HUMAN Cookie Key
24                    .authToken("<AUTH_TOKEN>") // replace with your HUMAN Server Token
25                    .moduleMode(ModuleMode.BLOCKING)
26                    .build();
27            this.enforcer = new PerimeterX(config);
28         } catch (PXException e) {
29            throw new ServletException("Failed to initialize HUMAN Enforcer", e);
30         }
31   }
32   @Override
33   public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse,
34                        FilterChain filterChain) throws IOException, ServletException {
35         HttpServletRequest req = (HttpServletRequest) servletRequest;
36         HttpServletResponse resp = (HttpServletResponse) servletResponse;
37
38         try {
39         // Wrap the request to allow reading the body multiple times
40         req = new RequestWrapper(req);
41         // Verify the request with HUMAN
42         PXContext ctx = enforcer.pxVerify(req, new HttpServletResponseWrapper(resp));
43  
44         // Block or First Party
45         if (ctx != null && ctx.isHandledResponse()) {
46              return;
47         }
48  
49         // Pass request
50         filterChain.doFilter(req, resp);
51          
52         // Post-verify for login response validation (Credentials Intelligence)
53         ResponseWrapper responseWrapper = new ResponseWrapper(resp);
54         enforcer.pxPostVerify(responseWrapper, ctx);
55         } catch (Exception e) {
56            // Fail open in case of Exception
57            filterChain.doFilter(servletRequest, servletResponse);
58         }
59   }
60}