Product guides

Configuration

Suggest Edits

📘

PX_CONFIGS and PX_CUSTOM

Enabling and configuring Enforcer features may require changes to the PX_CONFIGS VCL file, the PX_CUSTOM VCL file, or both. Each code sample below includes the name of the relevant VCL file where the changes should be made. See the instructions for each configuration below for more details.

Required Configurations

px_app_id

The application ID. Required to initialize the Enforcer.

# PX_CONFIGS
table px_configs {
    "px_app_id": "<APP_ID>",
    # ...
}

px_auth_token

The token used for authorization with the Human Security backend. Required to initialize the Enforcer.

# PX_CONFIGS
table px_configs {
    # ...
    "px_auth_token": "<AUTH_TOKEN>",
    # ...
}

px_cookie_secret

The secret used to decrypt the risk cookie. Required to initialize the Enforcer.

# PX_CONFIGS
table px_configs {
    # ...
    "px_cookie_secret": "<COOKIE_SECRET>",
    # ...
}

Generic Enforcer Configurations

px_module_enabled

This boolean serves as an on/off switch for the entire module, providing a way to enable and disable all Enforcer capabilities quickly and easily.

Default: "true"

# PX_CONFIGS
table px_configs {
    # ...
    "px_module_enabled": "false",
    # ...
}

px_module_mode

This feature controls the behavior of the enforcer by changing how it executes certain parts of the workflow. Most notably, different modes allow for analysis and fine-tuning of the enforcer behavior without serving block pages that affect end users.

Possible values:

  • "monitor" - the enforcer will perform all functions without returning block responses
  • "active_blocking" - the enforcer will return block responses when needed

Default: "monitor"

# PX_CONFIGS
table px_configs {
    # ...
    "px_module_mode": "active_blocking",
    # ...
}

px_s2s_timeout

🚧

Note

Adding this value in the px_configs table will not have any effect. Instead, this value can be set in the PX_CONFIGS VCL file under the PX_API backend definition. The connect_timeout, first_byte_timeout, and between_bytes_timeout can all be set to this same value.

The maximum time in milliseconds to wait for the risk API request. If this timeout is reached, the original request will be allowed to pass (fail open).

Default: 1000ms

# PX_CONFIGS
backend PX_API {
    # ...
    .connect_timeout = 2000ms;
    .first_byte_timeout = 2000ms;
    .between_bytes_timeout = 2000ms;
    # ...
}

px_custom_cookie_header

🚧

Previously, this was done via the px_custom_cookie_header_enabled configuration and px_custom_cookie_header subroutine. Both have since been deprecated.

The Enforcer attempts to extract the HUMAN cookies from the Cookie header. If the HUMAN cookies are transferred on a header other than Cookie, the header name should be configured here.

Default: "x-px-cookies"

# PX_CONFIGS
table px_configs {
    # ...
    "px_custom_cookie_header": "x-custom-cookies",
    # ...
}

px_extracted_cookies (access_cookie)

The Enforcer will extract cookies (keys + values) based on the px_custom_extracted_cookies subroutine, in order to add them to the HUMAN backend call as an additional information for the detection mechanism.

Default: "_pxac" (access cookie - see example below)

Access cookie: the enforcer will extract the _pxac cookie automatically (enforcer version 10.2.0+), make sure to include the correct cookie value supplied on your HUMAN Portal on _pxac cookie.

# PX_CUSTOM
sub px_custom_extracted_cookies {
    if (req.http.cookie:_pxac && req.http.req.http.cookie:_pxac != "") {
        set bereq.http.X-PX-ADD-access-cookie = req.http.cookie:_pxac;

   # if (req.http.cookie:{{COOKIE_NAME}} && req.http.cookie: != "") {
  #   set bereq.http.X-PX-{{COOKIE_NAME}} = req.http.cookie:{{COOKIE_NAME}}
  # }
    }
}

🚧

Note

Note 1: that in case custom cookie header is configured, adjust the req.http.cookie to be pointed to the relevant cookie header. example: in case of custom_cookie_header = x-px-cookies, the extracted cookie value should be extracted from req.http.x-px-cookies:{{COOKIE_NAME}}
Note 2: Before adding additional cookies, please contact your HUMAN customer success or advice one of our solution architects

px_secured_pxhd_enabled

Whether the PXHD cookie set on the HTTP response should include the Secure attribute.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_secured_pxhd_enabled": "true",
    # ...
}

px_block_size_exceeded_15k_headers_size

Due to Fastly size limitations, large requests may sometimes result in 413 HTTP errors. If this error is received during a Risk API request, the default Enforcer behavior is to allow the request to pass to the origin. However, if this configuration is enabled, Risk API requests resulting in a 413 response will be blocked instead.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_block_size_exceeded_15k_headers_size": "true",
    # ...
}

px_add_block_result_header

Whether to include the px-ctx:block-result header with value "0" or "1" to origin requests. A header value of "0" means that HUMAN determined the request should pass, while "1" means HUMAN determined the request should be blocked.

Note: This configuration is most often used while in monitor mode for testing and validation.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_add_block_result_header": "true",
    # ...
}

px_additional_activity_handler

px_additional_activity_handler_enabled

Whether to invoke the px_custom_additional_activity_handler subroutine.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_additional_activity_handler_enabled": "true",
    # ...
}

px_custom_additional_activity_handler

A subroutine where custom logic can be performed after sending the page_requested or block activity at the end of the request flow. HUMAN metadata about the request can be found on the req.http.px-ctx header. This subroutine is called in vcl_deliver.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_additional_activity_handler {
    declare local var.score STRING;
    set var.score = if(req.http.px-ctx:pass-reason, "0", "100");

    declare local var.data_enrichment_validated STRING;
    set var.data_enrichment_validated = if(req.http.px-ctx:de-validated == "1", "true", "false");

    log "syslog " req.service_id " CustomLoggingEndpoint :: Score: " var.score ", Data Enrichment: " req.http.px-ctx:data-enrichment ", Data Enrichment Validated: " var.data_enrichment_validated;
}

px_pre_clean

