PerimeterX Java SDK

Latest stable version: v6.14.0

Table of Contents

• Usage
  • Prerequisites
  • Installation
  • Upgrading
• Basic Usage Example
• Advanced Usage Examples
  • Data Enrichment
  • Custom Parameters
  • Custom Sensitive Request
  • Multiple Application Support
• Configuration
• Logging and Troubleshooting
• Contributing
• Additional Information

Prerequisites

JDK:

Use jdk 1.7 or higher.

Unlimited Strength Jurisdiction Policy:

Make sure your JDK supports unlimited key length.

If the SDK is throwing Unlimited Strength Jurisdiction Policy assertion errors on startup, follow the instructions below:

1. Download JCE for jdk17 or for jdk18.
2. Replace local_policy.jar and US_export_policy.jar in your $JAVA_HOME/jre/lib/security/ with those you have downloaded.
3. Run your project again and the Unlimited Strength Jurisdiction Policy error should no appear.

Installation

Maven:

• Add perimeterx-sdk to pom.xml:

<dependency>
   <groupId>com.perimeterx</groupId>
   <artifactId>perimeterx-sdk</artifactId>
   <version>${VERSION}</version>
</dependency>

gradle:

• Add perimeterx-sdk to your build.gradle:

compile group: 'com.perimeterx', name: 'perimeterx-sdk', version: '${VERSION}'

Upgrading

SDK > v4.x

To upgrade to the latest Enforcer version, run:

mvn versions:display-dependency-updates

Open the project’s pom.xml and change the version number to the latest version.

Your Enforcer version is now upgraded to the latest enforcer version.

SDK < v4.x

The PXContext on SDK v4.x has changed, following these changes, the implementation of PerimeterX SDK on the java filter must be changed accordingly.

PerimeterX SDK reports now if handled the response instead of reporting if request was verified (using ctx.isVerified()) instead, its PXContext expose the following methods: ctx.isHandledResponse().

isVerified() is deprecated and from now on, use isRequestLowScore()

isHandledResponse() will return true in the following cases

1. Request is blocked and PerimeterX handled the response by rendering a block page (because score was high)
2. Response was handled by first party mechanism (not score related).

• More information about First Party can be found in the configurations page

