ASP.NET configuration options

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

...
  appId="<APP_ID>"
...

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.

...
  apiToken="<AUTH_TOKEN>"
...

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.

...
  cookieKey="<COOKIE_SECRET>"
...

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 {0} as a placeholder for your application ID. Change this only after discussing the change with HUMAN Support.

...
  baseUri="https://sapi-{0}.perimeterx.net"
...

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

...
  apiTimeout="1500"
...

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

...
  blockingScore="100"
...

Header name that contains the real client IP. If unset, the Enforcer uses the request’s UserHostAddress.

Configure this when a load balancer or proxy sits in front of your application so HUMAN receives the true client IP for detection.

...
  socketIpHeader="X-PX-TRUE-IP"
...

Whether the Enforcer module is enabled.

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

...
  enabled="true"
...

When true, 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.

When false, the Enforcer returns block responses as needed.

...
  monitorMode="false"
...

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 false. 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.

...
  bypassMonitorHeader="x-px-block"
...

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

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

...
  loginCredentialsExtractionEnabled="true"
...

JSON array of credential extraction definitions, set as an XML attribute string. Each object configures one login endpoint.

When sent_through is custom, configure customCredentialsExtractionHandler. All endpoints with sent_through: "custom" use that handler.

...
  loginCredentialsExtraction='[{"method":"post","path_type":"exact","path":"/login","sent_through":"body","user_field":"username","pass_field":"password"},{"method":"post","path_type":"exact","path":"/login/custom","sent_through":"custom"}]'
...

Credentials Intelligence protocol to use for extracted login data.

• v2: Single-step login
• multistep_sso: Multi-step login

...
  ciVersion="v2"
...

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.

...
  compromisedCredentialsHeader="px-compromised-credentials"
...

Whether to attach the additional_s2s payload and URL as headers on the original request so your origin can enrich and send the activity later. When true, the Enforcer does not send additional_s2s automatically.

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. Set the login_successful and http_status_code fields before sending the activity.