The HUMAN Enforcer stores configurations and metadata on the client request HTTP headers to maintain access to them throughout the Fastly request lifecycle. During invocations of vcl_pass and vcl_miss that happen after the HUMAN enforcement flow, the px_miss and px_pass subroutines invoke logic to clean these HUMAN metadata headers from the backend request to your origin. If desired, you can configure a custom subroutine to run immediately before these HUMAN metadata headers are removed.

px_enable_pre_clean

Whether to invoke the px_custom_pre_clean subroutine.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_enable_pre_clean": "true",
    # ...
}

px_custom_pre_clean

This custom subroutine runs immediately before the HUMAN metadata headers are removed from the backend request. This subroutine is called in vcl_miss and vcl_pass.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_pre_clean {
    set bereq.http.X-Human-Score = if(req.http.px-ctx:pass-reason, "0", "100");
    set bereq.http.X-Human-Uuid = req.http.px-ctx:uuid;
}

px_set_custom_risk_backend_overwrite

A custom subroutine that is called during the Risk API flow to change the backend used for the Risk API request. (This is most often done to adjust the backend timeouts in different regions.) Any HUMAN backends other than PX_API must be defined. If left empty, the default PX_API backend is used. The subroutine is called during vcl_pass only when a Risk API request is necessary.

Default: Empty

Example:

# PX_CUSTOM
backend PX_RISK_API_LOW_TIMEOUT {
    # ...
}

sub px_set_custom_risk_backend_overwrite {
    if (server.region !~ {"US"}) {
        set req.backend = PX_RISK_API_LOW_TIMEOUT;
    }
}

px_custom_add_custom_parameters

This subroutine defines custom parameters that are sent to HUMAN on the Risk API and asynchronous activities. The custom parameters must be set in the HUMAN Portal before implementing this subroutine.

Custom parameters can be added by setting a client request header with the name px-custom-param:<NUMBER>, where <NUMBER> corresponds to the custom parameter number between 1-10.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_add_custom_parameters {
    set req.http.px-custom-param:1 = "test1";
    set req.http.px-custom-param:2 = "test2";
    set req.http.px-custom-param:3 = "3";
    set req.http.px-custom-param:4 = "4";
    set req.http.px-custom-param:5 = "5";
    set req.http.px-custom-param:6 = "6";
}

px_custom_data_enrichment_handler

A custom subroutine for handling data enrichment data. This subroutine is called in vcl_recv once the data enrichment value from either the cookie or the Risk API response has been parsed. For more information on data enrichment, see here.

Useful Headers:

  • req.http.px-ctx:data-enrichment - A string in JSON format containing the enrichment data.
  • req.http.px-ctx:de-validated - A boolean value ("1" or "0") indicating whether the data enrichment value can be trusted.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_data_enrichment_handler {
    set req.http.Human-Data-Enrichment-F-Type = if (req.http.px-ctx:data-enrichment ~ {""f_type":"([^"]*)"}, re.group.1, "");
}

px_custom_activity_headers

Fastly VCL limitations prevent the HUMAN Enforcer from reporting all request headers on the async activities. If there are additional headers that should be reported, they can be added to the async activities by implementing this custom subroutine.

The subroutine should return a string representing all headers that should be added to the async activities. Every header should be added in the following form, replacing <header_name> with the desired header. Note: The leading comma is very important!

",{%22name%22: %22<header name>%22, %22value%22: " if(req.http.<header name>, "%22" json.escape(req.http.<header name>) "%22", "null") "}"

Default: Returns ""

Example:

# PX_CUSTOM
sub px_custom_activity_headers STRING {
    declare local var.ret STRING;
    set var.ret =
        ",{%22name%22: %22my-header%22, %22value%22: " if(req.http.my-header, "%22" json.escape(req.http.my-header) "%22", "null") "}"
        ",{%22name%22: %22my-header-1%22, %22value%22: " if(req.http.my-header-1, "%22" json.escape(req.http.my-header-1) "%22", "null") "}"
        ",{%22name%22: %22my-header-2%22, %22value%22: " if(req.http.my-header-2, "%22" json.escape(req.http.my-header-2) "%22", "null") "}"
        ",{%22name%22: %22my-header-3%22, %22value%22: " if(req.http.my-header-3, "%22" json.escape(req.http.my-header-3) "%22", "null") "}";
    return var.ret;
}

px_override_configs

🚧

Whenever possible, configuration values should be set in the px_configs table rather than adjust them during runtime.

A custom subroutine that allows for adjusting the HUMAN configuration based on runtime values. See the PX VCL file for the list of req.http.px-cfg configuration header values that can be modified.

Default: Empty

Example:

# PX_CUSTOM
sub px_override_configs {
    if (client.geo.country_code == "GB") {
        set req.http.px-cfg:css-ref = "https://example.co.uk/style.css";
    }
}

px_custom_check_block_by_size

❗️

Deprecated

This configuration is deprecated.

px_custom_check_block_post_url

❗️

Deprecated

This configuration is deprecated.

First Party Configurations

px_first_party_enabled

To prevent suspicious or unwanted behavior on the client side, some browsers or extensions (e.g., adblockers) may deny the frontend JavaScript code from making requests to other domains. This prevents the Human Security sensor from making requests to the Human Security backends, which greatly limits Human Security's detection capabilities. To avoid this problem, first party enables the enforcer to be used as a proxy for Human Security servers, and to serve content to the browser from a first party endpoint (i.e., an endpoint on the customer’s domain).

Default: "true"

# PX_CONFIGS
table px_configs {
    # ...
    "px_first_party_enabled": "false",
    # ...
}

px_enable_redirect_xhr

First party requests include JavaScript resource (like the HUMAN Sensor and Captcha scripts), but they can also apply to XHR requests sent by the HUMAN Sensor. If you would like to disable first party for XHR requests only and leave other first party functionality enabled, you may set this value to be false.

Default: "true"

# PX_CONFIGS
table px_configs {
    # ...
    "px_enable_redirect_xhr": "false",
    # ...
}

px_custom_first_party_sensor_endpoint

For an application with ID PX12345678, the first party sensor endpoint is /12345678/init.js by default. This configuration customizes the entire first party sensor script endpoint. Note that in addition to responding to requests that match this configured route, the enforcer will also proxy first party requests that match the default pattern (/12345678/init.js).

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_custom_first_party_sensor_endpoint": "/human_sensor",
    # ...
}

px_custom_first_party_response_modifier

A custom subroutine for modifications to first party responses. This subroutine is called in vcl_deliver, so changes to the response should be made with the client response object.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_first_party_response_modifier {
    unset resp.http.Access-Control-Allow-Origin;
    set resp.http.Strict-Transport-Security = "max-age=86400";
}

px_custom_redirect

❗️

Deprecated

This configuration is deprecated. To perform redirects without invoking HUMAN enforcement logic, include your desired logic before the invocation of px_recv.

Logging Configurations

px_async_activities_logger

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

The name of the logging endpoint used to send asynchronous activities.

Default: "PX-Async-Activities"

# PX_CONFIGS
table px_configs {
    # ...
    "px_async_activities_logger": "Human-Async-Activities",
    # ...
}

px_telemetry_activity_logger

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

The name of the logging endpoint used to send telemetry activities.

Default: "PX-Telemetry"

# PX_CONFIGS
table px_configs {
    # ...
    "px_telemetry_activity_logger": "Human-Telemetry",
    # ...
}

px_logger_severity

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

The verbosity of the logs generated by the enforcer.

Possible values:

  • "none" - No logs will be generated
  • "error" - Sparse logs will be sent to the logging endpoint name set by the px_error_syslog_name configuration only when errors occur
  • "debug" - Detailed logs will be sent to the logging endpoint name set by the px_debug_syslog_name configuration (not advisable for production environments)

Default: "error"

# PX_CONFIGS
table px_configs {
    # ...
    "px_logger_severity": "debug",
    # ...
}

px_enable_error_logs

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

Whether error logs should be sent to the error logging endpoint.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_enable_error_logs": "true",
    # ...
}

