Java configuration options

Your HUMAN Application ID in the form of PX12AB34CD. You can copy this value from the HUMAN Console in Platform Settings > Applications Overview. If you have multiple applications, make sure to copy the ID of the application you want the Enforcer on.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .appId("APP_ID")
4
  // ...

The application’s server token needed to authorize with HUMAN’s backend. You can copy this value from the HUMAN Console in Platform Settings > Applications Overview > Click the appropriate application > Server token tab.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .authToken("AUTH_TOKEN")
4
  // ...

The secret used to encrypt and decrypt the risk cookie sent from the HUMAN Sensor. You can copy this value from the HUMAN Console in Sightline Cyberfraud Defense > Traffic Policy Overview > Click the appropriate application > Click the key > Copy value.

If you need to rotate secrets, then adjust this configuration to be an array of strings (string[]) and include the new secret and old secret. The new secret value should be the first value in the array. This prevents decryption failures.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .cookieKey("COOKIE_KEY")
4
  // ...

The total time in milliseconds that the Enforcer will wait for the Risk API request to return before timing out and passing the request.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .apiTimeout(2000)
4
  // ...

The minimum risk score that the Enforcer will block. Ranges from 0 (lowest risk) to 100 (highest risk).

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .blockingScore(20)
4
  // ...

The severity at which the logger will output logs.

• LoggerSeverity.NONE: The logger will not generate any logs.
• LoggerSeverity.ERROR: The logger will only generate logs on fatal errors.
• LoggerSeverity.DEBUG: The logger will generate detailed logs for debugging purposes. Not recommended for production environments.

See px_logger_auth_token for a header-based alternative.

The Java Enforcer uses SLF4J and Logback for logging.

1
import com.perimeterx.models.configuration.PXConfiguration;
2
import com.perimeterx.utils.logger.LoggerSeverity;
3
4
PXConfiguration.setPxLoggerSeverity(LoggerSeverity.DEBUG); // Can be called once; you do not need to call it on every request.

An array of header names that are trusted to contain the true client IP. Headers are traversed in the order they’re listed, and the first header value will always be used as the client IP.

If not set, will be taken from default.

Use with the CombinedIPProvider interface.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .ipHeaders(new HashSet<>(Arrays.asList("x-px-true-ip", "x-true-ip")))
4
  // ...

Whether the Enforcer module is enabled.

• true: Enable the module
• false: Disable the module

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .moduleEnabled(false)
4
  // ...

The Enforcer’s operation mode.

• ModuleMode.MONITOR: The Enforcer performs all functions without returning block responses. Useful for analyzing and adjusting Enforcer behavior without serving block pages to end users. If you have routes that must have enforcement at all times, see Enforced routes.
• ModuleMode.BLOCKING: The Enforcer will return block responses as needed.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .moduleMode(ModuleMode.BLOCKING)
4
  // ...

In specific cases such as XHR post requests, a full CAPTCHA page render might not be an option. In such cases, the Advanced Blocking Response (ABR) returns a JSON object containing all the information needed to render a customized CAPTCHA challenge implementation such as a popup modal, a section on the page, etc. This provides more flexibility and customizability in displaying the CAPTCHA challenge.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .advancedBlockingResponse(false)
4
  // ...
5
  .build();

Activates the full blocking flow to verify the flow works as expected if a particular header is present on the request. Often used during monitor mode, where the Enforcer collects data without blocking user requests, before switching to ModuleMode.BLOCKING.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .bypassMonitorHeader("x-px-block")
4
  // ...
5
  .build();

Whether to enable the extraction and reporting of credentials from the Enforcer for Credential Intelligence.

• true: Enable Credential Intelligence
• false: Disable Credential Intelligence

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .loginCredentialsExtractionEnabled(true)
4
  // ...
5
  .build();

An array of configuration objects for each credential endpoint. Each element in the array is an object representing a distinct endpoint to which credentials are sent and includes:

• How to identify these credential-bearing requests
• How to extract the credentials from the request
• How to determine if the request operation (login, signup, etc.) was successful based on the returned HTTP response

1
PXConfiguration pxConf = new PXConfiguration.Builder()
2
  // ...
3
  .loginCredentialsExtractionDetails(ciLoginMap)
4
  // ...
5
  .build();

Determines the structure and content of the user login data.

