Skip to navigation

Salesforce Commerce Cloud configuration options

Learn about different configuration options for the Salesforce Commerce Cloud Enforcer.

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. You can set most options in the Salesforce Business Manager. However, custom functions must be defined in int_perimeterx/cartridge/scripts/config/pxCustomFunctionsConfig.js.

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.

To update, navigate to Salesforce Business Manager and open Merchant Tools > Site Preferences > Custom Preferences > PXConfig. The Key is the field name shown on that form.

Salesforce Business Manager changes take effect after you click Save. Custom function changes require uploading the updated cartridge and activating the code version.

Types and format

Salesforce Business Manager stores values as strings, booleans, or integers. The cartridge parses some string fields as follows:

  • Comma-separated list: IP Headers, Sensitive Headers, IP Whitelist, and Filter by HTTP Method. Separate values with commas and no spaces (for example, DELETE,PUT).
  • Regular expression: Path Whitelist, Sensitive Routes, Monitored routes, and Enforced routes. Use /pattern/flags form. Add the i flag for case-insensitive matching. These patterns are matched against the Salesforce httpPath (for example, /on/demandware.store/Sites-YourSite-Site/en_US/Account-Login).
  • JSON array: Login credentials extraction. Paste a JSON array of credential endpoint objects.

Quick reference

Feature nameKeyTypeDefaultDescription
Application IDAppIDString""HUMAN Application ID
Authentication tokenAuthentication TokenString""HUMAN authentication token
Cookie secretCookie KeyString""HUMAN cookie secret
Blocking scoreBlocking ScoreInteger1000-100. The minimum risk score that the Enforcer blocks from.

Required configurations

These configurations are necessary for the Enforcer’s basic functionality and features.

Basic functionality configurations

AppID
stringRequired

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.

Authentication Token
stringRequired

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.

stringRequired

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.

Blocking Score
integerDefaults to 100Required

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

Basic feature configurations

IP Headers
stringRequired

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.

Taken from the Salesforce request remote address, then the dw-is-client_addr header, then the x-is-remote_addr header by default. Configure as a comma-separated list of header names.

Logger Severity
"none" | "error" | "debug"Defaults to "none"Required

The severity at which the cartridge writes logs.

  • none: The cartridge logs only errors. This is the Business Manager default.
  • error: The cartridge logs only errors.
  • debug: The cartridge logs detailed debug messages in addition to errors. Not recommended for production environments.

none and error behave the same way, where error logs are always written. Debug logs are written only when the value is debug. HUMAN messages use these templates:

  • Error messages: [PerimeterX - ERROR][APP_ID] - MESSAGE
  • Debug messages: [PerimeterX - DEBUG][APP_ID] - MESSAGE

Salesforce debug logs prefix each line with a timestamp and pipeline identifier. For example:

[2017-12-04 14:02:48.170 GMT] DEBUG PipelineCallServlet|9502992|Sites-SiteGenesis-Site|Default-Start|PipelineCall|jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== custom Sites-SiteGenesis-Site STOREFRONT jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== k1OX8IhVJVpqAAAK-0-00 9135655695325170688 - [PerimeterX - DEBUG][APP_ID] - Starting request verification
[2017-12-04 14:02:48.171 GMT] DEBUG PipelineCallServlet|9502992|Sites-SiteGenesis-Site|Default-Start|PipelineCall|jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== custom Sites-SiteGenesis-Site STOREFRONT jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== k1OX8IhVJVpqAAAK-0-00 9135655695325170688 - [PerimeterX - DEBUG][APP_ID] - Request context created successfully
[2017-12-04 14:02:48.171 GMT] DEBUG PipelineCallServlet|9502992|Sites-SiteGenesis-Site|Default-Start|PipelineCall|jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== custom Sites-SiteGenesis-Site STOREFRONT jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== k1OX8IhVJVpqAAAK-0-00 9135655695325170688 - [PerimeterX - DEBUG][APP_ID] - Cookie V3 found, Evaluating
[2017-12-04 14:02:48.394 GMT] DEBUG PipelineCallServlet|9502992|Sites-SiteGenesis-Site|Default-Start|PipelineCall|jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== custom Sites-SiteGenesis-Site STOREFRONT jLvMauivMBL8z7l1SRVBheAkTSR3zoHdk6G72IQQfr5SJs_uahpfrS7tfVKTaEHaVRs_WVcLLZMobrW6ugEcwA== k1OX8IhVJVpqAAAK-0-00 9135655695325170688 - [PerimeterX - DEBUG][APP_ID] - Cookie evaluation ended successfully, risk score: 0
Module Enabled
booleanDefaults to trueRequired