px_debug_syslog_name

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

The name of the logging endpoint to which debug logs will be sent.

Default: "PX-Debug"

# PX_CONFIGS
table px_configs {
    # ...
    "px_debug_syslog_name": "Human-Debug",
    # ...
}

px_error_syslog_name

See the instructions for adding optional logging to your Fastly service here.

The name of the logging endpoint to which error logs will be sent.

Default: "PX-Error"

# PX_CONFIGS
table px_configs {
    # ...
    "px_error_syslog_name": "Human-Error",
    # ...
}

px_debug_probability

📘

See the instructions on adding the required logging endpoints to your Fastly service here.

Sometimes, logging every request to the service is impractical, and a random sample of logs is preferable. This configuration can be used to specify the likelihood of a log being generated for an incoming request. One out of every X requests will result in logs, where X is the number configured here. That is, setting this value to "2" means 1 out of every 2 requests, or a 50% chance; setting "100" means 1 out of every 100 requests, or a 1% chance.

Default: "1"

# PX_CONFIGS
table px_configs {
    # ...
    "px_debug_probability": "100",
    # ...
}

Filtering Configurations

px_filter_by_extension

Human Security does not enforce static assets such as images and documents. To prevent unnecessary API calls to Human Security servers and needless computation, the enforcer filters all requests with a valid static file extension.

px_filter_by_extension_enabled

Whether to invoke the px_custom_filter_by_extension function to check for filtered extensions.

Default: "true"

# PX_CONFIGS
table px_configs {
    # ...
    "px_filter_by_extension_enabled": "false",
    # ...
}

px_custom_filter_by_extension

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to the file extension in its URL. A return value of false means the request should proceed with the usual enforcement flow.

Default:

# PX_CUSTOM
sub px_custom_filter_by_extension BOOL {
      if ((req.request == "GET" || req.request == "HEAD") && req.url.ext ~ "^(css|bmp|tif|ttf|docx|woff2|js|pict|tiff|eot|xlsx|csv|eps|woff|xls|jpeg|jpg|doc|ejs|otf|pptx|gif|pdf|swf|svg|ps|ico|pls|midi|svgz|class|png|ppt|mid|webp|jar)$") {
        return true;
    }
    return false;
}

px_filter_by_http_method

Filters out requests according to their HTTP method, avoiding unnecessary traffic in the enforcer verification flow and reducing operating costs.

px_filter_by_http_method_enabled

Whether to invoke the px_custom_filter_by_http_method function to check for filtered HTTP methods.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_filter_by_http_method_enabled": "true",
    # ...
}

px_custom_filter_by_http_method

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to its HTTP method. A return value of false means the request should proceed with the usual enforcement flow.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_filter_by_http_method BOOL {
    if (req.request ~ "(?i)(GET|POST|HEAD)$") {
        return true;
    }
    return false;
}

px_filter_by_ip

Filters out requests according to their IP address, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs.

px_filter_by_ip_enabled

Whether to invoke the px_custom_filter_by_ip function to check for filtered IPs.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_filter_by_ip_enabled": "true",
    # ...
}

px_custom_filter_by_ip

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to its IP. A return value of false means the request should proceed with the usual enforcement flow.

📘

Using Fastly ACLs

The easiest way to implement this subroutine is to declare and use a Fastly Access Control List (ACL) as shown in the example below. For more information, see here.

Default: Returns false.

Example:

# PX_CUSTOM
acl Filtered_IPs {
    "123.123.123.123";
    "12.12.12.0"/24;
}

sub px_custom_filter_by_ip BOOL {
    if (req.http.Fastly-Client-IP ~ Filtered_IPs) {
        return true;
    }
    return false;
}

px_filter_by_route

Filters out requests according to their URLs. A request to a filtered route will not undergo enforcement flow, and it will not generate any risk or async activities.

px_custom_filter_by_route

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to its route. A return value of false means the request should proceed with the usual enforcement flow.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_filter_by_route BOOL {
     if (req.url.path ~ {"^/prefix|^/exact/match$"}) {
        return true;
    }
    return false;
}

px_filter_by_user_agent

Filters out requests according to their user agent value, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs.

px_filter_by_user_agent_enabled

Whether to invoke the px_custom_filter_by_user_agent function to check for filtered user agents.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_filter_by_user_agent_enabled": "true",
    # ...
}