1
PXConfiguration pxConf = new PXConfiguration.Builder()
2
  // ...
3
  .ciProtocol(CIProtocol)
4
  // ...
5
  .build();

The header name to be set on the incoming request if the credentials are compromised. If this header is added, its value will always be 1. If credentials have not been identified as compromised, the header will not be added to the request.

1
PXConfiguration pxConf = new PXConfiguration.Builder()
2
  // ...
3
  .pxCompromisedCredentialsHeader("x-px-compromised-credentials")
4
  // ...
5
  .build();

Whether to attach the additional_s2s payload and URL as headers to the original request. This is done so that the additional_s2s activity can be enriched with the proper login_successful value and sent to the provided URL at a later stage. This disables automatically sending additional_s2s activities.

When set to true, the following headers are added to the origin request:

• px-additional-activity: A JSON object containing the payload of the additional_s2s activity. The login_successful and http_status_code fields should be set prior to sending the activity.

1
{
2
  "type": "additional_s2s",
3
  "timestamp": 1637000000,
4
  "socket_ip": "1.1.1.1",
5
  "px_app_id": "PX_APP_ID",
6
  "url": "https://www.example.com/the-target-url",
7
  "vid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
8
  "details": {
9
    "client_uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
10
    "request_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
11
    "ci_version": "v1",
12
    "http_status_code": null, // MODIFY, number (e.g., 200, 401, 404, etc.)
13
    "login_successful": null, // MODIFY, boolean (e.g., true, false)
14
    "raw_username": null // MODIFY, string (e.g., "test@mail.com")
15
  }
16
}

• px-additional-activity-url: The URL to which the additional_s2s payload should be sent as an HTTP POST request.

1
private boolean additionalS2SActivityHeaderEnabled = true;

Whether to report the raw username on the additional_s2s activity.

• false: The raw username will never be reported.
• true: The raw username will only be reported if:
  • The credentials are compromised, and
  • The login request was successful.

1
private boolean addRawUsernameOnAdditionalS2SActivity = true;

Method name that determines how to validate if the login was successful. There are several ways to report the success or failure of the login attempt. If left empty, the login success status is always reported as false.

1
private int[] loginResponseValidationStatusCode = {200};

1
private String headerNameToValidateLoginResponse = "x-px-login-successful";
2
private String headerValueToValidateLoginResponse = "1";

1
private String regexPatternToValidateLoginResponseBody = "You logged in successfully!" // string or RegExp

1
public class DefaultCustomLoginResponseValidator implements LoginResponseValidator {
2
3
    @Override
4
    public boolean isSuccessfulLogin(HttpServletResponseWrapper response) {
5
        return false;
6
    }
7
}

1
private LoginResponseValidationReportingMethod loginResponseValidationReportingMethod = LoginResponseValidationReportingMethod.STATUS

Regex pattern that checks the response body in order to validate successful login.

1
PXConfiguration pxConf = new PXConfiguration.Builder()
2
  // ...
3
  .loginResponseValidationRegexBody("You logged in successfully!")
4
  // ...
5
  .build();

Header name used to validate whether the login is successful.

1
PXConfiguration pxConf = new PXConfiguration.Builder()
2
  // ...
3
  .headerNameToValidateLoginResponse("x-px-login-successful")
4
  // ...
5
  .build();

Header value used to validate whether the login is successful.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .headerValueToValidateLoginResponse("ok")
4
  // ...
5
  .build();

Array of status codes used to validate whether the login was successful.

1
PXConfiguration pxConf = new PXConfiguration.Builder()
2
  // ...
3
  .loginResponseValidationStatusCode(new int[] { 200, 201 })
4
  // ...
5
  .build();

By default, the Enforcer extracts HUMAN cookies from the Cookie header. However, if these cookies are transferred on a different header, then that header’s name must be provided with this configuration.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .customCookieHeader("x-custom-cookies")
4
  // ...
5
  .build();

Enriches activities sent from the Enforcer to HUMAN with additional custom parameters. This data can include user information, session IDs, or other data that HUMAN should have access to. These custom parameters are defined by a configurable function that must return an object that contains these custom parameters. There is a limit of 10 custom parameters.

Parameters:

• config: HumanSecurityConfiguration
• request: HttpServletRequest

Returns: Promise<CustomParameters>

