> This page is for Applications Protection. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.humansecurity.com/llms.txt. # Configuration > **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. ```vcl # PX_CONFIGS table px_configs { "px_app_id": "``", # ... } ``` ### px_auth_token The token used for authorization with the Human Security backend. Required to initialize the Enforcer. ```vcl # PX_CONFIGS table px_configs { # ... "px_auth_token": "``", # ... } ``` ### px_cookie_secret The secret used to decrypt the risk cookie. Required to initialize the Enforcer. ```vcl # PX_CONFIGS table px_configs { # ... "px_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"` ```vcl # 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"` ```vcl # 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` ```vcl # PX_CONFIGS backend PX_API { # ... .connect_timeout = 2000ms; .first_byte_timeout = 2000ms; .between_bytes_timeout = 2000ms; # ... } ``` ### px_custom_cookie_header > **Note** > > 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"` ```vcl # 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. ```vcl # 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies). **Default**: `"false"` ```vcl # 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413). 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"` ```vcl # 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"` ```vcl # 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"` ```vcl # 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**: ```vcl # 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"` ```vcl # 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**: ```vcl # 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**: ```vcl # 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:`, where `` corresponds to the custom parameter number between 1-10. **Default**: Empty **Example**: ```vcl # 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](/applications/data-classification-enrichment). 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**: ```vcl # 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 `` with the desired header. Note: The leading comma is very important! `",{%22name%22: %22
%22, %22value%22: " if(req.http.
, "%22" json.escape(req.http.
) "%22", "null") "}"` **Default**: Returns `""` **Example**: ```vcl # 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**: ```vcl # 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"` ```vcl # 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"` ```vcl # 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**: `""` ```vcl # 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](https://www.fastly.com/documentation/reference/vcl/variables/client-response/) object. **Default**: Empty **Example**: ```vcl # 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]\(/applications/installation-fastly-vcl#2-add-the-required-logging-endpoints).** The name of the logging endpoint used to send asynchronous activities. **Default**: `"PX-Async-Activities"` ```vcl # 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]\(/applications/installation-fastly-vcl#2-add-the-required-logging-endpoints).** The name of the logging endpoint used to send telemetry activities. **Default**: `"PX-Telemetry"` ```vcl # 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]\(/applications/installation-fastly-vcl#2-add-the-required-logging-endpoints).** 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"` ```vcl # 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]\(/applications/installation-fastly-vcl#2-add-the-required-logging-endpoints).** Whether error logs should be sent to the error logging endpoint. **Default**: `"false"` ```vcl # 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]\(/applications/installation-fastly-vcl#2-add-the-required-logging-endpoints).** The name of the logging endpoint to which debug logs will be sent. **Default**: `"PX-Debug"` ```vcl # 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](/applications/installation-fastly-vcl#5-add-the-optional-logging-endpoints). The name of the logging endpoint to which error logs will be sent. **Default**: `"PX-Error"` ```vcl # 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]\(/applications/installation-fastly-vcl#2-add-the-required-logging-endpoints).** 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"` ```vcl # 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"` ```vcl # 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**: ```vcl # 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"` ```vcl # 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**: ```vcl # 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"` ```vcl # 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](https://www.fastly.com/documentation/reference/vcl/declarations/acl/). **Default**: Returns `false`. **Example**: ```vcl # 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**: ```vcl # 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" ```vcl # 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**: ```vcl # 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](https://www.fastly.com/documentation/guides/concepts/shielding/). **Default**: `"false"` ```vcl # 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**: ```vcl # 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**: ```vcl # 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**: `""` ```vcl # 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**: ```vcl # 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"` ```vcl # 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**: ```vcl # 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**: ```vcl # 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**: `""` ```vcl # 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**: `""` ```vcl # 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**: `""` ```vcl # 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"` ```vcl # 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](https://www.fastly.com/documentation/reference/vcl/variables/cache-object/) type and the [synthetic](https://www.fastly.com/documentation/reference/vcl/statements/synthetic/) statement. **Default**: Empty **Example**: ```vcl # 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**: ```vcl # PX_CUSTOM sub px_custom_create_block_page STRING { declare local var.ret STRING; set var.ret = "Access Denied

You have been blocked.