px_custom_filter_by_user_agent

A custom subroutine that returns a boolean value. A return value of true means the request should be filtered from the enforcement flow due to its user agent. A return value of false means the request should proceed with the usual enforcement flow.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_filter_by_user_agent BOOL {
    if (req.http.User-Agent ~ {"Filtered_UA"}) {
        return true;
    }
    return false;
}

px_filter_on_cache_hit_enabled

Filters out requests if the requested resource results in a cache HIT at the edge POP. If shielding is enabled, a request that results in a cache MISS at the edge POP will undergo enforcement even if it results in a cache HIT at the shield POP. For more information about Fastly Shielding, see here.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_filter_on_cache_hit_enabled": "true",
    # ...
}

Special Routes Configurations

px_custom_enforced_routes

Customers may want certain, but not all, endpoints to be enforced by HUMAN, even when the Enforcer is in monitor mode. This custom subroutine returns a boolean value indicating whether the request is an enforced route.

A return value of true means the request should go through the full enforcer workflow, including blocking when necessary. That is, even when the enforcer is in monitor mode, these requests will behave as if in active blocking mode. A return value of false means the request should proceed with the usual flow based on the module mode.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_enforced_routes BOOL {
    if (req.url.path ~ {"^/enforced|^/non/monitored/route$"}) {
        return true;
    }
    return false;
}

px_custom_monitored_routes

Enables certain endpoints to be monitored rather than enforced by HUMAN, even when the enforcer is in active blocking mode.

A return value of true means the request should go through the enforcement flow in monitor mode. That is, even when the enforcer is in active_blocking mode, these requests will behave as if in monitor mode. A return value of false means the request should proceed with the usual flow based on the module mode.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_monitored_routes BOOL {
    if (req.url.path ~ {"^/monitored|^/non/enforced/route$"}) {
        return true;
    }
    return false;
}

px_bypass_monitor_header

When enabling the enforcer for the first time, it is recommended to do so in monitor mode to collect data before actually starting to block user requests. Prior to switching the module mode to active_blocking entirely, it's also crucial to verify that the full blocking flow works as expected. This feature activates the full blocking flow even while in monitor mode if a particular header is present on the request.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_bypass_monitor_header": "x-px-block",
    # ...
}

px_custom_check_sensitive_route

Certain endpoints may require more stringent protection from bot attacks (e.g., endpoints that execute payments or handle personal information). In these cases, this subroutine can be implemented. If the subroutine returns true, a Risk API call will be made even if the request contains a valid, unexpired cookie. If the subroutine returns false, the enforcer will use the value found in the valid, unexpired cookie.

Default: Returns false.

Example:

# PX_CUSTOM
sub px_custom_check_sensitive_route BOOL {
    if (req.url.path ~ {"^/login"}) {
        return true;
    }
    return false;
}

px_sensitive_headers

The HUMAN detector requires information about the HTTP request as part of its bot detections. Certain headers may contain information that should not be forwarded to other servers, including the HUMAN backend. Setting these configurations will remove the headers from requests sent to HUMAN.

Note: The Cookie header is always removed from backend requests to HUMAN whether this feature is enabled or not.

px_sensitive_headers_enabled

Whether to invoke the px_custom_unset_sensitive_headers function to unset sensitive headers prior to requests to the HUMAN backend.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_sensitive_headers_enabled": "true",
    # ...
}

px_custom_unset_sensitive_headers

A custom subroutine that is invoked prior to requests to the HUMAN backend to remove sensitive headers. This subroutine is called in vcl_pass, so headers should be unset from the bereq object.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_unset_sensitive_headers {
    unset bereq.http.X-Sensitive-Token;
}

px_custom_check_enabled_route

A custom subroutine that returns a boolean indicating whether the module should be enabled for certain requests. This subroutine only has an effect if the px_module_enabled configuration is set to "false".

Default: Returns false

Example:

# PX_CUSTOM
sub px_custom_check_enabled_route BOOL {
    if (req.url.path ~ {"^/prefix|^/exact/match$"}) {
        return true;
    }
    return false;
}

Custom Blocking Configurations

px_css_ref

Provides a way to include an additional custom .css file to add to the captcha page.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_css_ref": "https://www.example.com/custom_style.css",
    # ...
}

px_js_ref

Provides a way to include a custom JS script to add to the captcha page. This script will run after the default JS scripts.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_js_ref": "https://www.example.com/custom_script.js",
    # ...
}

px_custom_logo

Adds a custom logo to the captcha page that will be shown to users. This aligns the captcha page with the customer's brand.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_custom_logo": "https://www.example.com/custom_logo.png",
    # ...
}

px_enable_captcha

Provides more fine-tuned control of which block responses are returned. When set to "true", the px_custom_captcha_handler will be invoked if HUMAN has decided a captcha response is necessary; otherwise, the px_custom_block_handler will be invoked. When set to "false", the px_custom_block_handler will be invoked always.

Default: "true"

# PX_CONFIGS
table px_configs {
    # ...
    "px_enable_captcha": "false",
    # ...
}

px_custom_rate_limit_block_page

A subroutine that allows for customizing the rate limit block response. This will be invoked only if HUMAN has decided to return a 429 Too Many Requests response. This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_rate_limit_block_page {
    set obj.http.Response-Header = "Value";
}

px_custom_create_block_page

A custom subroutine that returns a string representing the HTML response body to be returned on the block response. Returning an empty value will result in the default HTML block page.

Default: Returns ""

Example:

# PX_CUSTOM
sub px_custom_create_block_page STRING {
    declare local var.ret STRING;
    set var.ret = "<!DOCTYPE html><html><head><title>Access Denied</title></head><body><h1>You have been blocked.</h1></body></html>";
    return var.ret;
}

px_custom_block_handler

A custom subroutine that will be called if (1) px_enable_captcha is set to "false", or (2) HUMAN decided to return a non-captcha response. This subroutine must set all properties of the block response you wish to generate. This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

🚧

This subroutine should always end with a return(deliver); statement to prevent the error flow from continuing.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_block_handler {
    synthetic {"You have been blocked."};
    set obj.status = 403;
    set obj.response = "Forbidden";
    set obj.http.Content-Type = "text/plain";
    return(deliver);
}