1
PXConfiguration pxConfiguration = PXConfiguration.builder()
2
     ...
3
     .customParametersExtraction((req) -> {
4
          CustomParameters customParameters = new CustomParameters();
5
          customParameters.setCustomParam1("example-value");
6
          customParameters.setCustomParam2(req.getHeader("example-header"));
7
          customParameters.setCustomParam3(123);  // Numbers are supported
8
          customParameters.setCustomParam4(true); // Booleans are supported
9
          return customParameters;
10
        })
11
     .build();

Whether to use the proxyHost for message forwarding.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .useProxy(true)
4
  // ...
5
  .build();

If your architecture requires the use of a proxy server to access outside services, you can designate a proxy URL or IP port to use. This will use HTTP tunneling and direct all outgoing HUMAN traffic to the defined proxy address.

Required if useProxy is true.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .proxyHost("proxy.example.com")
4
  // ...
5
  .build();

The proxy’s port. Required if useProxy is true.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .proxyPort(8080)
4
  // ...
5
  .build();

Whether to decode or decrypt a cookie.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .encryptionEnabled(false)
4
  // ...
5
  .build();

Sets the number of activities to send in batched activities.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .maxBufferLen(20)
4
  // ...
5
  .build();

Filters out requests with the specified file extension. By default, HUMAN doesn’t enforce static assets such as images and documents to minimize unncessary API calls and computation, but you can configure this list at any time.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .staticFilesExt(new HashSet<>(Arrays.asList("css", "js", "png")))
4
  // ...
5
  .build();

Adds a header to the incoming request with the configured header name and the JSON-stringified data enrichment object as the value. If empty or if data enrichment has not been enabled for your policy, no header will be set. To view available data and enable this feature, see Data classification enrichment.

1
PXConfiguration config = new PXConfiguration.Builder()
2
     ...
3
     .pxDataEnrichmentHeaderName("X-PX-Data-Enrichment")
4
     .build();
5
PerimeterX enforcer = new PerimeterX(config);
6
7
// In your filter:
8
PXContext ctx = enforcer.pxVerify(request, response);
9
10
// After pxVerify, the request now contains the data enrichment header
11
// and can be forwarded to your backend/origin server
12
// The header will be available as "X-PX-Data-Enrichment" in the request
13
filterChain.doFilter(request, response);

A way to include a custom CSS file to the block page.

Maps to {{cssRef}} in the block page template.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .cssRef("https://www.example.com/custom_style.css")
4
  // ...
5
  .build();

A way to include custom JavaScript to the block page. This script will run after the default JavaScript scripts.

Maps to {{jsRef}} in the block page template.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .jsRef("https://www.example.com/custom_script.js")
4
  // ...
5
  .build();

Adds a custom logo to the HUMAN Challenge block page via URL.

Maps to {{customLogo}} in the block page template.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .customLogo("https://www.example.com/custom_logo.png")
4
  // ...
5
  .build();

An array of routes or prefixes that should be enforced by HUMAN even when the Enforcer is in monitor mode.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .enforcedRoutes(new HashSet<>(Arrays.asList("/checkout", "/api/payment")))
4
  // ...
5
  .build();

A list of endpoints to be monitored rather than blocked by the Enforcer, even when the Enforcer is in ModuleMode.BLOCKING mode.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .monitoredRoutes(new HashSet<>(Arrays.asList("/status", "/health")))
4
  // ...
5
  .build();

TCP connection timeout to HUMAN servers, in milliseconds.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .connectionTimeout(2000)
4
  // ...
5
  .build();

The maximum connections per route for Risk API requests in the connections pool.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .maxConnectionsPerRoute(100)
4
  // ...
5
  .build();

The total maximum connections for Risk API client.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .maxConnections(300)
4
  // ...
5
  .build();

Toggle sending asynchronous page activities.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .sendPageActivities(false)
4
  // ...
5
  .build();

Set the base url for HUMAN servers

1
PXConfiguration pxConf = new PXConfiguration.Builder()
2
  // ...
3
  .serverUrl("https://custom-collector.example.com")
4
  // ...
5
  .build();

The PX Hashed Data (PXHD) cookie links the first risk request with the browser activities as detected by the Sensor for better user tracking. It can also add more information that’s shared between the HUMAN Collector, Enforcer, and Sensor. This configuration determines whether the Secure cookie attribute is added when setting the PXHD cookie.