Whether the Enforcer module is enabled.

  • true: Enable the module
  • false: Disable the module
Module Mode
"monitor" | "active_blocking"Defaults to monitorRequired

The Enforcer’s operation mode.

  • 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.
  • active_blocking: The Enforcer will return block responses as needed.

Optional configurations

These configurations aren’t required, but you can use them to further customize the Enforcer’s behavior.

Backend and collector URLs

Backend Url
stringDefaults to https://sapi-<AppID>.perimeterx.net

Do not set this value unless directed by your HUMAN Solutions Engineer.

The base URL for the HUMAN SAPI (Risk API and related calls). If empty, the Enforcer uses the default host for your Application ID.

The default value uses your Application ID in lowercase. For example, https://sapi-px12ab34cd.perimeterx.net.

Collector Url
stringDefaults to https://collector-<AppID>.perimeterx.net

Do not set this value unless directed by your HUMAN Solutions Engineer.

The base URL for HUMAN async activities (page_requested, block, and related calls). If empty, the Enforcer uses the default collector host for your Application ID.

The default value uses your application ID in lowercase. For example, https://collector-px12ab34cd.perimeterx.net.

Bypass monitor header

Bypass Monitor Mode Header
string

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, where the Enforcer usually collects data without blocking user requests, before switching to active_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.

Credentials Intelligence

These configurations let you extract and detect compromised credentials. They’re closely related to Credentials Intelligence-related features in Sightline Cyberfraud Defense.

At minimum, ensure the following are configured to enable Credential Intelligence:

The cartridge reports login success with a storefront hook rather than by inspecting the HTTP response automatically. See Additional S2S activity. If the request contains credentials, session.privacy.PXCompromised is set to a boolean after enforcement indicating whether the credentials are compromised.

Login credentials extraction enabled
booleanDefaults to false

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

  • true: Enable Credential Intelligence
  • false: Disable Credential Intelligence
Login credentials extraction
string

An array of configuration objects for each credential endpoint. Each object describes how to identify the request and how to extract the username and password. Paste the array as JSON in the PXConfig field.

Credential path values are matched against the Salesforce httpPath (for example, /on/demandware.store/Sites-RefArch-Site/en_US/Account-Login). When path_type is regex, use a raw regular expression string such as ^/on/demandware.store/.*/Account-Login$, not /pattern/flags form. Matching is case-insensitive.

path
stringRequired

The path of the request that contains the credentials. It can be either an exact path or a string in the form of a regular expression.

Example
{
// ...
path: '/sign-up',
// ...
}
path_type
"exact" | "regex"Defaults to "exact"

Whether the incoming request path should be evaluated against the configured path as a regular expression or as an exact match.

  • exact: The value set in path must match the request path exactly as is.
  • regex: The value set in path is a regular expression to be matched against the request path.
Example
{
// ...
path: '/auth/[A-Za-z0-9]{12}/login',
path_type: 'regex',
// ...
}
method
stringRequired

The HTTP method of the request that contains the credentials. This can be set to any string representing an HTTP method.

Example
{
// ...
method: 'POST',
// ...
}
sent_through
"body" | "header" | "query-param"Required

Whether the credentials should be extracted from the request body, headers, or query parameters.

  • "body": The credentials are extracted from the request body using user_field and pass_field. The Enforcer parses the body when the Content-Type is application/json or application/x-www-form-urlencoded. Nested JSON fields can use period-separated paths.
  • "header": The credentials are extracted from the request headers.
  • "query-param": The credentials are extracted from the request query parameters.
user_field
string

Required if sent_through is set to "body", "header", or "query-param". The name of the field containing the username in the request body, headers, or query parameters.

Supports subfields in cases of Content-Type: application/json bodies with nested objects. The subfields can be separated with periods. For example, the credential endpoint configuration object can include a user_field with the value "user_info.username" and a pass_field with the value "authentication.password" to support extracting the credentials.

{
// ...
sent_through: 'body',
user_field: 'username',
// ...
}
pass_field
string

Required if sent_through is set to "body", "header", or "query-param". The name of the field, header name, or query parameter where the password can be found.

Supports subfields in cases of Content-Type: application/json bodies with nested objects. The subfields can be separated with periods. For example, the credential endpoint configuration object can include a user_field with the value "user_info.username" and a pass_field with the value "authentication.password" to support extracting the credentials.

