Directives
HUMANConfigurations
| Interface Name | Description | Default value | Values | Note |
|---|---|---|---|---|
| appId | HUMAN custom application ID in the format of HUMAN**__** | null | String | mandatory |
| cookieKey | Key used for cookie signing - Can be found or generated in HUMAN portal - Policy page. | null | String | mandatory |
| authToken | JWT token used for REST API - Can be found or generated in HUMAN portal - Application page. | null | String | mandatory |
| moduleMode | Set the mode for HUMAN module, Blocking or Monitor, setting to blocking mode meaning the module will be active blocking, monitor mode will only inspect the request but will not block it | Monitor | ModuleMode.BLOCKING / ModuleMode.MONITOR | enum, mandatory for active blocking |
| moduleEnabled | Flag for enabling or disabling HUMAN protection. | true | Boolean | |
| encryptionEnabled | Flag indicating the module to decode or decrypt a cookie. | true | Boolean | |
| blockingScore | When requests with a score equal to or higher value they will be blocked. | 100 | int | |
| sensitiveHeaders | Marks which headers will not be send to HUMAN backends | [cookie, cookies] | Set | |
| maxBufferLen | Set the number of activities to send in batched activities | 10 | int | |
| apiTimeout | Response timeout after sending the request | 1000 | int | Milliseconds |
| connectionTimeout | TCP connection with the HUMAN server timeout | 1000 | int | Milliseconds |
| maxConnectionsPerRoute | Set the maximum connection per route for risk api requests in the connections pool | 50 | int | |
| maxConnections | Set the total maximum connections for risk api client | 200 | int | |
| sendPageActivities | Toggle sending asynchronous page activities | true | Boolean | |
| serverURL | Set the base url for HUMAN servers | https://sapi-<app_id>.perimeterx.net | String | |
| customLogo | The logo will be displayed at the top div of the the block page. The logo’s host name | String | ||
| cssRef | The block page can be modified with a custom CSS by adding the CSSRef directive and providing a valid URL to the css | null | String | |
| jsRef | The block page can be added with custom JS file by adding JSRef directive and providing the JS file that will be loaded with the block page. | null | String | |
| sensitiveRoutes | List of routes the HUMAN module will always do a server-to-server call for, even if the cookie score is low and valid | Empty list | Set | |
| remoteConfigurationEnabled | Toggle remote configurations, when true, initial configurations will be set through constructor, then can be tuned from the portal | false | Boolean | |
| remoteConfigurationInterval | Set the interval value for when to fetch configurations from HUMAN’s configuration service | 5000 | int | Milliseconds |
| remoteConfigurationDelay | Set amount of time to delay the remote configuration thread before it starts | 0 | int | Milliseconds |
| remoteConfigurationUrl | Set the UTL for HUMAN configuration service | String | ||
| ipHeaders | List of headers to extract the user IP from, if not set, it will be taken from default | Empty List | Set | Use with CombinedIPProvider |
| firstPartyEnabled | Toggle first party requests enabled | true | Boolean | Read more details about first party integration here |
| xhrFirstPartyEnabled | Toggle first party XHR requests will be forwarded to PerimeterX servers | true | Boolean | |
| useProxy | The http client shall use a proxy for message forwarding | false | Boolean | |
| proxyHost | The proxy’s host name | String | ||
| proxyPort | The proxy’s port | None - required | int | |
| testingMode | Running the Enforcer in dev environment for testing purposes, response returned as a JSON object. When you run the Enforcer in testing mode, please do not set custom verification handler | false | Boolean | |
| validateRequestQueueInterval | Interval in seconds of cleaning requests queue. Solves HttpComponent reference leak bug. | 5 | int | |
| loginCredentialsExtractionEnabled | Flag that enables/disables the extraction of login credentials. | false | boolean | |
| loginCredentialsExtractionDetails | Maps the json login credentials configuration array to a dedicate class. The map helps in determine if an incoming request is a login request or not. | null | CILoginMap | |
| ciProtocol | Credentials Intelligence protocol determines the structure and content of the user login data. | V2 | CIProtocol | |
| pxCompromisedCredentialsHeader | The name of the header that is sent to the client to mark that the account is breached. | ”px-compromised-credentials” | String | |
| addRawUsernameOnAdditionalS2SActivity | Flag that determines if raw username will be sent in the additional S2S activity. | false | boolean | |
| additionalS2SActivityHeaderEnabled | Flag that determines if additional S2S activity will be sent from the client’s origin to HUMAN. | boolean | false | |
| loginResponseValidationReportingMethod | Method name that determines how to validate if the login was successful. | null | LoginResponseValidationReportingMethod | |
| loginResponseValidationRegexBody | Regex pattern that checks the response body in order to validate successful login. | null | String | |
| headerNameToValidateLoginResponse | Header name that is used to validate if the login is successful. | x-px-login-successful | String | |
| headerValueToValidateLoginResponse | Header value that is used to validate if the login is successful. | ”1” | String | |
| loginResponseValidationStatusCode | Array of status codes that is used to validate if the login was successful. | 200 | int[] | |
| customLoginResponseValidator | Custom class that validates if the login was successful. LoginResponseValidator must be implemented to be able to use this class. | DefaultCustomLoginResponseValidator | LoginResponseValidator | |
| credentialsCustomExtractor | Custom class that extracts the login credentials. CredentialsExtractor must be implemented to be able to use this class. | DefaultCredentialsCustomExtractor | CredentialsExtractor | |
| pxDataEnrichmentHeaderName | Header name for forwarding data enrichment payload to origin server. When set, the SDK will add the PXDE payload as a header that can be forwarded to backend services. | "" (empty string) | String | Used with data enrichment feature |
| securedPxhdEnabled | Enable secure flag on pxhd cookie for enhanced security in HTTPS-only environments. | false | Boolean | |
| pxJwtCookieName | Name of the cookie containing JWT token for user identifier extraction. | null | String | Part of Account Defender JWT user identifiers feature |
| pxJwtCookieUserIdFieldName | Field name in JWT payload to extract as user ID from cookie. | null | String | Supports dot notation for nested fields (e.g., “user.id”) |
| pxJwtCookieAdditionalFieldNames | List of additional field names to extract from JWT cookie payload. | Empty List | String[] | Supports dot notation for nested fields |
| pxJwtHeaderName | Name of the header containing JWT token for user identifier extraction. | null | String | Part of Account Defender JWT user identifiers feature |
| pxJwtHeaderUserIdFieldName | Field name in JWT payload to extract as user ID from header. | null | String | Supports dot notation for nested fields (e.g., “sub”) |
| pxJwtHeaderAdditionalFieldNames | List of additional field names to extract from JWT header payload. | Empty List | String[] | Supports dot notation for nested fields |
Interfaces
perimeterx-java-sdk can be tuned and set a different types of interfaces in order to make the module more flexible
Below you can find a list of available interfaces and their setter
| Interface Name | Description | Default Interface | method |
|---|---|---|---|
| ActivityHandler | Handler for all asynchronous activities from type enforcer_telemetry, page_requested and block | BufferedActivityHandler | setActivityHandler |
| BlockHandler | Blocking handle will be called when pxVerify will return that user is not verified | DefaultBlockHandler | blockHandler |
| IPProvider | Handles IP address extraction from request | CombinedIPProvider | setIpProvider |
| HostnameProvider | Handles hostname extraction from request | DefaultHostnameProvider | setHostnameProvider |
| VerificationHandler | handling verification after HUMAN service finished analyzing the request | DefaultVerificationHandler | setVerificationHandler |
| CustomParametersProvider | Adds to all activities additional custom parameters | CustomParametersProvider | customParametersProvider |
| LoginResponseValidator | Validate if the Login response was successful | LoginResponseValidator | isSuccessfulLogin |
| CredentialsExtractor | Extract credentials from login request | LoginCredentials | extractCredentials |
The interfaces should be set after HUMAN instance has been initialized
1 BlockHandler exampleBlockHandler = new ExampleBlockHandler(); 2 PXConfiguration pxConf = new PXConfiguration.Builder(exampleBlockHandler) 3 // This will set the blocking handler from the default one to 4 // the our custom block handler 5 .blockHandler() 6 .build(); 7 this.enforcer = new PerimeterX(pxConf) 8 this.enforcer.setActivityHandler(new BlockingActivityHandler());
Configuration Examples
Basic Active And Blocking Configuration
1 PXConfiguration pxConf = new PXConfiguration.Builder() 2 .appId("APP_ID") 3 .cookieKey("AUTH_TOKEN") // Should copy from RiskCookie section in https://console.perimeterx.com/botDefender/admin?page=policiesmgmt 4 .moduleMode(ModuleMode.BLOCKING) 5 .authToken("AUTH_TOKEN") // PX Server request auth token to be copied from Token section in https://console.perimeterx.com/botDefender/admin?page=applicationsmgmt 6 .build();
Module Enabled/Disabled
1 PXConfiguration pxConf = new PXConfiguration.Builder() 2 ... 3 .moduleEnabled(false) // default is true 4 ...
Monitored routes
1 PXConfiguration pxConf = new PXConfiguration.Builder() 2 ... 3 .monitoredRoutes(new HashSet<String>(Arrays.asList("/profile", "/profile.*"))); 4 ...
Enforced routes
1 PXConfiguration pxConf = new PXConfiguration.Builder() 2 ... 3 .enforcedRoutes(new HashSet<String>(Arrays.asList("/profile", "/profile.*"))); 4 ...
Tune Blocking Score Threshold
1 PXConfiguration pxConf = new PXConfiguration.Builder() 2 ... 3 .blockingScore(95)
Sensitive Headers
1 PXConfiguration pxConf = new PXConfiguration.Builder() 2 ... 3 .sensitiveHeaders(new HashSet<String>(Arrays.asList("cookie", "cookies"))) 4 ...
IP Headers
1 PXConfiguration pxConf = new PXConfiguration.Builder() 2 ... 3 .ipHeaders(new HashSet<String>(Arrays.asList("x-px-true-ip", "x-true-ip"))) 4 ...
Sensitive Routes
1 PXConfiguration pxConf = new PXConfiguration.Builder() 2 ... 3 .sensitiveRoutes(new HashSet<String>(Arrays.asList("/cartCheckout"))) 4 ...
Customizing Default Block Page
1 PXConfiguration pxConf = new PXConfiguration.Builder() 2 ... 3 .customLogo(URL_TO_LOGO) 4 .cssRef(URL_TO_CSS) 5 .jsRef(URL_TO_JS) 6 ...
Custom Parameters Provider
Risk API requests can be enriched with custom parameters by implementing CustomParametersProvider and adding logic to extract the custom parameters from the request.
Before implementing the interface, please make sure to configure custom parameters on HUMAN portal.
Make sure that the custom parameters are NOT marked as query strings
1 public class PerimeterxCustomParamsProvider implements CustomParametersProvider { 2 public CustomParameters buildCustomParameters(PXConfiguration pxConfiguration, PXContext pxContext) { 3 ... Some logic ... 4 String cp2 = "PerimeterX_Custom_param2"; 5 String cp5 = "PerimeterX_Custom_param5"; 6 customParameters.setCustomParam2(cp2); 7 customParameters.setCustomParam5(cp5); 8 ... Some logic ... 9 10 return customParameters; 11 } 12 } 13 PXConfiguration pxConf = new PXConfiguration.Builder() 14 PerimeterxCustomParamsProvider perimeterxCustomParamsProvider = new PerimeterxCustomParamsProvider(); 15 ... 16 .customParametersProvider(PerimeterxCustomParamsProvider) 17 ...
Proxy Integration
Providing a proxy allows the communication between the Enforcer and our backend service via proxy. You can set the proxy as a hostname (with a domain name), or as an ip port combination. If you choose to use the proxy’s domain, do not enter a port in the configuration. Make sure you have the proxy’s certificate installed on the machine that is running the Enforcer.
1 PXConfiguration config = new PXConfiguration.Builder() 2 .appId("PXaBcDeFgH") 3 .cookieKey("COOKIE_KEY") 4 .authToken("AUTH_TOKEN") 5 .useProxy(true) 6 .proxyHost(127.0.0.1) 7 .proxyPort(80) 8 .build(); 9 10 PXConfiguration config = new PXConfiguration.Builder() 11 .appId("PXaBcDeFgH") 12 .cookieKey("COOKIE_KEY") 13 .authToken("AUTH_TOKEN") 14 .useProxy(true) 15 .proxyHost(yourdomain.com) 16 .build();