See Use of cookies & web storage for more information.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .securedPxhdEnabled(true)
4
  // ...
5
  .build();

An alternative to the basic logger configuration. This sends Enforcer logs to HUMAN’s logging service if a specific header is present on the request. This is particularly useful for expedited debugging, diagnosis, and resolution of any integration or Enforcer-related issues.

Contact HUMAN to recieve your token.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .loggerAuthToken("LOGGER_AUTH_TOKEN")
4
  // ...
5
  .build();

The interval time in milliseconds to wait between attempts to fetch the Remote Configuration.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .remoteConfigurationInterval(15000)
4
  // ...
5
  .build();

The amount of time to delay the remote configuration thread before it starts

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .remoteConfigurationDelay(1000)
4
  // ...
5
  .build();

Set the URL for HUMAN configuration service

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .remoteConfigurationUrl("https://configurations.perimeterx.net")
4
  // ...
5
  .build();

Interval in seconds of cleaning requests queue. Solves HttpComponent reference leak bug.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .validateRequestQueueInterval(10)
4
  // ...
5
  .build();

Specifies certain headers that should not be forwarded to any other destination, including the HUMAN Detector. While HUMAN’s detection system will continue to use these headers to determine whether to block or not, the specified headers won’t be forwarded from the Enforcer, won’t appear in Enforcer activities, and won’t be sent to any other IP if the Enforcer acts as a proxy.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .sensitiveHeaders(new HashSet<>(Arrays.asList("cookie", "authorization")))
4
  // ...
5
  .build();

A list of prefixes for all routes that should be considered sensitive.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .sensitiveRoutes(new HashSet<>(Arrays.asList("/login", "/checkout")))
4
  // ...
5
  .build();

Regex strings for routes that should be considered sensitive.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .sensitiveRoutesRegex(new HashSet<>(Arrays.asList("^/api/login$", "^/api/users/.*/password$")))
4
  // ...
5
  .build();

A custom function that lets you define which requests should be considered sensitive based on custom logic. It accepts the incoming request as an argument and returns a boolean indicating whether the request should be considered sensitive.

Parameters:

• request: function

Returns: A boolean or a Promise resolving to a boolean.

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

Runs the Enforcer in a development environment for testing purposes. The response returns as a JSON object. When you run the Enforcer in testing mode, do not set a custom verification handler

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .testingMode(true)
4
  // ...
5
  .build();

The name of the cookie that contains the JWT token that HUMAN should extract user identifiers from.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .pxJwtCookieName("auth")
4
  // ...
5
  .build();

The field name in the JWT object, extracted from the JWT cookie, that contains the user ID to be extracted and reported.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .pxJwtCookieUserIdFieldName("nameID")
4
  // ...
5
  .build();

The field names in the JWT object, extracted from the JWT cookie, that should be extracted and reported in addition to the user ID.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .pxJwtCookieAdditionalFieldNames(Arrays.asList("exp", "iss"))
4
  // ...
5
  .build();

The name of the header that contains the JWT token that HUMAN should extract user identifiers from.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .pxJwtHeaderName("x-jwt-authorization")
4
  // ...
5
  .build();

The field name in the JWT object, extracted from the JWT header, that contains the user ID to be extracted and reported.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .pxJwtHeaderUserIdFieldName("sub")
4
  // ...
5
  .build();

The field names in the JWT object, extracted from the JWT header, that should be extracted and reported in addition to the user ID.

1
PXConfiguration pxConf = PXConfiguration.builder()
2
  // ...
3
  .pxJwtHeaderAdditionalFieldNames(Arrays.asList("exp", "iss"))
4
  // ...
5
  .build();

Handler for all asynchronous activities from type enforcer_telemetry, page_requested, and block.

• Method: setActivityHandler

Blocking handle will be called when pxVerify will return that user is not verified.

• Method: blockHandler

Handles IP address extraction from request.

• Method: setIpProvider

Handles hostname extraction from request.

• Method: setHostnameProvider

Handling verification after HUMAN service finished analyzing the request.

• Method: setVerificationHandler

Adds to all activities additional custom parameters.

• Method: customParametersProvider

Validate if the Login response was successful.

• Method: isSuccessfulLogin

Extract credentials from login request.

• Method: extractCredentials