{
// ...
sent_through: 'body',
user_field: 'username',
// ...
}
Example
[
{
"method": "post",
"path_type": "exact",
"path": "/on/demandware.store/Sites-RefArch-Site/en_US/Account-Login",
"sent_through": "body",
"user_field": "loginEmail",
"pass_field": "loginPassword"
},
{
"method": "post",
"path_type": "regex",
"path": "^/on/demandware.store/Sites-RefArch-Site/.*/Account-Login$",
"sent_through": "body",
"user_field": "nested.username",
"pass_field": "nested.password"
}
]
Credentials Intelligence Version
"v2" | "multistep_sso"Defaults to v2

The credential hashing protocol.

  • "v2": Both username and password are present on the same HTTP request and must be extracted successfully to trigger Credentials Intelligence.
  • "multistep_sso": The username and password are delivered on different HTTP requests. Either the username or password, but not both, must be extracted successfully to trigger Credentials Intelligence.
Send raw username on additional s2s activity
booleanDefaults to 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.

Additional S2S activity

To report whether a login succeeded, call the additionalS2SHandling hook from your login flow and pass the login result and HTTP status code:

var HookManager = require('dw/system/HookMgr');
HookManager.callHook('app.scripts.additionalS2SHandling', 'additionalS2SHandling', {
login_successful: isLoginSuccessful,
status_code: statusCode
});
stringDefaults to 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.

Enforced routes

These configurations let you define specific routes that should be enforced by HUMAN when the Enforcer is in monitor mode. These routes will always be subject to the full Enforcer workflow, including blocking requests if necessary.

Enforced routes
string

Routes or prefixes that should be enforced by HUMAN even when the Enforcer is in monitor mode.

Configure as a single regular expression in /pattern/flags form. For case-insensitive matching, end the regex with the i flag.

Filters

These configurations let you filter out certain requests or assets from the Enforcer. These values will be ignored by the Enforcer and will never be blocked.

Filter by HTTP Method
string

Filters out requests with the specified HTTP method to avoid unnecessary traffic in the Enforcer verification flow. Configure as a comma-separated list.

IP Whitelist
string

Filters out requests with the specified IP address to avoid unnecessary traffic in the Enforcer verification flow. Configure IPs or CIDR ranges as a comma-separated list.

Path Whitelist
string

Filters out requests whose Salesforce httpPath matches the configured regular expression. Matched requests are never blocked and do not generate risk or async activities.

Configure as a single regular expression in /pattern/flags form. For case-insensitive matching, end the regex with the i flag.

First party

Enabling first party serves HUMAN client and CAPTCHA files from your domain. First party also requires the Dynamic Mapping rule described in Set up first party.

First Party Enabled
booleanDefaults to false

Whether to enable first party mode for Bot Defender or Sightline Cyberfraud Defense.

HUMAN Challenge customization

These configurations let you customize the HUMAN Challenge block page.

CSS Ref
string

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

Custom Block Page Template
stringDefaults to block_template

The ISML template name used to render the block page. If empty, the cartridge uses block_template. You do not need to include the .isml extension.

To fully customize the block page to match your site theme, copy the cartridge’s custom_block_template.isml and use that copy as the base. Do not edit the default block_template.

The copied template contains the minimum markup required for the Challenge to render:

  • A div element with the ID px-captcha.
  • A script block with the variable declarations needed for the Challenge.

You can customize anything else on the template. Then set this option to the new template name.

string

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

The logo is displayed at the top of the block page. Maximum height is 150px. Width is automatic.

JS Ref
string

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

Mobile support

Enforcers with Mobile Support automatically recognize and handle requests coming from HUMAN’s Mobile SDK. Since mobile apps don’t add cookies as part of HTTP requests, HUMAN sends Risk Cookies as headers instead of cookies. Further, because mobile user-agents can change during the application’s flow, these headers are considered tokens instead of being signed with the user-agent.

This setting also selects which web risk cookie the Enforcer validates (_px2 or _px3).

Token Version
"2" | "3" | "v3"Defaults to v3

The Risk Cookie version number the Mobile SDK can expect from requests from mobile applications.

  • 2: Denotes the Risk Cookie V2 (_px2).
  • 3 or v3 : Denotes the Risk Cookie V3 (_px3).

Monitored routes

These configurations let you specify routes that should be monitored by the Enforcer, which means their requests will never be blocked, even when the Enforcer is in active_blocking mode. This means that these routes will go through the full Enforcer workflow and generate risk and async activities, but all block activities will only be simulated blocks on these routes.

Monitored routes
string

