> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# 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.

| Artifact                 | Servlet API                       | Use when                              |
| ------------------------ | --------------------------------- | ------------------------------------- |
| `perimeterx-sdk`         | `javax.servlet` (Java EE 8)       | Spring Boot 2.x, Tomcat 9 and earlier |
| `perimeterx-sdk-jakarta` | `jakarta.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](https://www.oracle.com/java/technologies/javase-jce-all-downloads.html) 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

#### Java EE (javax.servlet)

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

#### Add the SDK dependency

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

**`Maven`**

```xml title="Maven"
<!-- Add perimeterx-sdk to pom.xml -->
<dependency>
   <groupId>com.perimeterx</groupId>
   <artifactId>perimeterx-sdk</artifactId>
   <version>${VERSION}</version>
</dependency>
```

**`Gradle`**

```groovy title="Gradle"
// Add perimeterx-sdk to build.gradle
implementation 'com.perimeterx:perimeterx-sdk:${VERSION}'
```

#### 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.

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

#### Servlet version >= 3.0

**`Integration example`**

```java title="Integration example" {22-24, 54-58}
import com.perimeterx.api.PerimeterX;
import com.perimeterx.http.RequestWrapper;
import com.perimeterx.http.ResponseWrapper;
import com.perimeterx.models.PXContext;
import com.perimeterx.models.configuration.ModuleMode;
import com.perimeterx.models.configuration.PXConfiguration;
import com.perimeterx.models.exceptions.PXException;
import javax.servlet.*;
import javax.servlet.annotation.WebFilter;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpServletResponseWrapper;
import java.io.IOException;

@WebFilter("/*")
public class HumanFilter implements Filter {
   private PerimeterX enforcer;
   @Override
   public void init(FilterConfig filterConfig) throws ServletException {
         try {
            PXConfiguration config = PXConfiguration.builder()
                    .appId("<APP_ID>") // replace with your HUMAN Application ID
                    .cookieKey("<COOKIE_KEY>") // replace with your HUMAN Cookie Key
                    .authToken("<AUTH_TOKEN>") // replace with your HUMAN Server Token
                    .moduleMode(ModuleMode.BLOCKING)
                    .build();
            this.enforcer = new PerimeterX(config);
         } catch (PXException e) {
            throw new ServletException("Failed to initialize HUMAN Enforcer", e);
         }
   }
   @Override
   public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse,
                        FilterChain filterChain) throws IOException, ServletException {
         HttpServletRequest req = (HttpServletRequest) servletRequest;
         HttpServletResponse resp = (HttpServletResponse) servletResponse;

         try {
         // Wrap the request to allow reading the body multiple times
         req = new RequestWrapper(req);
         // Verify the request with HUMAN
         PXContext ctx = enforcer.pxVerify(req, new HttpServletResponseWrapper(resp));
  
         // Block or First Party
         if (ctx != null && ctx.isHandledResponse()) {
              return;
         }
  
         // Pass request
         filterChain.doFilter(req, resp);
          
         // Post-verify for login response validation (Credentials Intelligence)
         ResponseWrapper responseWrapper = new ResponseWrapper(resp);
         enforcer.pxPostVerify(responseWrapper, ctx);
         } catch (Exception e) {
            // Fail open in case of Exception
            filterChain.doFilter(servletRequest, servletResponse);
         }
   }
}           
```

#### Servlet version \< 3.0

If you're using a Servlet version less than 3.0, remove the `@WebFilter` annotation and add the filter to your `web.xml` file instead.

**`Integration example`**

```java title="Integration example" {9, 15, 22-24, 54-58}
import com.perimeterx.api.PerimeterX;
import com.perimeterx.http.RequestWrapper;
import com.perimeterx.http.ResponseWrapper;
import com.perimeterx.models.PXContext;
import com.perimeterx.models.configuration.ModuleMode;
import com.perimeterx.models.configuration.PXConfiguration;
import com.perimeterx.models.exceptions.PXException;
import javax.servlet.*;
// note WebFilter import removed
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpServletResponseWrapper;
import java.io.IOException;