px_custom_captcha_handler

A custom subroutine that will be called if (1) px_enable_captcha is set to "true", and (2) HUMAN decided to return a captcha response. This subroutine must set all properties of the captcha response you wish to generate. This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

🚧

This subroutine should always end with a return(deliver); statement to prevent the error flow from continuing.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_captcha_handler {
    synthetic {"<!DOCTYPE html><html><head><title>Unauthorized</title></head><body><script src="custom/captcha.js"></script></body></html>"};
    set obj.status = 401;
    set obj.response = "Unauthorized";
    set obj.http.Content-Type = "text/html";
    return(deliver);
}

px_custom_post_block_handler

❗️

Deprecated

This configuration is deprecated. Please use px_custom_block_handler or px_custom_captcha_handler instead.

px_custom_create_advanced_blocking_response

A subroutine that allows for customization of the JSON captcha response. This is applicable to the JSON captcha response only! This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_create_advanced_blocking_response {
    set obj.status = 401;
    set obj.response = "Unauthorized";
    set obj.http.Response-Header = "Value";
}

px_custom_create_synthetic_web_response

A subroutine that allows for customization of the HTML browser captcha response. This is applicable to the HTML captcha response only! This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_create_synthetic_web_response {
    set obj.http.Is-Web-Block = "1";
}

px_custom_create_synthetic_mobile_response

🚧

The HUMAN Mobile SDK expects mobile captcha responses to have a certain structure. Exercise caution when making modifications to the mobile captcha response so as not to break this protocol.

A subroutine that allows for customization of the mobile captcha response. This is applicable to the mobile captcha response only! This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_create_synthetic_mobile_response {
    set obj.http.Is-Mobile-Block = "1";
}

CORS Configurations

CORS (Cross-Origin Resource Sharing) is a mechanism that enables the server to indicate when a request contains cross-origin resources. It does so by adding special HTTP headers to the request, which permits the browser to load these resources. Without these headers, the browser may block requests to these resources for security reasons.

In most cases, CORS employs a two-stage procedure with a preliminary "preflight" request followed by the actual request. The preflight request checks if the actual request will be responded to. To learn more about different request types, see these examples.

In the HUMAN Enforcer, CORS behavior must be configured to address both simple requests (without preflight) and more complex ones (with preflight).

px_cors_support_enabled

Enabling CORS support via this configuration will have the following effects:

  • It will automatically add the following default CORS response headers to block responses resulting from CORS requests.
Access-Control-Allow-Origin: <ORIGIN_REQUEST_HEADER_VALUE>
Access-Control-Allow-Credentials: true
  • It will permit enabling the px_cors_create_custom_block_response_headers configuration, which will allow for customizing the block response headers via a custom function.
  • It will permit enabling the px_cors_preflight_request_filter_enabled and px_cors_custom_preflight_handler configurations, which allow for filtering and custom handling of preflight requests.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_cors_support_enabled": "true",
    # ...
}

px_cors_preflight_request_filter_enabled

🚧

If both the px_cors_preflight_request_filter_enabled and px_cors_preflight_handler_enabled are set to true, the custom preflight handler will take priority and invoke the px_custom_cors_preflight_handler from the VCL error stage.

This configuration disables enforcement for CORS preflight requests. When this configuration is set to true, CORS preflight requests will be filtered from the enforcer flow. That is, they will pass through the enforcer flow without triggering detection or block responses.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_cors_preflight_request_filter_enabled": "true",
    # ...
}

px_cors_preflight_handler

If a more customized approach is needed for handling CORS preflight requests, these configurations can be set to define the desired behavior.

px_cors_preflight_handler_enabled

🚧

If both the px_cors_preflight_request_filter_enabled and px_cors_preflight_handler_enabled are set to true, the custom preflight handler will take priority and invoke the px_custom_cors_preflight_handler from the VCL error stage.

Whether to invoke the px_custom_cors_preflight_handler subroutine. This is done by triggering a specific error with an error statement.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_cors_preflight_handler_enabled": "true",
    # ...
}

px_custom_cors_preflight_handler

A custom subroutine for defining the desired CORS preflight response. This subroutine is called in vcl_error, so changes to the response should be made with the cache object type and the synthetic statement.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_cors_preflight_handler {
    set obj.status = 204;
    set obj.http.Access-Control-Allow-Origin = req.http.Origin;
    set obj.http.Access-Control-Allow-Methods = req.method;
    set obj.http.Access-Control-Allow-Headers = req.http.Access-Control-Request-Headers;
    set obj.http.Access-Control-Allow-Credentials = "true";
    set obj.http.Access-Control-Max-Age = "86400";
}

px_cors_create_custom_block_response_headers

If the default CORS response headers are not sufficient, these configurations can be used to completely customize the headers that should be added to all block responses resulting from CORS requests. If this function is defined, the default headers will not be added; instead, the custom subroutine will be invoked.

px_cors_create_custom_block_response_headers_enabled

Whether to invoke the px_custom_cors_set_custom_block_response_headers subroutine. If set to "true", the px_custom_cors_set_custom_block_response_headers subroutine will be invoked on block responses to CORS requests. If set to "false", then the default CORS response headers (Access-Control-Allow-Origin: req.http.Origin and Access-Control-Allow-Credentials: true) will be added to block responses.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_cors_create_custom_block_response_headers_enabled": "true",
    # ...
}

px_custom_cors_set_custom_block_response_headers

A custom subroutine for adding any desired headers to block responses to CORS requests. This subroutine is called in vcl_error, so changes to the response should be made with the cache object type.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_cors_set_custom_block_response_headers {
    set obj.http.Access-Control-Allow-Origin = req.http.Origin;
    set obj.http.Access-Control-Allow-Credentials = "true";
    set obj.http.Access-Control-Allow-Methods = "GET, POST, OPTIONS";
    set obj.http.Access-Control-Allow-Headers = "Content-Type, Authorization";
}

px_enable_access_control_header

❗️

Deprecated