"; 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](https://www.fastly.com/documentation/reference/vcl/variables/cache-object/) type and the [synthetic](https://www.fastly.com/documentation/reference/vcl/statements/synthetic/) statement. > **This subroutine should always end with a \`return(deliver);\` statement to prevent the error flow from continuing.** **Default**: Empty **Example**: ```vcl # 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](https://www.fastly.com/documentation/reference/vcl/variables/cache-object/) type and the [synthetic](https://www.fastly.com/documentation/reference/vcl/statements/synthetic/) statement. > **This subroutine should always end with a \`return(deliver);\` statement to prevent the error flow from continuing.** **Default**: Empty **Example**: ```vcl # PX_CUSTOM sub px_custom_captcha_handler { synthetic {"Unauthorized"}; 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](https://www.fastly.com/documentation/reference/vcl/variables/cache-object/) type and the [synthetic](https://www.fastly.com/documentation/reference/vcl/statements/synthetic/) statement. **Default**: Empty **Example**: ```vcl # 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](https://www.fastly.com/documentation/reference/vcl/variables/cache-object/) type and the [synthetic](https://www.fastly.com/documentation/reference/vcl/statements/synthetic/) statement. **Default**: Empty **Example**: ```vcl # 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](https://www.fastly.com/documentation/reference/vcl/variables/cache-object/) type and the [synthetic](https://www.fastly.com/documentation/reference/vcl/statements/synthetic/) statement. **Default**: Empty **Example**: ```vcl # 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#examples_of_access_control_scenarios). 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. ```none Access-Control-Allow-Origin: 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"` ```vcl # 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"` ```vcl # 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](https://www.fastly.com/documentation/reference/vcl/statements/error/). **Default**: `"false"` ```vcl # 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](https://www.fastly.com/documentation/reference/vcl/variables/cache-object/) type and the [synthetic](https://www.fastly.com/documentation/reference/vcl/statements/synthetic/) statement. **Default**: Empty **Example**: ```vcl # 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"` ```vcl # 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](https://www.fastly.com/documentation/reference/vcl/variables/cache-object/) type. **Default**: Empty **Example**: ```vcl # 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"` ```vcl # 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**: ```vcl # 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**: `""` ```vcl # 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**: `""` ```vcl # 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**: ```vcl # 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**: `""` ```vcl # 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**: `""` ```vcl # 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**: `""` ```vcl # 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**: `""` ```vcl # 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_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**: ```vcl # 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**: `""` ```vcl # PX_CONFIGS table px_configs { # ... "px_remote_config_id": "", # ... } ``` ### px_remote_config_secret A secret key to use in the authentication of incoming Remote Config update requests. **Default**: `""` ```vcl # PX_CONFIGS table px_configs { # ... "px_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](https://www.fastly.com/documentation/reference/api/dictionaries/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](https://www.fastly.com/documentation/reference/api/dictionaries/dictionary/) with the same name can be added instead. In the `cs_data` Fastly table (or dictionary), two entries should be added: \| Key Name | Value | \| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | \| `eng_key` | The 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](https://docs.fastly.com/en/guides/using-api-tokens#creating-api-tokens), [CLI](https://www.fastly.com/documentation/reference/cli/auth-token/create/), or [API](https://www.fastly.com/documentation/reference/api/auth-tokens/#create-token). | \| `px_enforcer_config_rdata_id` | The dictionary ID associated with the `px_enforcer_config_rdata` dictionary. You can determine the dictionary ID via [CLI](https://www.fastly.com/documentation/reference/cli/dictionary/describe/) or [API](https://www.fastly.com/documentation/reference/api/dictionaries/dictionary-info/#get-dictionary-info). | ## CSP Configurations ### px_csp_enabled Whether to enable the CSP feature. This feature adds the [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) and [Content-Security-Policy-Report-Only](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only) headers to the HTTP responses. The values of these headers are updated by the Code Defender product. **Default**: `"false"` ```vcl # 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"` ```vcl # 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**: ```vcl # 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](https://www.fastly.com/documentation/reference/api/dictionaries/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](https://www.fastly.com/documentation/reference/api/dictionaries/dictionary/) with the same name should be added instead. In the `cs_data` Fastly dictionary, two values should be added: \| Key Name | Value | \| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | \| eng_key | The 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_id | The 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` ```vcl # 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](https://www.fastly.com/documentation/reference/api/dictionaries/dictionary/) with the same name. **Default**: Empty ```vcl # 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.) ```vcl # 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"`. ```vcl # 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](https://docs.fastly.com/products/network-services-resource-limits#request-and-response-limits)). ```vcl # 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. ```vcl # 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. ```vcl # 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. ```json { "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"`. ```vcl # 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"` ```vcl # 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**: ```vcl # 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**: ```vcl # 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"` ```vcl # 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"` ```vcl # 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**: ```vcl # 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"` ```vcl # 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"` ```vcl # 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**: `""` ```vcl # 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"` ```vcl # 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. ```js 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}`); } } ```