// note @WebFilter removed
public class HumanFilter implements Filter {
   private PerimeterX enforcer;
   @Override
   public void init(FilterConfig filterConfig) throws ServletException {
         try {
            PXConfiguration config = PXConfiguration.builder()
                     .appId("<APP_ID>") // replace with your HUMAN Application ID
                     .cookieKey("<COOKIE_KEY>") // replace with your HUMAN Cookie Key
                     .authToken("<AUTH_TOKEN>") // replace with your HUMAN Server Token
                     .moduleMode(ModuleMode.BLOCKING)
                     .build();
               this.enforcer = new PerimeterX(config);
            } catch (PXException e) {
               throw new ServletException("Failed to initialize HUMAN Enforcer", e);
            }
         }
   @Override
   public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse,
                        FilterChain filterChain) throws IOException, ServletException {
         HttpServletRequest req = (HttpServletRequest) servletRequest;
         HttpServletResponse resp = (HttpServletResponse) servletResponse;

         try {
            // Wrap the request to allow reading the body multiple times
            req = new RequestWrapper(req);
            // Verify the request with HUMAN
            PXContext ctx = enforcer.pxVerify(req, new HttpServletResponseWrapper(resp));
   
            // Block or First Party
            if (ctx != null && ctx.isHandledResponse()) {
               return;
            }
   
            // Pass request
            filterChain.doFilter(req, resp);
            
            // Post-verify for login response validation (Credentials Intelligence only)
            ResponseWrapper responseWrapper = new ResponseWrapper(resp);
            enforcer.pxPostVerify(responseWrapper, ctx);
            } catch (Exception e) {
               // Fail open in case of Exception
               filterChain.doFilter(servletRequest, servletResponse);
            }
   }
}
```

**`web.xml filter`**

```xml title="web.xml filter"
<filter>
    <filter-name>HumanFilter</filter-name>
    <filter-class>com.yourapp.HumanFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>HumanFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
```

#### Jakarta EE (jakarta.servlet)

Use this artifact for Spring Boot 3.x, Tomcat 10+, and other stacks that use the `jakarta.servlet` namespace.

> **Note**
>
> Jakarta EE environments require Servlet 3.0 or later. Use the `@WebFilter` annotation or register the filter in `web.xml` with the Jakarta EE namespace.

#### Add the SDK dependency

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

**`Maven`**

```xml title="Maven"
<!-- Add perimeterx-sdk-jakarta to pom.xml -->
<dependency>
   <groupId>com.perimeterx</groupId>
   <artifactId>perimeterx-sdk-jakarta</artifactId>
   <version>${VERSION}</version>
</dependency>
```

**`Gradle`**

```groovy title="Gradle"
// Add perimeterx-sdk-jakarta to build.gradle
implementation 'com.perimeterx:perimeterx-sdk-jakarta:${VERSION}'
```

#### Integrate the Enforcer as a Servlet Filter

Create a filter that intercepts all incoming requests and verifies them with HUMAN. The integration logic is the same as the Java EE (javax) variant; use `jakarta.servlet.*` imports instead of `javax.servlet.*`.

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

**`Integration example`**

```java title="Integration example" {22-24, 54-58}
import com.perimeterx.api.PerimeterX;
import com.perimeterx.http.RequestWrapper;
import com.perimeterx.http.ResponseWrapper;
import com.perimeterx.models.PXContext;
import com.perimeterx.models.configuration.ModuleMode;
import com.perimeterx.models.configuration.PXConfiguration;
import com.perimeterx.models.exceptions.PXException;
import jakarta.servlet.*;
import jakarta.servlet.annotation.WebFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.servlet.http.HttpServletResponseWrapper;
import java.io.IOException;

@WebFilter("/*")
public class HumanFilter implements Filter {
   private PerimeterX enforcer;
   @Override
   public void init(FilterConfig filterConfig) throws ServletException {
         try {
            PXConfiguration config = PXConfiguration.builder()
                    .appId("<APP_ID>") // replace with your HUMAN Application ID
                    .cookieKey("<COOKIE_KEY>") // replace with your HUMAN Cookie Key
                    .authToken("<AUTH_TOKEN>") // replace with your HUMAN Server Token
                    .moduleMode(ModuleMode.BLOCKING)
                    .build();
            this.enforcer = new PerimeterX(config);
         } catch (PXException e) {
            throw new ServletException("Failed to initialize HUMAN Enforcer", e);
         }
   }
   @Override
   public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse,
                        FilterChain filterChain) throws IOException, ServletException {
         HttpServletRequest req = (HttpServletRequest) servletRequest;
         HttpServletResponse resp = (HttpServletResponse) servletResponse;

         try {
         // Wrap the request to allow reading the body multiple times
         req = new RequestWrapper(req);
         // Verify the request with HUMAN
         PXContext ctx = enforcer.pxVerify(req, new HttpServletResponseWrapper(resp));
  
         // Block or First Party
         if (ctx != null && ctx.isHandledResponse()) {
              return;
         }
  
         // Pass request
         filterChain.doFilter(req, resp);
          
         // Post-verify for login response validation (Credentials Intelligence)
         ResponseWrapper responseWrapper = new ResponseWrapper(resp);
         enforcer.pxPostVerify(responseWrapper, ctx);
         } catch (Exception e) {
            // Fail open in case of Exception
            filterChain.doFilter(servletRequest, servletResponse);
         }
   }
}           
```

If you prefer to register the filter in `web.xml` instead of using `@WebFilter`, use the Jakarta EE namespace:

**`web.xml filter (Jakarta EE)`**

```xml title="web.xml filter (Jakarta EE)"
<filter>
    <filter-name>HumanFilter</filter-name>
    <filter-class>com.yourapp.HumanFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>HumanFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
```