A regular expression of endpoints to be monitored rather than blocked by the Enforcer, even when the Enforcer is in active_blocking mode.

Configure as a single regular expression in /pattern/flags form. For case-insensitive matching, end the regex with the i flag.

SCAPI custom header

SCAPI Custom Header Name
stringDefaults to c_px-headers

When you protect SCAPI (for example, PWA Kit or Composable Storefront), Salesforce does not forward the original client request headers and cookies. Send those original headers in a single custom header whose name matches this setting, or send individual headers prefixed with c_px-.

SCAPI Protection Considerations covers header limitations and how to pass original request headers.

Send activities

Send Block Activities
booleanDefaults to true

Whether to send asynchronous block activities.

Send Page Activities
booleanDefaults to true

Whether the Enforcer sends a page_requested activity for requests that aren’t blocked. Disabling this feature prevents HUMAN from receiving the request data that populates the portal, including how many requests were processed.

Sensitive headers removal

Sensitive Headers
stringDefaults to 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.

Configure as a comma-separated list of header names.

Sensitive routes

These configurations let you specify certain routes that need particularly stringent protection from attacks, such as endpoints that execute payments or handle personal information. Sensitive routes will always trigger a Risk API call even if the request contains a valid, unexpired, low-score cookie.

Requests with high-score cookies won’t send a Risk API call.

For logic that cannot be expressed as a regular expression, use customIsSensitiveRequest.

Sensitive Routes
string

A regular expression for routes that should be considered sensitive.

Configure as a single regular expression in /pattern/flags form. For case-insensitive matching, end the regex with the i flag.

SGJC cartridge name

SGJC Cartridge Name
stringDefaults to app_storefront_controllers

The cartridge name of the site’s SiteGenesis JavaScript Controllers (SGJC) controllers cartridge. The HUMAN SGJC storefront cartridge loads guard and app from this cartridge.

Leave this field empty for SFRA sites. If you use SGJC, set this to your controllers cartridge name.

User identifiers

These configurations let the cartridge read the logged-in Salesforce customer profile and send the customer number, email address, and account creation date on Enforcer activities. They’re closely related to the Accounts and Account Takeover or Fake Account features in Sightline Cyberfraud Defense.

Extract user fields
booleanDefaults to false

Whether to extract user identifiers from the Salesforce customer profile.

Custom functions

These options cannot be set in Business Manager and must instead be edited in int_perimeterx/cartridge/scripts/config/pxCustomFunctionsConfig.js:

  1. Uncomment the function.
  2. Uncomment the matching module.exports line.
  3. Add your logic.
  4. Upload the updated cartridge and deploy in Salesforce.

These functions use Salesforce’s global request object when they need request data.

Additional activity handler

additionalActivityHandler
functionDefaults to null

A custom function the Enforcer runs after sending the page_requested or block activity to the Collector and before forwarding the request to the next step in the pipeline. A common use case is to store the score on the session so storefront code can read it.

Parameters:

  • pxContext: The Enforcer context object
  • config: The HUMAN configuration object

Returns: void

Example
function additionalActivityHandler(pxContext, config) {
session.privacy.PXScore = pxContext.score;
}
module.exports = {
additionalActivityHandler: additionalActivityHandler
};

Custom parameters

These configurations are related to custom parameters.

enrichCustomParameters
functionDefaults to null

Enriches activities sent from the Enforcer to HUMAN with additional custom data. This data can include user information, session IDs, or other data that HUMAN should have access to. There is a limit of 10 custom parameters. Only keys matching custom_param1 through custom_param10 are sent.

Parameters:

  • customParameters: An object that contains custom_param1 through custom_param10

Returns: the custom parameters object

Example
function enrichCustomParameters(customParameters) {
customParameters.custom_param1 = 'test value';
customParameters.custom_param2 = 'second value';
return customParameters;
}
module.exports = {
enrichCustomParameters: enrichCustomParameters
};

Custom sensitive request

customIsSensitiveRequest
functionDefaults to null

This configuration is meant for cases that require more complex logic. We recommend you use Sensitive Routes for most cases.

A custom function that returns whether the current request should be considered sensitive. Sensitive requests always trigger a Risk API call even if they contain a valid cookie.

Parameters: none. Use the Salesforce global request object.

Returns: true if the request is sensitive, otherwise false

Example
function customIsSensitiveRequest() {
return request.getHttpMethod() === 'POST' || request.getHttpMethod() === 'PUT';
}
module.exports = {
customIsSensitiveRequest: customIsSensitiveRequest
};