> 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. # Java configuration options Each Enforcer has a set of **configuration options** that control the Enforcer's functionality and features. While some are required, many of these are optional configurations that you can use to customize the Enforcer's behavior. You can reference available configurations with this article. The HUMAN Java Enforcer is configured with a `PXConfiguration` instance passed to the `PerimeterX` constructor (and related builder APIs). > **Note** > > While all Enforcers come with the same set of required configurations, the optional configurations available for each may differ. We recommend updating to the latest Enforcer version to ensure you have access to the latest features and configurations. ## Quick reference #### Basic functionality | Feature name | Key | Type | Default | Description | | :--------------------------------- | :-------------- | :------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------ | | [Application ID](#appId) | `appId` | String | `""` | HUMAN Application ID | | [Authentication token](#authToken) | `authToken` | String | `""` | HUMAN authentication token | | [Cookie secret](#cookieKey) | `cookieKey` | String | `""` | HUMAN cookie secret | | [S2S timeout](#apiTimeout) | `apiTimeout` | Integer | `1000` | Total time, in milliseconds, that the Enforcer will wait for the Risk API request to return before timing out and passing the request | | [Blocking score](#blockingScore) | `blockingScore` | Integer | `100` | 0-100. The minimum risk score that the Enforcer blocks from. | #### Basic features | Feature name | Key | Type | Default | Description | | :--------------------------------- | :------------------ | :--------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------- | | [Logger](#setLoggerSeverity) | `setLoggerSeverity` | String | `"error"` | The threshold above which logs on a particular event are received. | | [Client IP extraction](#ipHeaders) | `ipHeaders` | Array of strings | `[]` | Header names that are trusted to contain the true client IP. This is required when there are proxies between the Enforcer and your server. | | [Module enable](#moduleEnabled) | `moduleEnabled` | Boolean | `true` | Whether the HUMAN Enforcer module is enabled | | [Module mode](#moduleMode) | `moduleMode` | String | `"monitor"` | The HUMAN Enforcer's operation mode | #### Optional | Feature name | Key | Type | Default | Description | | :--------------------------------------------------------------------------------------- | :--------------------------------------- | :----------------------------------------------- | :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Advanced blocking response (ABR)](#advanced-blocking-response-abr) | `advancedBlockingResponse` | `boolean` | `true` | Enables JSON-based advanced blocking responses for supported requests. | | [Bypass monitor header](#bypass-monitor-header) | `bypassMonitorHeader` | `String` | `"x-px-block"` | Header name used to force blocking flow while in monitor mode. | | [Credentials Intelligence](#credentials-intelligence) | `loginCredentialsExtractionEnabled` | `boolean` | `false` | Enables Credentials Intelligence login-credentials extraction. | | [Credentials Intelligence](#credentials-intelligence) | `loginCredentialsExtractionDetails` | `CILoginMap` | `null` | Parsed route map describing where credentials are sent and how to extract them. | | [Credentials Intelligence](#credentials-intelligence) | `ciProtocol` | `CIProtocol` | `CIProtocol.V2` | Protocol version for Credentials Intelligence payloads. | | [Credentials Intelligence](#credentials-intelligence) | `pxCompromisedCredentialsHeader` | `String` | `"px-compromised-credentials"` | Header used to mark compromised credentials. | | [Credentials Intelligence](#credentials-intelligence) | `additionalS2SActivityHeaderEnabled` | `boolean` | `false` | Adds additional S2S payload headers to origin requests. | | [Credentials Intelligence](#credentials-intelligence) | `addRawUsernameOnAdditionalS2SActivity` | `boolean` | `false` | Sends raw username in additional S2S activity when enabled. | | [Credentials Intelligence](#credentials-intelligence) | `loginResponseValidationReportingMethod` | `LoginResponseValidationReportingMethod` | `null` | Strategy used to determine successful login responses. | | [Credentials Intelligence](#credentials-intelligence) | `loginResponseValidationRegexBody` | `String` | `null` | Regex for validating successful login by response body. | | [Credentials Intelligence](#credentials-intelligence) | `headerNameToValidateLoginResponse` | `String` | `"x-px-login-successful"` | Header used to validate successful login responses. | | [Credentials Intelligence](#credentials-intelligence) | `headerValueToValidateLoginResponse` | `String` | `"1"` | Header value used for successful-login validation. | | [Credentials Intelligence](#credentials-intelligence) | `loginResponseValidationStatusCode` | `int[]` | `{200}` | Status codes considered successful logins. | | [Custom cookie header](#custom-cookie-header) | `customCookieHeader` | `String` | `"x-px-cookies"` | Custom header name containing HUMAN cookies. | | [Custom parameters](#custom-parameters) | `customParametersExtraction` | `Function` | `null` | Function that enriches activities with custom parameters. | | [Custom parameters](#custom-parameters) | `customParametersExtraction` | `Function` | `null` | Function that enriches activities with custom parameters. | | [Custom proxy](#custom-proxy) | `useProxy`, `proxyHost`, `proxyPort` | `boolean`, `String`, `int` | `false`, `null`, `0` | Configures proxy forwarding for SDK backend traffic. | | [Custom proxy](#custom-proxy) | `useProxy` | `boolean` | `false` | Use a custom proxy for the Enforcer. | | [Custom proxy](#custom-proxy) | `proxyHost` | `String` | `null` | The host of the custom proxy. | | [Custom proxy](#custom-proxy) | `proxyPort` | `int` | `0` | The port of the custom proxy. | | [Encryption and buffering](#encryption-and-buffering) | `encryptionEnabled` | `boolean` | `true` | Controls cookie decryption behavior. | | [Encryption and buffering](#encryption-and-buffering) | `maxBufferLen` | `int` | `20` | Maximum number of activities to send in a single batch. | | [Filters](#filters) | `staticFilesExt` | `Set` | Built-in common extensions | File extensions ignored by the SDK. | | [Header data enrichment](#header-data-enrichment) | `pxDataEnrichmentHeaderName` | `String` | `""` | Header name for forwarding data enrichment payloads. | | [HUMAN Challenge & hard block customization](#human-challenge--hard-block-customization) | `cssRef` | `String` | `null` | URL used to customize block page. | | [HUMAN Challenge & hard block customization](#human-challenge--hard-block-customization) | `jsRef` | `String` | `null` | URL used to customize challenge page. | | [HUMAN Challenge & hard block customization](#human-challenge--hard-block-customization) | `customLogo` | `String` | `null` | URL used to customize block page logo. | | [Monitored and enforced routes](#monitored-and-enforced-routes) | `enforcedRoutes` | `Set` | `[]` | Route sets that override behavior in monitor/blocking modes. | | [Monitored and enforced routes](#monitored-and-enforced-routes) | `monitoredRoutes` | `Set` | `[]` | Route sets that override behavior in monitor/blocking modes. | | [Network configuration](#network-configuration) | `connectionTimeout` | `int` | `1000` | TCP connection timeout to HUMAN servers, in milliseconds. | | [Network configuration](#network-configuration) | `maxConnectionsPerRoute` | `int` | `50` | The maximum connections per route for Risk API requests in the connections pool. | | [Network configuration](#network-configuration) | `maxConnections` | `int` | `200` | The total maximum connections for Risk API client. | | [Network configuration](#network-configuration) | `sendPageActivities` | `boolean` | `true` | Toggle sending asynchronous page activities. | | [Network configuration](#network-configuration) | `serverURL` | `string` | `https://sapi-.perimeterx.net` | Set the base url for HUMAN servers | | [PXHD cookie](#pxhd-cookie) | `securedPxhdEnabled` | `boolean` | `false` | Adds the `Secure` attribute to the `_pxhd` cookie. | | [Remote configuration](#remote-configuration) | `loggerAuthToken` | `string` | `""` | Set the logger authentication token for HUMAN configuration service. | | [Remote configuration](#remote-configuration) | `remoteConfigurationInterval` | `int` | `5000` | Set the interval value for when to fetch configurations from PerimeterX configuration service. | | [Remote configuration](#remote-configuration) | `remoteConfigurationDelay` | `int` | `0` | Set amount of time to delay the remote configuration thread before it starts. | | [Remote configuration](#remote-configuration) | `remoteConfigurationUrl` | `string` | `https://configurations.perimeterx.net` | Set the URL for HUMAN configuration service. | | [Requests queue interval](#requests-queue-interval) | `validateRequestQueueInterval` | `int` | `5` | Interval in seconds of cleaning requests queue. Solves HttpComponent reference leak bug. | | [Sensitive headers and routes](#sensitive-headers-and-routes) | `sensitiveHeaders` | `Set` | `["cookie", "cookies"]` | Headers that should be considered sensitive. | | [Sensitive headers and routes](#sensitive-headers-and-routes) | `sensitiveRoutes` | `Set` | `[]` | Routes that should be considered sensitive. | | [Sensitive headers and routes](#sensitive-headers-and-routes) | `sensitiveRoutesRegex` | `Set` | `[]` | Regex strings for routes that should be considered sensitive. | | [Sensitive headers and routes](#sensitive-headers-and-routes) | `customIsSensitiveRequest` | `Predicate` | `(req) -> false` | Custom predicate to determine if a request should be considered sensitive. | | [Testing mode](#testing-mode) | `testingMode` | `boolean` | `false` | 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 | | [Users identifiers](#users-identifiers) | `pxJwtCookieName` | `string` | `""` | Set the name of the JWT cookie for user identifier extraction. | | [Users identifiers](#users-identifiers) | `pxJwtCookieUserIdFieldName` | `string` | `""` | Set the field name for the user ID in the JWT cookie. | | [Users identifiers](#users-identifiers) | `pxJwtCookieAdditionalFieldNames` | `string[]` | `[]` | Set the additional field names for the user ID in the JWT cookie. | | [Users identifiers](#users-identifiers) | `pxJwtHeaderName` | `string` | `""` | Set the name of the JWT header for user identifier extraction. | | [Users identifiers](#users-identifiers) | `pxJwtHeaderUserIdFieldName` | `string` | `""` | Set the field name for the user ID in the JWT header. | | [Users identifiers](#users-identifiers) | `pxJwtHeaderAdditionalFieldNames` | `string[]` | `[]` | Set the additional field names for the user ID in the JWT header. | #### Interfaces In addition to standard configurations, the Java Enforcer can be tuned and set to a different type of interface for a more flexible module. | Interface | Description | Default | Method | | :---------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- | :--------------------------- | :------------------------------ | | [`ActivityHandler`](#activityhandler) | Handler for all asynchronous activities from type `enforcer_telemetry`, `page_requested`, and `block` | `BufferedActivityHandler` | `setActivityHandler` | | [`BlockHandler`](#blockhandler) | Blocking handle will be called when `pxVerify` will return that user is not verified | DefaultBlockHandler | `blockHandler` | | [`IPProvider`](#ipprovider) | Handles IP address extraction from request | `CombinedIPProvider` | `setIpProvider` | | [`HostnameProvider`](#hostnameprovider) | Handles hostname extraction from request | `DefaultHostnameProvider` | `setHostnameProvider` | | [`VerificationHandler`](#verificationhandler) | Handling verification after HUMAN service finished analyzing the request | `DefaultVerificationHandler` | `setVerificationHandler` | | [`CustomParametersProvider`](#customparametersprovider) | Adds to all activities additional custom parameters | `CustomParametersProvider` | `customParametersProvider` | | [`LoginResponseValidator`](#loginresponsevalidator) | Validate if the Login response was successful | `LoginResponseValidator` | `isSuccessfulLogin` | | [`CredentialsExtractor`](#credentialsextractor) | Extract credentials from login request | `LoginCredentials` | `extractCredentials` | | [`RemoteConfigurationHandler`](#remoteconfigurationhandler) | Handles remote configuration | `RemoteConfigurationHandler` | `setRemoteConfigurationHandler` | ## Required configurations These configurations are necessary for the Enforcer's basic functionality and features. ### Basic functionality configurations **`appId`** `string` — required Your HUMAN Application ID in the form of `PX12AB34CD`. You can copy this value from the [HUMAN Console](https://console.humansecurity.com/) in **Platform Settings > Applications Overview.** If you have multiple applications, make sure to copy the ID of the application you want the Enforcer on. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .appId("APP_ID") // ... ``` --- **`authToken`** `string` — required The application's server token needed to authorize with HUMAN's backend. You can copy this value from the [HUMAN Console](https://console.humansecurity.com/) in **Platform Settings > Applications Overview > Click the appropriate application > Server token tab.** **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .authToken("AUTH_TOKEN") // ... ``` --- **`cookieKey`** `string | string[]` — required, default: string The secret used to encrypt and decrypt the risk cookie sent from the HUMAN Sensor. You can copy this value from the [HUMAN Console](https://console.humansecurity.com/) 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 a list of secrets via repeated `.cookieKey(...)` calls or a JSON string array. Put the new secret first. This prevents decryption failures. **`Basic example`** ```java Basic example PXConfiguration pxConf = PXConfiguration.builder() // ... .cookieKey("COOKIE_KEY") // ... ``` **`Cookie rotation example`** ```java Cookie rotation example PXConfiguration pxConf = PXConfiguration.builder() // ... .cookieKey("") .cookieKey("") // ... ``` --- **`apiTimeout`** `integer` — required, default: 1000 The total time in milliseconds that the Enforcer will wait for the **Risk API** request to return before timing out and passing the request. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .apiTimeout(2000) // ... ``` --- **`blockingScore`** `integer` — required, default: 100 The minimum risk score that the Enforcer will block. Ranges from 0 (lowest risk) to 100 (highest risk). **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .blockingScore(20) // ... ``` --- ### Basic feature configurations **`setLoggerSeverity`** `LoggerSeverity.NONE | LoggerSeverity.ERROR | LoggerSeverity.DEBUG` — required, default: LoggerSeverity.ERROR 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`](#px_logger_auth_token) for a header-based alternative. The Java Enforcer uses [SLF4J](https://www.slf4j.org/manual.html) and [Logback](https://logback.qos.ch/) for logging. **`Example`** ```java Example import com.perimeterx.models.configuration.PXConfiguration; import com.perimeterx.utils.logger.LoggerSeverity; PXConfiguration.setPxLoggerSeverity(LoggerSeverity.DEBUG); // Can be called once; you do not need to call it on every request. ``` --- **`ipHeaders`** `string[]` — required, default: \[] 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](#combinedipprovider). **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .ipHeaders(new HashSet<>(Arrays.asList("x-px-true-ip", "x-true-ip"))) // ... ``` --- **`moduleEnabled`** `boolean` — required, default: true Whether the Enforcer module is enabled. * `true`: Enable the module * `false`: Disable the module **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .moduleEnabled(false) // ... ``` --- **`moduleMode`** `ModuleMode.BLOCKING | ModuleMode.MONITOR` — required, default: ModuleMode.MONITOR 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](#enforced-routes). * `ModuleMode.BLOCKING`: The Enforcer will return block responses as needed. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .moduleMode(ModuleMode.BLOCKING) // ... ``` --- ## Optional configurations These configurations aren't required, but you can use them to further customize the Enforcer's behavior. ### Advanced blocking response (ABR) **`advancedBlockingResponse`** `boolean` — default: true 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)](/applications/set-challenge-configurations#enable-challenge-configurations#custom-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. * `true`: Enable ABR * `false`: Disable ABR **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .advancedBlockingResponse(false) // ... .build(); ``` --- ### Bypass monitor header **`bypassMonitorHeader`** `string` — default: x-px-block Activates the full blocking flow to verify the flow works as expected if the specified header is present on the request with a value of `1`. Often used to test the Enforcer block workflow during [monitor mode](#moduleMode), where the Enforcer usually collects data without blocking user requests, before switching to `ModuleMode.BLOCKING`. Requests with this header will go through the entire blocking workflow despite being in monitor mode. To disable blocking behavior on the specified header, set the value to `0`. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .bypassMonitorHeader("x-px-block") // ... .build(); ``` --- ### Credentials Intelligence These configurations let you extract and detect compromised credentials. They're closely related to [Credentials Intelligence-related features](/applications/about-the-credentials-intelligence-dashboard) in Sightline Cyberfraud Defense. At minimum, ensure the following are configured to enable Credential Intelligence: * [`loginCredentialsExtractionEnabled`](#loginCredentialsExtractionEnabled) is set to `true` * [`loginCredentialsExtractionDetails`](#loginCredentialsExtractionDetails) is configured with at least one credential endpoint **`loginCredentialsExtractionEnabled`** `boolean` — default: false Whether to enable the extraction and reporting of credentials from the Enforcer for Credential Intelligence. * `true`: Enable Credential Intelligence * `false`: Disable Credential Intelligence **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .loginCredentialsExtractionEnabled(true) // ... .build(); ``` --- **`loginCredentialsExtractionDetails`** `CILoginMap` — default: null 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 **`Example`** ```java Example PXConfiguration pxConf = new PXConfiguration.Builder() // ... .loginCredentialsExtractionDetails(ciLoginMap) // ... .build(); ``` --- **`ciProtocol`** `CIProtocol | V2` — default: V2 Determines the structure and content of the user login data. **`Example`** ```java Example PXConfiguration pxConf = new PXConfiguration.Builder() // ... .ciProtocol(CIProtocol) // ... .build(); ``` --- **`pxCompromisedCredentialsHeader`** `string` — default: px-compromised-credentials 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. **`Example`** ```java Example PXConfiguration pxConf = new PXConfiguration.Builder() // ... .pxCompromisedCredentialsHeader("x-px-compromised-credentials") // ... .build(); ``` --- **`additionalS2SActivityHeaderEnabled`** `boolean` — default: false 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. #### \`px-additional-activity\` header example ```json { "type": "additional_s2s", "timestamp": 1637000000, "socket_ip": "1.1.1.1", "px_app_id": "PX_APP_ID", "url": "https://www.example.com/the-target-url", "vid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "details": { "client_uuid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "request_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "ci_version": "v1", "http_status_code": null, // MODIFY, number (e.g., 200, 401, 404, etc.) "login_successful": null, // MODIFY, boolean (e.g., true, false) "raw_username": null // MODIFY, string (e.g., "test@mail.com") } } ``` * `px-additional-activity-url`: The URL to which the `additional_s2s` payload should be sent as an HTTP POST request. **`Example`** ```java Example private boolean additionalS2SActivityHeaderEnabled = true; ``` --- **`addRawUsernameOnAdditionalS2SActivity`** `boolean` — default: false 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. **`Example`** ```java Example private boolean addRawUsernameOnAdditionalS2SActivity = true; ``` --- **`loginResponseValidationReportingMethod`** `LoginResponseValidationReportingMethod.STATUS | LoginResponseValidationReportingMethod.HEADER | LoginResponseValidationReportingMethod.BODY | LoginResponseValidationReportingMethod.CUSTOM` — default: null 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`. #### STATUS Provide a status or array of statuses that represent a successful login. If a response’s status code matches the provided value or one of the values in the provided array, the login success status is set to true. Otherwise, it is set to `false`. To define a range of statuses, use the `CUSTOM` reporting method. **Default values:** * `px_login_successful_status`: `200` ```java private int[] loginResponseValidationStatusCode = {200}; ``` #### HEADER Provide a header name and value. If the header exists on the response and matches the provided value, the login success status is set to `true`. If the header is not found on the response, or if the header value does not match the value in the configuration, the login success status is set to `false`. **Default values:** * `headerNameToValidateLoginResponse`: `x-px-login-successful` * `headerValueToValidateLoginResponse`: `1` ```java private String headerNameToValidateLoginResponse = "x-px-login-successful"; private String headerValueToValidateLoginResponse = "1"; ``` #### BODY Provide a string or regular expression with which to parse the response body. If a match is found, the login success status is set to `true`. If no match is found, the login success status is set to `false`. **Default values:** * `regexPatternToValidateLoginResponseBody`: Empty ```java private String regexPatternToValidateLoginResponseBody = "You logged in successfully!" // string or RegExp ``` #### CUSTOM Provide a custom class that implements the [`LoginResponseValidator` interface](#loginresponsevalidator) and overrides `isSuccessfulLogin`, which receives a `ResponseWrapper` and returns a `boolean`. **Default values:** * `customLoginResponseValidator`: empty ```java public class DefaultCustomLoginResponseValidator implements LoginResponseValidator { @Override public boolean isSuccessfulLogin(HttpServletResponseWrapper response) { return false; } } ``` **`Example`** ```java Example private LoginResponseValidationReportingMethod loginResponseValidationReportingMethod = LoginResponseValidationReportingMethod.STATUS ``` --- **`loginResponseValidationRegexBody`** `string` — default: null Regex pattern that checks the response body in order to validate successful login. **`Example`** ```java Example PXConfiguration pxConf = new PXConfiguration.Builder() // ... .loginResponseValidationRegexBody("You logged in successfully!") // ... .build(); ``` --- **`headerNameToValidateLoginResponse`** `string` — default: x-px-login-successful Header name used to validate whether the login is successful. **`Example`** ```java Example PXConfiguration pxConf = new PXConfiguration.Builder() // ... .headerNameToValidateLoginResponse("x-px-login-successful") // ... .build(); ``` --- **`headerValueToValidateLoginResponse`** `string` — default: 1 Header value used to validate whether the login is successful. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .headerValueToValidateLoginResponse("ok") // ... .build(); ``` --- **`loginResponseValidationStatusCode`** `int[]` — default: \{200} Array of status codes used to validate whether the login was successful. **`Example`** ```java Example PXConfiguration pxConf = new PXConfiguration.Builder() // ... .loginResponseValidationStatusCode(new int[] { 200, 201 }) // ... .build(); ``` --- ### Custom cookie header **`customCookieHeader`** `string` — default: x-px-cookies 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. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .customCookieHeader("x-custom-cookies") // ... .build(); ``` --- ### Custom parameters **`customParametersExtraction`** `function` — default: null 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. > **Warning** > > The request body can only be read once! If you plan on reading the request body in this function, we recommend you using a request wrapper that caches the body before calling `pxVerify` **Parameters:** * `config: HumanSecurityConfiguration` * `request:` HttpServletRequest **Returns:** `Promise` **`Example`** ```java Example PXConfiguration pxConfiguration = PXConfiguration.builder() ... .customParametersExtraction((req) -> { CustomParameters customParameters = new CustomParameters(); customParameters.setCustomParam1("example-value"); customParameters.setCustomParam2(req.getHeader("example-header")); customParameters.setCustomParam3(123); // Numbers are supported customParameters.setCustomParam4(true); // Booleans are supported return customParameters; }) .build(); ``` --- ### Custom proxy **`useProxy`** `boolean` — default: false Whether to use the [`proxyHost`](#proxyHost) for message forwarding. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .useProxy(true) // ... .build(); ``` --- **`proxyHost`** `string` — default: "" 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. > **Warning** > > If using HTTPS, ensure that the proxy’s certificate is installed on the machine running the Enforcer. Required if [`useProxy`](#useProxy) is `true`. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .proxyHost("proxy.example.com") // ... .build(); ``` --- **`proxyPort`** `integer` — default: 0 The proxy's port. Required if [`useProxy`](#useProxy) is `true`. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .proxyPort(8080) // ... .build(); ``` --- ### Encryption and buffering **`encryptionEnabled`** `boolean` — default: true Whether to decode or decrypt a cookie. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .encryptionEnabled(false) // ... .build(); ``` --- **`maxBufferLen`** `integer` — default: 10 Sets the number of activities to send in batched activities. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .maxBufferLen(20) // ... .build(); ``` --- ### Filters **`staticFilesExt`** `Set` — default: \["css", "bmp", ... , "json"] 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. > **Note** > > Filtering by extension only applies to GET and HEAD HTTP methods. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .staticFilesExt(new HashSet<>(Arrays.asList("css", "js", "png"))) // ... .build(); ``` --- ### Header data enrichment These configurations let you add headers to incoming requests with additional data. **`pxDataEnrichmentHeaderName`** `string` — default: "" 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](/applications/data-classification-enrichment). **`Example`** ```java Example PXConfiguration config = new PXConfiguration.Builder() ... .pxDataEnrichmentHeaderName("X-PX-Data-Enrichment") .build(); PerimeterX enforcer = new PerimeterX(config); // In your filter: PXContext ctx = enforcer.pxVerify(request, response); // After pxVerify, the request now contains the data enrichment header // and can be forwarded to your backend/origin server // The header will be available as "X-PX-Data-Enrichment" in the request filterChain.doFilter(request, response); ``` --- ### HUMAN Challenge & hard block customization These configurations let you customize the [HUMAN Challenge block page](/applications/create-a-human-challenge) as well as the hard block page, which appears when a request is blocked without a Challenge. Hard block pages inherit the same styling as the HUMAN Challenge according to the following configurations and cannot be customized separately. **`cssRef`** `string` A way to include a custom CSS file to the block page. Maps to `{{cssRef}}` in the hard block page template. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .cssRef("https://www.example.com/custom_style.css") // ... .build(); ``` --- **`jsRef`** `string` A way to include custom JavaScript to the block page. This script will run after the default JavaScript scripts. Maps to `{{jsRef}}` in the hard block page template. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .jsRef("https://www.example.com/custom_script.js") // ... .build(); ``` --- **`customLogo`** `string` — default: "" Adds a custom logo to the [HUMAN Challenge](/applications/create-a-human-challenge) block page via URL. Maps to `{{customLogo}}` in the hard block page template. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .customLogo("https://www.example.com/custom_logo.png") // ... .build(); ``` --- ### Monitored and enforced routes These configurations let you define specific routes that should be enforced by HUMAN when the Enforcer is in [monitor mode](#moduleMode). These routes will always be subject to the full Enforcer workflow, including blocking requests if necessary. Primitive string values are treated as path prefixes. For example, `/login` also matches `/login/callback`. **`enforcedRoutes`** `Set` — default: \[] Routes or prefixes that should be enforced by HUMAN even when the Enforcer is in [monitor mode](#moduleMode). **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .enforcedRoutes(new HashSet<>(Arrays.asList("/checkout", "/api/payment"))) // ... .build(); ``` --- **`monitoredRoutes`** `Set` — default: \[] A list of endpoints to be monitored rather than blocked by the Enforcer, even when the Enforcer is in [`ModuleMode.BLOCKING`](#moduleMode) mode. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .monitoredRoutes(new HashSet<>(Arrays.asList("/status", "/health"))) // ... .build(); ``` --- ### Network configuration **`connectionTimeout`** `integer` — default: 1000 TCP connection timeout to HUMAN servers, in milliseconds. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .connectionTimeout(2000) // ... .build(); ``` --- **`maxConnectionsPerRoute`** `integer` — default: 50 The maximum connections per route for Risk API requests in the connections pool. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .maxConnectionsPerRoute(100) // ... .build(); ``` --- **`maxConnections`** `integer` — default: 200 The total maximum connections for Risk API client. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .maxConnections(300) // ... .build(); ``` --- **`sendPageActivities`** `boolean` — default: true Toggle sending asynchronous page activities. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .sendPageActivities(false) // ... .build(); ``` --- **`serverURL`** `string` — default: https\://sapi-\.perimeterx.net Set the base URL for HUMAN servers **`Example`** ```java Example PXConfiguration pxConf = new PXConfiguration.Builder() // ... .serverUrl("https://custom-collector.example.com") // ... .build(); ``` --- ### PXHD cookie **`securedPxhdEnabled`** `boolean` — default: false The PX Hashed Data (PXHD or `_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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies#block_access_to_your_cookies) is added when setting the PXHD cookie. See [Use of cookies & web storage](/applications/use-of-cookies-web-storage) for more information. * `true`: Adds the `Secure` attribute to the PXHD cookie * `false`: Does not add the `Secure` attribute to the PXHD cookie **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .securedPxhdEnabled(true) // ... .build(); ``` --- ### Remote configuration Remote Configuration lets you update your Enforcer's configuration from the HUMAN portal rather than interacting with the Enforcer package directly. **`loggerAuthToken`** `string` — default: "" An alternative to the [basic logger](#setLoggerSeverity) 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](/applications/human-customer-support) to receive your token. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .loggerAuthToken("LOGGER_AUTH_TOKEN") // ... .build(); ``` --- **`remoteConfigurationInterval`** `integer` — default: 5000 The interval time in milliseconds to wait between attempts to fetch the Remote Configuration. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .remoteConfigurationInterval(15000) // ... .build(); ``` --- **`remoteConfigurationDelay`** `integer` — default: 0 The amount of time to delay the remote configuration thread before it starts **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .remoteConfigurationDelay(1000) // ... .build(); ``` --- **`remoteConfigurationUrl`** `string` Set the URL for HUMAN configuration service **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .remoteConfigurationUrl("https://configurations.perimeterx.net") // ... .build(); ``` --- ### Requests queue interval **`validateRequestQueueInterval`** `integer` — default: 5 Interval in seconds of cleaning requests queue. Solves HttpComponent reference leak bug. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .validateRequestQueueInterval(10) // ... .build(); ``` --- ### Sensitive headers and routes **`sensitiveHeaders`** `Set` — default: \["cookie", "cookies"] 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. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .sensitiveHeaders(new HashSet<>(Arrays.asList("cookie", "authorization"))) // ... .build(); ``` --- **`sensitiveRoutes`** `Set` — default: \[] A list of prefixes for all routes that should be considered sensitive. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .sensitiveRoutes(new HashSet<>(Arrays.asList("/login", "/checkout"))) // ... .build(); ``` --- **`sensitiveRoutesRegex`** `Set` — default: \[] Regex strings for routes that should be considered sensitive. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .sensitiveRoutesRegex(new HashSet<>(Arrays.asList("^/api/login$", "^/api/users/.*/password$"))) // ... .build(); ``` --- **`customIsSensitiveRequest`** `Predicate` — default: (req) -> false > **Warning** > > This configuration is meant for cases that require more complex logic. We recommended you use [`sensitiveRoutes`](#sensitiveRoutes) for most cases. 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. **`Example`** ```java Example PXConfiguration pxConfiguration = new PXConfiguration.Builder() ... .customIsSensitiveRequest((req) -> req.getHeader("example-header") == "example-value") .build(); ``` --- ### Testing mode **`testingMode`** `boolean` — default: false 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 **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .testingMode(true) // ... .build(); ``` --- ### Users identifiers These configurations let you extract user identifiers from a JWT carried on the request either in a cookie or a header. They're closely related to the [Accounts](/applications/about-the-accounts-overview-dashboard) and [Account Takeover or Fake Account](/applications/about-the-recent-attacks-dashboard) features in Sightline Cyberfraud Defense. The Enforcer reads the JWT from the configured cookie first, then from the configured header if cookie extraction does not succeed. Field names support dot notation for nested JWT claim (for example, `product.id`). **`pxJwtCookieName`** `string` — default: "" The name of the cookie that contains the JWT token that HUMAN should extract user identifiers from. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .pxJwtCookieName("auth") // ... .build(); ``` --- **`pxJwtCookieUserIdFieldName`** `string` — default: "" The field name in the JWT object, extracted from the JWT cookie, that contains the user ID to be extracted and reported. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .pxJwtCookieUserIdFieldName("nameID") // ... .build(); ``` --- **`pxJwtCookieAdditionalFieldNames`** `string[]` — default: \[] The field names in the JWT object, extracted from the JWT cookie, that should be extracted and reported in addition to the user ID. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .pxJwtCookieAdditionalFieldNames(Arrays.asList("exp", "iss")) // ... .build(); ``` --- **`pxJwtHeaderName`** `string` — default: "" The name of the header that contains the JWT token that HUMAN should extract user identifiers from. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .pxJwtHeaderName("x-jwt-authorization") // ... .build(); ``` --- **`pxJwtHeaderUserIdFieldName`** `string` — default: "" The field name in the JWT object, extracted from the JWT header, that contains the user ID to be extracted and reported. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .pxJwtHeaderUserIdFieldName("sub") // ... .build(); ``` --- **`pxJwtHeaderAdditionalFieldNames`** `string[]` — default: \[] The field names in the JWT object, extracted from the JWT header, that should be extracted and reported in addition to the user ID. **`Example`** ```java Example PXConfiguration pxConf = PXConfiguration.builder() // ... .pxJwtHeaderAdditionalFieldNames(Arrays.asList("exp", "iss")) // ... .build(); ``` --- ## Interfaces You can use the following interfaces to tune the Java Enforcer to your specific needs. Interfaces should be set after you initialize the PerimeterX instance. **`Example`** ```java Example BlockHandler exampleBlockHandler = new ExampleBlockHandler(); PXConfiguration pxConf = new PXConfiguration.Builder(exampleBlockHandler) // This will set the blocking handler from the default one to // the our custom block handler .blockHandler() .build(); this.enforcer = new PerimeterX(pxConf) this.enforcer.setActivityHandler(new BlockingActivityHandler()); ``` **`activityHandler`** `Defaults to BufferedActivityHandler` Handler for all asynchronous activities from type `enforcer_telemetry`, `page_requested`, and `block`. * Method: `setActivityHandler` --- **`blockHandler`** `Defaults to DefaultBlockHandler` Blocking handle will be called when `pxVerify` will return that user is not verified. * Method: `blockHandler` --- **`ipProvider`** `Defaults to CombinedIPProvider` Handles IP address extraction from request. * Method: `setIpProvider` --- **`hostnameProvider`** `Defaults to DefaultHostnameProvider` Handles hostname extraction from request. * Method: `setHostnameProvider` --- **`verificationHandler`** `Defaults to DefaultVerificationHandler` Handling verification after HUMAN service finished analyzing the request. * Method: `setVerificationHandler` --- **`customParametersProvider`** `Defaults to CustomParametersProvider` Adds to all activities additional custom parameters. * Method: `customParametersProvider` --- **`loginResponseValidator`** `Defaults to LoginResponseValidator` Validate if the Login response was successful. * Method: `isSuccessfulLogin` --- **`credentialsExtractor`** `Defaults to LoginCredentials` Extract credentials from login request. * Method: `extractCredentials` ---