This configuration is deprecated. If you want to make customizations to block responses only when the incoming request is a CORS request, please use the px_cors_create_custom_block_response_headers_enabled and px_custom_cors_set_custom_block_response_headers configurations instead. If you want to make customizations to block responses in all cases, please use the px_custom_create_synthetic_web_response, px_custom_create_synthetic_mobile_response, and px_custom_create_advanced_blocking_response configurations instead.

px_custom_access_control_header

❗️

Deprecated

This configuration is deprecated. If you want to make customizations to block responses only when the incoming request is a CORS request, please use the px_cors_create_custom_block_response_headers_enabled and px_custom_cors_set_custom_block_response_headers configurations instead. If you want to make customizations to block responses in all cases, please use the px_custom_create_synthetic_web_response, px_custom_create_synthetic_mobile_response, and px_custom_create_advanced_blocking_response configurations instead.

GraphQL Configurations

px_graphql_enabled

Whether the enforcer should attempt to parse and report information about GraphQL operations on incoming requests.

Default: "true"

# PX_CONFIGS
table px_configs {
    # ...
    "px_graphql_enabled": "false",
    # ...
}

px_custom_is_graphql_route

A custom subroutine that returns a boolean indicating whether the request should be parsed as a GraphQL request. If px_graphql_enabled is "true" and this subroutine returns true, the enforcer will attempt to parse the request body for GraphQL data. If this subroutine returns false, the enforcer will not attempt to extract GraphQL data.

Default:

# PX_CUSTOM
sub px_custom_is_graphql_route BOOL {
    if (req.url.path ~ {"/graphql"}) {
        return true;
    }
    return false;
}

px_sensitive_graphql_operation_types

A space-separated list of operation types (query, mutation, or subscription) that should be considered sensitive. If one or more GraphQL operations on an HTTP request is found to have a type matching the list configured here, it will trigger a Risk API call even if the request contains a valid, unexpired cookie.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_sensitive_graphql_operation_types": "mutation subscription",
    # ...
}

px_sensitive_graphql_operation_names

A space-separated list of operation names that should be considered sensitive. If one or more GraphQL operations on an HTTP request is found to have a name matching the list configured here, it will trigger a Risk API call even if the request contains a valid, unexpired cookie.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_sensitive_graphql_operation_names": "SensitiveOperation1 SensitiveOperation2",
    # ...
}

px_custom_check_sensitive_graphql_operation

📘

This configuration should be used in cases that require more complex logic than allowed by the px_sensitive_graphql_operation_types and px_sensitive_graphql_operation_names configurations.

A custom subroutine that returns a boolean indicating whether the request should be treated as sensitive given the GraphQL data that was extracted by the enforcer.

Extracted data:

  • req.http.px-graphql:operation-type - The GraphQL operation type (query, mutation, subscription) on the request
  • req.http.px-graphql:operation-name - The GraphQL operation name on the request

Default: Returns false

Example:

# PX_CUSTOM
sub px_custom_check_sensitive_graphql_operation BOOL {
    if (req.http.px-graphql:operation-type ~ "mutation" || req.http.px-graphql:operation-name ~ "SensitiveOperation") {
        return true;
    }
    return false;
}

Account Defender Configurations

px_jwt_cookie_name

The name of the cookie that contains the JWT token from which user identifiers should be extracted.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_jwt_cookie_name": "auth",
    # ...
}

px_jwt_cookie_user_id_field_name

The field name in the JWT object, extracted from the JWT cookie, that contains the user ID to be extracted and reported.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_jwt_cookie_user_id_field_name": "nameID",
    # ...
}

px_jwt_header_name

The name of the header that contains the JWT token from which user identifiers should be extracted.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_jwt_header_name": "x-jwt-authorization",
    # ...
}

px_jwt_header_user_id_field_name

The field name in the JWT object, extracted from the JWT header, that contains the user ID to be extracted and reported.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_jwt_header_user_id_field_name": "sub",
    # ...
}

px_custom_extract_jwt_additional_fields

A custom subroutine that extracts any additional desired field names and values in the JWT object. The subroutine should set the client request header px-jwt:additional-fields to a valid JSON string in the format of {"<field_name_1>": "<field_value_1>", "field_name_2": "field_value_2"}. The values can be extracted from the decoded JWT token available on the header req.http.px-jwt:token-decoded.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_extract_jwt_additional_fields {
    declare local var.fieldValue1 STRING;
    if (req.http.px-jwt:token-decoded ~ {"("fieldName1":"[^"]*")"}) {
        set var.fieldValue1 = if(re.group.1, re.group.1, "");
    }
    set req.http.px-jwt:additional-fields = "{\"fieldName1\":\"" var.fieldValue1 "\"}";
}

Remote Config Configurations

px_remote_config_id

The ID associated with the remote configuration for the application.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_remote_config_id": "<REMOTE_CONFIG_ID>",
    # ...
}

px_remote_config_secret

A secret key to use in the authentication of incoming Remote Config update requests.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_remote_config_secret": "<REMOTE_CONFIG_SECRET>",
    # ...
}

px_enforcer_config_rdata

This table exists in the PX_CUSTOM VCL file. If the Remote Config feature is enabled, this table declaration should be removed and an empty Fastly dictionary with the same name should be added instead.

cs_data

This table exists in the PX_CUSTOM VCL file. This table declaration may be removed and a Fastly dictionary with the same name can be added instead.

In the cs_data Fastly table (or dictionary), two entries should be added:

Key NameValue
eng_keyThe Fastly API key with permissions to make changes to the Fastly service. (The scope must be global, but it only needs permissions for the specific Fastly service.) This allows HUMAN to make updates to the Remote Config values. You can create an API token via the Fastly Console, CLI, or API.
px_enforcer_config_rdata_idThe dictionary ID associated with the px_enforcer_config_rdata dictionary. You can determine the dictionary ID via CLI or API.

CSP Configurations

px_csp_enabled

Whether to enable the CSP feature. This feature adds the Content-Security-Policy and Content-Security-Policy-Report-Only headers to the HTTP responses. The values of these headers are updated by the Code Defender product.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_csp_enabled": "true",
    # ...
}

px_remote_data_enabled