Following the instructions above, the filter should be changed according the the example below

  // Verify the request
  PXContext ctx = enforcer.pxVerify(req, new HttpServletResponseWrapper(resp);

  // Notice that isVerified() changed to isHandledResponse()
  if (ctx != null && ctx.isHandledResponse()) {

     // Optional: check why response was handled
     if (ctx.isFirstPartyRequest()) {
       System.out.println("Incoming request was first party request");
     }

     if (!ctx.isRequestLowScore()) {
       System.out.println("Request score was higher than threshold");
     }

    // Must return and not continue to filterChain.doFilter
    return;

 }

 filterChain.doFilter(servletRequest, servletResponse);

Once the filter is changed, follow the instructions above.

For more information, contact PerimeterX Support.

Basic Usage Example

// Create configuration object
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
     .cookieKey(COOKIE_KEY)
     .authToken(AUTH_TOKEN)
     .appId(APP_ID)
     .blockingScore(SCORE)
     .moduleMode(ModuleMode.BLOCKING)
     .build();

// Get instance
PerimeterX enforcer = new PerimeterX(pxConfiguration);

// Inside the request / Filter
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOExcption {
...
    PXContext ctx = enforcer.pxVerify(req, new HttpServletResponseWrapper(resp);
    if (ctx != null && !ctx.isHandledResponse()) {
       // request should be blocked and BlockHandler was triggered on HttpServerResponseWrapper
    }
...
}

Please continue reading about the various configurations available on the sdk in the configurations page .

Advanced Usage Examples

Data Enrichment - pxde(PerimeterX Data Enrichment)

Users can use the additional activity handler to retrieve information for the request using the pxde object. First, check that the data enrichment object is verified, then you can access it's properties.

MyVerificationHandler.java:

...
public class MyVerificationHandler implements VerificationHandler {
    PXConfiguration pxConfig;
    VerificationHandler defaultVerificationHandler;

    public AutomationVerificationHandler(PXConfiguration pxConfig) throws PXException {
        this.pxConfig = pxConfig;
        PXClient pxClient = new PXHttpClient(pxConfig);
        ActivityHandler activityHandler = new DefaultActivityHandler(pxClient, pxConfig);
        this.defaultVerificationHandler = new DefaultVerificationHandler(pxConfig, activityHandler);
    }

    public boolean handleVerification(PXContext pxContext, HttpServletResponseWrapper httpServletResponseWrapper) throws PXException, IOException {
        if (pxContext.isPxdeVerified()) {
            JsonNode dataEnrichmentPayload = pxContext.getPxde();
            <handle data enrichment payload here>
        }

        return defaultVerificationHandler.handleVerification(pxContext, httpServletResponseWrapper);
    }
}

Then, in your filter:

...
PXConfiguration config = new PXConfiguration.Builder()
     ...
     .build();
PerimeterX enforcer = new PerimeterX(config);
enforcer.setVerificationHandler(new MyVerificationHandler(config));
...

Custom Sensitive Request

With the customIsSensitive predicate you can force the request to be sensitive. The input of the function is the same request that sent to the method pxVerify. If the function throws exception, it is equivalent to returning false. Implementing this configuration does NOT override other sensitive configurations, like sensitive_routes.

Note The request body can only be read once by default. If your function requires reading the body consider using RequestWrapper which caches the body. Send the wrapped request to pxVerify instead of the native one.

In your filter:

...
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
        ...
        .customIsSensitiveRequest((req) -> req.getHeader("example-header") == "example-value")
        .build();

Custom Parameters

With the customParametersExtraction function you can add up to 10 custom parameters to be sent back to PerimeterX servers. When set, the function is called before setting the payload on every request to PerimetrX servers. The input of the function is the same request that sent to the method pxVerify. If the function throws exception, it is equivalent to returning empty custom params. Implementing this configuration overrides the deprecated configuration customParameterProvider.

Note The request body can only be read once by default. If your function requires reading the body consider using RequestWrapper which caches the body. Send the wrapped request to pxVerify instead of the native one.

In your filter:

...
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
     ...
     .customParametersExtraction((req) -> {
          CustomParameters customParameters = new CustomParameters();
          customParameters.setCustomParam1("example-value");
          customParameters.setCustomParam2(req.getHeader("example-header"));
          return customParameters;
        })
     .build();
...

Multiple Application Support

Simply create multiple instances of the PerimeterX class:

PerimeterX enforcerApp1 = new PerimeterX(new PXConfiguration.Builder().appId(APP_ID_1)...build(););
PerimeterX enforcerApp2 = new PerimeterX(new PXConfiguration.Builder().appId(APP_ID_2)...build(););

...

// Inside route request handler for app 1:
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOExcption {
    PXContext ctx = enforcerApp1.px(req, new HttpServletResponseWrapper(resp);
    ...
}

...

// Inside route request handler for app 2:
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOExcption {
    PXContext ctx = enforcerApp2.pxVerify(req, new HttpServletResponseWrapper(resp);
    if(ctx != null) {
      ...
    }
}

Logging and Troubleshooting

perimeterx-java-sdk is using SLF4J and Logback for logs.

For further information please visit SLF4J and Logback.

If you wish to use a basic logger which uses System.out and System.err to print debug and error accordingly, Change the value of the static variable to your desired level.

import com.perimeterx.models.configuration.PXConfiguration;
import com.perimeterx.utils.LoggerSeverity;

PXConfiguration.setPxLoggerSeverity(LoggerSeverity.DEBUG);

Note This method can be executed once, no need to execute it every request.

---

The following steps are welcome when contributing to our project.

Fork/Clone

First and foremost, Create a fork of the repository, and clone it locally. Create a branch on your fork, preferably using a self descriptive branch name.

Code/Run

Code your way out of your mess, and help improve our project by implementing missing features, adding capabilities or fixing bugs.

To run the code, simply follow the steps in the installation guide. Grab the keys from the PerimeterX Portal, and try refreshing your page several times continuously. If no default behaviors have been overriden, you should see the PerimeterX block page. Solve the CAPTCHA to clean yourself and start fresh again.

Pull Request

After you have completed the process, create a pull request to the Upstream repository. Please provide a complete and thorough description explaining the changes. Remember this code has to be read by our maintainers, so keep it simple, smart and accurate.

Additional Information

URI Delimiters

PerimeterX processes URI paths with general- and sub-delimiters according to RFC 3986. General delimiters (e.g., ?, #) are used to separate parts of the URI. Sub-delimiters (e.g., $, &) are not used to split the URI as they are considered valid characters in the URI path.

Thanks