Directives
HUMANConfiguration
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 \ generated in HUMANHUMAN portal - Policy page. | null | String | mandatory |
authToken | JWT token used for REST API - Can be found \ 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 \ 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 | ||
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 | |
MonitoredRoutes | A list of specific routes that should be monitored and not actively enforced (blocked) even if Monitor Mode is set to Active Blocking. | [] | A list of string representations of regex routes or a specific route | Set |
EnforcedRoutes | A list of specific routes that should be enforced even if Monitor Mode is set to Monitor. | [] | A list of string representations of regex routes or a specific route | Set |
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 strcuture 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 succussful login. | null | String | |
headerNameToValidateLoginResponse | Header name that is used to validate if the login is succesful. | 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 |
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
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());
Configuration Examples
Basic Active And Blocking Configuration
PXConfiguration pxConf = new PXConfiguration.Builder()
.appId("APP_ID")
.cookieKey("AUTH_TOKEN") // Should copy from RiskCookie section in https://console.perimeterx.com/botDefender/admin?page=policiesmgmt
.moduleMode(ModuleMode.BLOCKING)
.authToken("AUTH_TOKEN") // PX Server request auth token to be copied from Token section in https://console.perimeterx.com/botDefender/admin?page=applicationsmgmt
.build();
Module Enabled/Disabled
PXConfiguration pxConf = new PXConfiguration.Builder()
...
.moduleEnabled(false) // default is true
...
Monitored routes
PXConfiguration pxConf = new PXConfiguration.Builder()
...
.monitoredRoutes(new HashSet<String>(Arrays.asList("/profile", "/profile.*")));
...
Enforced routes
PXConfiguration pxConf = new PXConfiguration.Builder()
...
.enforcedRoutes(new HashSet<String>(Arrays.asList("/profile", "/profile.*")));
...
Tune Blocking Score Threshold
PXConfiguration pxConf = new PXConfiguration.Builder()
...
.blockingScore(95)
Sensitive Headers
PXConfiguration pxConf = new PXConfiguration.Builder()
...
.sensitiveHeaders(new HashSet<String>(Arrays.asList("cookie", "cookies")))
...
IP Headers
PXConfiguration pxConf = new PXConfiguration.Builder()
...
.ipHeaders(new HashSet<String>(Arrays.asList("x-px-true-ip", "x-true-ip")))
...
Sensitive Routes
PXConfiguration pxConf = new PXConfiguration.Builder()
...
.sensitiveRoutes(new HashSet<String>(Arrays.asList("/cartCheckout")))
...
Customizing Default Block Page
PXConfiguration pxConf = new PXConfiguration.Builder()
...
.customLogo(URL_TO_LOGO)
.cssRef(URL_TO_CSS)
.jsRef(URL_TO_JS)
...
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
public class PerimeterxCustomParamsProvider implements CustomParametersProvider {
public CustomParameters buildCustomParameters(PXConfiguration pxConfiguration, PXContext pxContext) {
... Some logic ...
String cp2 = "PerimeterX_Custom_param2";
String cp5 = "PerimeterX_Custom_param5";
customParameters.setCustomParam2(cp2);
customParameters.setCustomParam5(cp5);
... Some logic ...
return customParameters;
}
}
PXConfiguration pxConf = new PXConfiguration.Builder()
PerimeterxCustomParamsProvider perimeterxCustomParamsProvider = new PerimeterxCustomParamsProvider();
...
.customParametersProvider(PerimeterxCustomParamsProvider)
...
Custom Sensitive Request
Allows writing your own logic to decide whether the request is sensitive.
The custom sensitive request function gets the request object as a parameter and should return true, otherwise, return false. Throwing an exception is equivalent to `false`. Implementing this configuration does not override other `sensitive` configurations, like `sensitive_routes`.
Example
PXConfiguration pxConfiguration = new PXConfiguration.Builder()
...
.customIsSensitiveRequest((req) -> req.getHeader("example-header") == "example-value")
.build();
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.
PXConfiguration config = new PXConfiguration.Builder()
.appId("PXaBcDeFgH")
.cookieKey("COOKIE_KEY")
.authToken("AUTH_TOKEN")
.useProxy(true)
.proxyHost(127.0.0.1)
.proxyPort(80)
.build();
PXConfiguration config = new PXConfiguration.Builder()
.appId("PXaBcDeFgH")
.cookieKey("COOKIE_KEY")
.authToken("AUTH_TOKEN")
.useProxy(true)
.proxyHost(yourdomain.com)
.build();
Updated 12 days ago