This configuration enables receiving updates to CSP values from the HUMAN backend. If px_csp_enabled is enabled, this configuration should be enabled as well.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_remote_data_enabled": "true",
    # ...
}

px_custom_csp_enabled_routes

A custom subroutine to determine which routes to enable CSP for. If the request should receive an HTTP response with the CSP and CSPRO headers, then this subroutine should set the req.http.csp_enabled_route header to "1".

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_csp_enabled_routes {
    if (req.url.path ~ ".*") {
        set req.http.csp_enabled_route = "1";
    }
}

px_csp_rdata

This table exists in the PX_CUSTOM VCL file. If the CSP feature is enabled, this table declaration should be removed and an empty Fastly dictionary with the same name should be added instead.

cs_data

This table exists in the PX_CUSTOM VCL file. If the CSP feature is enabled, this table declaration should be removed and a Fastly dictionary with the same name should be added instead.

In the cs_data Fastly dictionary, two values should be added:

Key NameValue
eng_keyThe Fastly API key with permissions to make changes to the Fastly service. This allows HUMAN to make updates to the CSP values.
px_csp_rdata_idThe ID associated with the px_csp_rdata dictionary.

Credential Intelligence Configurations

The Credential Intelligence product allows customers to safeguard their users' login information by leveraging HUMAN's database of compromised credentials.

The enforcer plays a major role in the Credential Intelligence process as it is in charge of extracting and sending to Credential Intelligence an anonymized, hashed, and salted version of the credentials in real-time and provides a real-time response whether the credentials are compromised or not. (This requires enablement of the Data Enrichment feature.)

px_login_credentials_extraction_enabled

This enables the extraction and reporting of credentials from the Enforcer. This must be set to "true" to enable the Credential Intelligence product.

Default: false

# PX_CONFIGS
table px_configs {
    # ...
    "px_login_credentials_extraction_enabled": "true",
    # ...
}

px_login_credentials_extraction

A table detailing the settings for each credential endpoint. Each element in the array is an object representing a distinct endpoint to which credentials are sent, and includes information about how to identify these credential-bearing requests and how to extract the credentials from the request.

For each endpoint, define a credential entpoint suffix (e.g., _0, _1) and add this suffix to the keys corresponding to that endpoint (e.g., path_0, method_0, path_1, method_1). For more information, see the px_custom_is_login_request subroutine.

This table exists in the PX_CUSTOM VCL file. This table can be filled in or it may be removed in favor of a Fastly dictionary with the same name.

Default: Empty

# PX_CUSTOM
table px_login_credentials_extraction {
    # endpoint _0
    "path_0": "/login",
    "protocol_0": "v2",
    "method_0": "post",
    "sent_through_0": "body",
    "pass_field_0": "password",
    "user_field_0": "username",

    # endpoint _1
    "path_1": "/sign-up",
    "protocol_1": "multistep_sso",
    "method_1": "post",
    "use_callback_1": "1",
}

Each credential endpoint configuration object contains the following fields:

path

Required. The path of the request that contains the credentials. (If you need to use a regular expression instead of an exact path, you can do so in the px_custom_is_login_request subroutine.)

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "path_0": "/login",
    # ...
}

method

Required. The HTTP method of the request that contains the credentials. Supported methods are "post" and "put".

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "method_0": "post",
    # ...
}

sent_through

Required only if use_callback is not 1. Whether the credentials should be extracted from the request body.

Possible values:

  • "body" - The credentials will be extracted according to the configured user_field and pass_field values from the request body. Please notice that body limit is 8K (see Fastly docs).
# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "sent_through_0": "body",
    # ...
}

📘

The Enforcer parses the request body based on the Content-Type request header. Supported Content-Type values are:

  • application/json
  • application/x-www-form-urlencoded

To support other content types, set the use_callback key to 1 and define a px_custom_login_extraction_callback to extract the credentials from the request as desired.

user_field

Required only if sent_through is set to "body".

The name of the field, header name, or query parameter where the username can be found.

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "sent_through_0": "body",
    "user_field_0": "username",
    # ...
}

pass_field

Required only if sent_through is set to "body".

The name of the field, header name, or query parameter where the password can be found.

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "sent_through_0": "body",
    "pass_field_0": "password",
    # ...
}

📘

Nested Objects in a JSON Body

The user_field and pass_field configurations support Content-Type: application/json bodies with nested objects. The configurations need only include the specific key names associated with the desired values. Any higher-level keys can be ignored.

For example, the table can include a user_field with the value "username" and a pass_field with the value "password" to support extracting the credentials from the following JSON body. There is no need to include the higher-level fields (i.e., "user_info" or "authentication") in the configurations.

{
    "user_info": {
        "username": "user123"
    },
    "authentication": {
        "password": "P@s$w0rD!"
    }
}

use_callback

Required only if sent_through is not set.

This field can be set to "1" instead of the sent_through field to indicate that for this endpoint, the credentials will be extracted by invoking the px_custom_login_extraction_callback subroutine. This may be used for multiple credential endpoints. The only possible value for this field is "1".

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "use_callback_0": "1",
    # ...
}

protocol

Optional. Whether to process credentials as part of single or multiple HTTP requests. By default, the module tries to process requests depending on which credential fields were extracted.

Possible values:

  • "v2" - Both username and password are present on the same HTTP request and must be extracted successfully to trigger Credential 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 Credential Intelligence.
  • "both" - The username and password may be present on the same HTTP request or on different HTTP requests. If either username or password is successfully extracted, the Enforcer will send the credentials according to the multistep_sso protocol. If both username and password are successfully extracted, the Enforcer will send the credentials according to the v2 protocol.

Default: "both"

# PX_CUSTOM
table px_login_credentials_extraction {
    # ...
    "protocol_0": "v2",
    # ...
}

px_custom_is_login_request

A custom subroutine that sets the correct credential endpoint suffix according to the the request URL. That is, this subroutine should set the req.http.login-set header to the credential endpoint suffix (e.g., _0, _1) that corresponds with the request's path.

You may use the path values in the px_login_credentials_extraction table if an exact match is needed, or you may use a regular expression as desired.

Default:

# PX_CUSTOM
sub px_custom_is_login_request {
    unset req.http.login-set;

    if (req.url.path == table.lookup(px_login_credentials_extraction, "path_0")) {
        set req.http.login-set = "_0";
    # } else if (req.url.path ~ "^/sign-up") {
    #     req.http.login-set = "_1";
    }
}

px_custom_login_extraction_callback

A custom subroutine to extract the raw username and password from the request. All login extraction endpoints will use this same subroutine if their use_callback value is set to "1". Use the req.http.login-set header, which has the value of the credential endpoint suffix (e.g., _0, _1), to differentiate between the endpoints.

Set the req.http.px-creds:raw-username header value to the raw username and the req.http.px-creds:raw-password header value to the raw password extracted from the request.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_login_extraction_callback {
    declare local var.username STRING;
    declare local var.password STRING;

    if (req.http.login-set == "_1") {
        # extract from req and set to local variables
        # set var.username = ...;
        # set var.password = ...;
    }

    if (var.username) {
        set req.http.px-creds:raw-username = var.username;
    }
    if (var.password) {
        set req.http.px-creds:raw-password = var.password;
    }
}

px_credentials_intelligence_version

❗️

Deprecated

This configuration is deprecated. Set the Credential Intelligence protocol on a per-endpoint basis by adding the protocol field in the px_login_credentials_extraction table.

px_login_successful_reporting_method

The method by which the Enforcer will determine whether the login request was successful.

Possible values:

  • "status" - The Enforcer will determine if the login request was successful by evaluating the response status code against the px_login_successful_status configuration. (Supports only one status code. For multiple status codes, use the "custom" setting.)
  • "header" - The Enforcer will determine if the login request was successful by evaluating whether the x-px-login-successful header is set to "1".
  • "custom" - The Enforcer will determine if the login request was successful by invoking the px_custom_set_login_successful_response_header subroutine.

This setting will apply to all configured Credential Intelligence endpoints. If you need to differentiate between endpoints, set this value to "custom" and use the px_custom_set_login_successful_response_header to implement your desired logic on a per-endpoint basis.

Default: "status"

# PX_CONFIGS
table px_configs {
    # ...
    "px_login_successful_reporting_method": "custom",
    # ...
}

px_login_successful_status

An HTTP status signifying a successful login. All other status codes will be treated as unsuccessful login attempts. This configuration takes effect only when the px_login_successful_reporting_method is set to "status".

🚧

Note

This configuration supports defining only one status code. For multiple status codes, set px_login_successful_reporting_method to "custom" and implement your desired logic in the px_custom_set_login_successful_response_header subroutine instead.

Default: "200"

# PX_CONFIGS
table px_configs {
    # ...
    "px_login_successful_status": "202",
    # ...
}

px_custom_set_login_successful_response_header

A custom subroutine to indicate if the login attempt was successful. This configuration takes effect only when the px_login_successful_reporting_method is set to "custom". This subroutine is invoked during the vcl_deliver stage.

The subroutine should set the resp.http.x-px-login-successful header to "1" if the login request resulted in a successful login, or to "0" if the login attempt was unsuccessful.

Default: Empty

Example:

# PX_CUSTOM
sub px_custom_set_login_successful_response_header {
    if (resp.http.custom-login-header == "login_successful") {
        set resp.http.x-px-login-successful = "1";
    } else {
        set resp.http.x-px-login-successful = "0";
    }
}

px_send_raw_username_on_additional_s2s_activity

Whether to report the raw username on the additional_s2s activity. When set to "false", the raw username will never be reported. When set to "true", the raw username will only be reported if (1) the credentials are compromised, and (2) the login request was successful.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_send_raw_username_on_additional_s2s_activity": "true",
    # ...
}

px_credentials_intelligence_query_string

Whether to add the URL query parameter compromised_credentials=true to the origin request URL if compromised credentials have been identified on the request.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_credentials_intelligence_query_string": "true",
    # ...
}

px_compromised_credentials_returned_status_response

This configuration modifies the returned client response status code if px_credentials_intelligence_query_string is enabled, and if the login request contained compromised credentials and resulted in a successful login.

Default: ""

# PX_CONFIGS
table px_configs {
    # ...
    "px_compromised_credentials_returned_status_response": "401",
    # ...
}

px_additional_s2s_activity_header_enabled

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.

When set to "true", the additional_s2s activity will no longer be sent automatically by the Enforcer. Instead, the following headers will be 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-url - The URL to which the additional_s2s payload should be sent as an HTTP POST request.

Default: "false"

# PX_CONFIGS
table px_configs {
    # ...
    "px_additional_s2s_activity_header_enabled": "true",
    # ...
}

Below is an example of JavaScript code at the origin server to handle parsing, enrichment, and sending of the additional_s2s activities that arrive on request headers.

app.post('/login', (req, res) => {
    // handle login flow, resulting in variables
    // isLoginSuccessful (boolean) and responseStatusCode (number)

    if (
        req.headers['px-additional-activity'] &&
        req.headers['px-additional-activity-url']
    ) {
        handlePxAdditionalActivity(req, responseStatusCode, isLoginSuccessful);
    }
});

function handlePxAdditionalActivity(req, statusCode, isLoginSuccessful) {
    try {
        // extract url and activity from the request headers
        const url = req.headers['px-additional-activity-url'];
        const activity = JSON.parse(req.headers['px-additional-activity']);

        // enrich the activity details with added information
        activity.details['http_status_code'] = statusCode;
        activity.details['login_successful'] = isLoginSuccessful;

        if (activity.details['credentials_compromised'] && isLoginSuccessful) {
            // add raw username if credentials are compromised and login is successful (only if desired)
            activity.details['raw_username'] = req.body.username;
        } else {
            // remove raw username if login is not successful or credentials are not compromised
            delete activity.details['raw_username'];
        }

        // send the POST request
        axios.post(url, activity, {
            headers: {
                'Authorization': `Bearer ${env.PX_AUTH_TOKEN}`,
                'Content-Type': 'application/json'
            }
        });
    } catch (err) {
        console.error(`Error: ${err}`);
    }
}

Updated 12 days ago