{
  "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.

Send the POST with Content-Type: application/json and Authorization: Bearer <AUTH_TOKEN>.

To send additional_s2s automatically from the Enforcer instead, leave this set to false and configure loginSuccessfulReportingMethod. If the reporting method is left empty, login success is always reported as false.

...
  additionalS2SActivityHeaderEnabled="true"
...

Whether to report the raw username on the additional_s2s activity.

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

...
  sendRawUsernameOnAdditionalS2SActivity="true"
...

Method used to decide whether a login succeeded when the Enforcer sends additional_s2s automatically. If left empty, login success is always reported as false.

...
  loginSuccessfulReportingMethod="status"
  loginSuccessfulStatus="200,201,202"
...

...
  loginSuccessfulReportingMethod="header"
  loginSuccessfulHeaderName="login-successful"
  loginSuccessfulHeaderValue="true"
...

...
  loginSuccessfulReportingMethod="body"
  loginSuccessfulBodyRegex=".*You logged in successfully.*"
...

...
  loginSuccessfulReportingMethod="status"
...

HTTP status codes treated as a successful login when loginSuccessfulReportingMethod is status.

...
  loginSuccessfulStatus="200,201"
...

Regular expression matched against the response body when loginSuccessfulReportingMethod is body.

...
  loginSuccessfulBodyRegex=".*You logged in successfully.*"
...

Response header name checked when loginSuccessfulReportingMethod is header.

...
  loginSuccessfulHeaderName="login-successful"
...

Expected response header value when loginSuccessfulReportingMethod is header.

...
  loginSuccessfulHeaderValue="true"
...

Class name of an ICredentialsExtractionHandler implementation used when a credentials extraction endpoint sets sent_through to custom.

The Handle method receives an HttpRequest and should return an ExtractedCredentials object, or null if extraction fails.

...
  customCredentialsExtractionHandler="MyCredentialsExtractorHandler"
...

namespace myUniqueApp
{
    public class MyCredentialsExtractorHandler : ICredentialsExtractionHandler
    {
        public ExtractedCredentials Handle(HttpRequest httpRequest)
        {
            // Custom credentials extraction logic goes here.
            return new ExtractedCredentials("user", "pass");
        }
    }
}

Class name of an ILoginSuccessfulHandler implementation used when loginSuccessfulReportingMethod is custom.

The Handle method receives an HttpResponse and returns whether the login succeeded.

...
  customLoginSuccessfulHandler="MyLoginSuccessfulHandler"
...

namespace myUniqueApp
{
    public class MyLoginSuccessfulHandler : ILoginSuccessfulHandler
    {
        public bool Handle(HttpResponse httpResponse)
        {
            // Custom implementation resulting in boolean isLoginSuccessful
            return isLoginSuccessful;
        }
    }
}

URL of the custom block page HTML file. The Enforcer automatically allows this URI to avoid infinite redirects.

As of version 2.8.0, CAPTCHA logic is handled by the JavaScript snippet rather than the Enforcer. Custom block pages must include the required script tag and div for the challenge.

...
  customBlockUrl="https://www.example.com/block.html"
...

When true and customBlockUrl is set, blocked users receive a 307 Temporary Redirect to the custom block page, with query parameters such as:

https://www.example.com/block.html?url=L3NvbWVwYWdlP2ZvbyUzRGJhcg==&uuid=e8e6efb0-8a59-11e6-815c-3bdad80c1d39&vid=08320300-6516-11e6-9308-b9c827550d47

The url parameter is the original path and query, URL-encoded and then Base64-encoded, so it does not collide with block-page query parameters.

When false, the Enforcer returns 403 on the blocked request URL and injects the block page content (or custom page content) without requiring those query parameters on your page.

...
  redirectOnCustomUrl="false"
...

When set, the Enforcer reads HUMAN cookies from this header in addition to (or instead of relying solely on) the standard Cookie header.

...
  customCookieHeader="x-px-cookies"
...

Class name of an ICustomParametersHandler implementation. The Enforcer calls Handle before building the payload on requests to HUMAN servers. You can set up to 10 custom parameters (custom_param1 through custom_param10).

The Handle method receives an HttpRequest.

...
  customParametersHandler="CustomParamsImpl"
...

namespace myUniqueApp
{
    public class CustomParamsImpl : ICustomParametersHandler
    {
        public CustomParameters Handle(HttpRequest httpRequest)
        {
            CustomParameters customParams = new CustomParameters();
            customParams.custom_param1 = "example";
            customParams.custom_param2 = "example2";
            return customParams;
        }
    }
}

Header name that contains the client user agent. If unset, the Enforcer uses the incoming request’s User-Agent header.

...
  useragentOverride="px-user-agent"
...

Class name of an IVerificationHandler implementation. When set, the Enforcer calls this handler instead of the default verification behavior so you can customize handling based on the risk score and context.

The Handle method receives:

• HttpApplication application: Current ASP.NET application. Calling CompleteRequest ends the request pipeline after the current event.
• PxContext pxContext: HUMAN context with fields such as Score, UUID, and BlockAction. You can also read data enrichment from pxContext when pxContext.IsPxdeVerified is true.
• PxModuleConfigurationSection pxConfig: Current Enforcer configuration.

...
  customVerificationHandler="UniqueVerificationHandler"
...

namespace myUniqueApp
{
    public class UniqueVerificationHandler : IVerificationHandler
    {
        public void Handle(HttpApplication application, PxContext pxContext, PxModuleConfigurationSection pxConfig)
        {
            if (pxContext.IsPxdeVerified)
            {
                dynamic pxde = pxContext.Pxde;
                // Use data enrichment as needed
            }
            if (pxContext.Score >= pxConfig.BlockingScore)
            {
                PxModule.BlockRequest(pxContext, pxConfig);
                application.CompleteRequest();
            }
        }
    }
}

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

Matching routes go through the full Enforcer workflow, including blocking when necessary.

Compare paths to Request.Url.AbsolutePath with the leading / removed. For example, configure login to match /login. This is an exact match, not a prefix match.

...
  mitigationUrls="login,checkout"
...

When this list is non-empty, the Enforcer runs only on request paths that start with one of the configured prefixes. All other routes are skipped.

...
  enforceSpecificRoutes="/protect/route,/login,/checkout"
...

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.

...
  fileExtWhitelist=".css,.js,.png,.jpg"
...

Filters out requests with the specified IP address to avoid unnecessary traffic in the Enforcer verification flow.

The request IP is resolved with the same logic as detection (socketIpHeader when configured, otherwise the request socket IP). IPv4 and IPv6 are supported.

...
  ipWhitelist="127.0.0.1,10.0.0.0/24"
...

Filters out requests with the specified route to avoid unnecessary traffic in the Enforcer verification flow. Requests to these specified routes will never be blocked regardless of their risk score and will never generate risk or async activities. Primitive string values are treated as path prefixes. For example, /login also matches /login/callback. That is, it uses exact prefix matching on the route via StartsWith().

Does not support regex and is case-sensitive.

...
  routesWhitelist="/health,/assets"
...

Filters out requests with the specified user agent to avoid unnecessary traffic in the Enforcer verification flow. Primitive string values are case-sensitive and require an exact user-agent string.

...
  useragentsWhitelist="GoogleBot,MyInternalMonitor/1.0"
...

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

...
  firstPartyEnabled="true"
...

Whether first-party XHR activity reverse-proxy routes are enabled.

...
  firstPartyXhrEnabled="true"
...

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

...
  cssRef="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"
...

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

...
  jsRef="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"
...

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

...
  customLogo="https://s.perimeterx.net/logo.png"
...

Exact request paths treated as monitor mode even when the Enforcer is actively blocking elsewhere.

Compare paths to Request.Url.AbsolutePath with the leading / removed. For example, configure home to match /home. This is an exact match, not a prefix match.

...
  monitoredRoutes="home,user"
...

Whether to send asynchronous page_requested activities. Sending these activities does not block the request.

...
  sendPageActivities="true"
...

Whether to send asynchronous block activities.

...
  sendBlockActivities="true"
...

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.

...
  sensitiveHeaders="cookie,cookies,x-auth-token"
...

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

...
  sensitiveRoutes="/login,/user/profile"
...