Product guides

Akamai EdgeWorker Enforcer v4 configuration

Suggest Edits

Overview

The HUMAN enforcer can be configured within the Akamai Property Manager Variables. These variables can be set in the Akamai property and will always be prefaced with PMUSER_ (e.g., PX_APP_ID will be PMUSER_PX_APP_ID).

Custom functions can be implemented within the Akamai EdgeWorker code in JavaScript.

🚧

Note

When possible, the Akamai Property rules reference the Akamai Property variables dynamically; however, there may be cases in which changes to the Akamai Property variables necessitate changes in the Akamai Property rules (e.g., PX_APP_ID, PX_FILTER_BY_EXTENSION). Be sure to double-check the Property rules when making variable changes to ensure they are aligned.

HumanSecurityConfiguration Property Manager Variables

PX_APP_ID

Required. The application ID.

PX_AUTH_TOKEN

Required. The token used for authorization with the HUMAN backend.

Security Settings: Hidden

PX_COOKIE_SECRET

Required. The secret used to encrypt and decrypt the risk cookie.

Security Settings: Hidden

Cookie Secret Rotation

In case you would like to generate and use a new cookie secret, the enforcer will have to support both old and new cookie secrets to avoid multiple 'cookie decryption failed' errors. In your configuration, adjust the PX_COOKIE_SECRET value to be a comma-separated list of the new cookie secret followed by the old cookie secret. Array size is limited to 2 cookie secrets.

Example: newCooki3Secr3t,0ldCooki3Secr3t

PX_BACKEND_DOMAIN

Required. The domain to which HUMAN requests are sent. This must be set to the value sapi-<PX_APP_ID>.perimeterx.net.

Default: sapi-<PX_APP_ID>.perimeterx.net

Example: sapi-PX12345678.perimeterx.net (where the PX_APP_ID is PX12345678)

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.

Possible values:

  • true - The enforcer is enabled
  • false- The enforcer is disabled

Default: true

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_LOGGER_SEVERITY

The verbosity of the logs generated by the enforcer.

Possible values:

  • none - No logs will be generated
  • error - Sparse logs will be generated only when errors occur
  • debug - Detailed logs will always be generated (not advisable for production environments)

Default: error

PX_S2S_TIMEOUT

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: 1000

PX_IP_HEADERS

By default, the IP is taken from the AK_CLIENT_REAL_IP variable. However, if this value is inaccurate, the enforcer can extract the IP from the headers configured in the comma-separated list. The headers are traversed in the order they are listed. The first header value that exists will be used as the client IP.

Default: Empty

Example: true-ip,true-client-ip

PX_ABR_ENABLED

In specific cases (e.g., XHR post requests), a full captcha page render might not be an option. In such cases the advanced blocking response (ABR) returns a JSON object containing all the information needed to render a customized captcha challenge implementation - be it a popup modal, a section on the page, etc. This allows for flexibility and customizability in terms of how the captcha pages are displayed.

Possible values:

  • true - JSON advanced block responses (ABR) will be returned when needed
  • false - JSON advanced block responses (ABR) will not be returned

Default: true

PX_FIRST_PARTY_ENABLED

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

Possible values:

  • true - First party is enabled
  • false - First party is disabled

Default: true

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: x-px-block

PX_ENFORCED_ROUTES

Customers may want certain, but not all, endpoints to be enforced by HUMAN, even when the Enforcer is in monitor mode. These routes will go through the full enforcer workflow, including blocking requests when necessary. That is, even when the enforcer is in monitor mode, these routes will behave as if in active blocking mode. Routes should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the i flag.

Default: Empty

Example: /^(\/webapi\/reservation\/confirm\/?)$/i

PX_MONITORED_ROUTES

Enables certain endpoints to be monitored rather than enforced by HUMAN, even when the enforcer is in active blocking mode. Routes should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the i flag.

Default: Empty

Example: /^(./category/?.)|(./product/?.)$/i

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. Configuring these header names as sensitive headers will remove these headers from requests sent to other backends by HUMAN. Headers should be configured as a comma-separated list of header names.

Default: cookie,cookies

PX_SENSITIVE_ROUTES

Certain endpoints may require more stringent protection from bot attacks (e.g., endpoints that execute payments or handle personal information). In these cases, routes can be configured as sensitive routes, meaning risk API calls will be made even if the request contains a valid, unexpired cookie. Routes should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the i flag.

Default: Empty

Example: /^(./login/?.)|(./sign/?.)$/i

PX_FILTER_BY_EXTENSION

HUMAN does not enforce static assets such as images and documents. To prevent unnecessary API calls to HUMAN servers and needless computation, the enforcer filters all requests with a valid static file extension. Filtering by extension only applies to HTTP requests with methods GET and HEAD. Extensions should be configured as a comma-separated list.

📘

Note

Must match those configured in the PXWorkerRule and PXStaticContentWorkerRule in the Akamai Property Manager.

Default: .css,.bmp,.tif,.ttf,.docx,.woff2,.js,.pict,.tiff,.eot,.xlsx,.jpg,.csv,.eps,.woff,.xls,.jpeg,.doc,.ejs,.otf,.pptx,.gif,.pdf,.swf,.svg,.ps,.ico,.pls,.midi,.svgz,.class,.png,.ppt,.mid,.webp,.jar,.json,.xml

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. HTTP methods should be configured as a comma-separated list (case-insensitive).

Default: HEAD,TRACE

📘

Note

To avoid invoking the Akamai EdgeWorker in its entirety for these HTTP methods, you can also implement this by editing the PXWorkerRule in the Property Manager.
Under the Criteria section, add another match as follows:

  • Request Method: Request Method
  • Operator: is not
  • Value: The HTTP methods you want to filter out (e.g., HEAD, TRACE)

PX_FILTER_BY_IP

Filters out requests according to their IP address, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs. The IPs or CIDR ranges should be configured as a comma-separated list.

Default: Empty

Example: 1.1.1.1,2.2.2.2/8

PX_FILTER_BY_ROUTE

Filters out requests based on their route. A request to a filtered route will not be enforced or blocked and will not generate any risk or async activities. Routes should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the i flag.

Default: Empty

Example: /^(./allowed_route/?.)|(./filtered_route/?.)$/i

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. User agents should be configured as a single regular expression (PCRE). For case-insensitive matching, the regex should end with the i flag.

Default: Empty

Example: /^(filtered-ua)|(filtered-user-agent)$/

PX_CSS_REF

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

Default: Empty

Example: https://www.example.com/custom/style.css

PX_JS_REF

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

Default: Empty

Example: https://www.example.com/custom_script.js

PX_CUSTOM_LOGO

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

Default: Empty

Example: https://www.example.com/custom_logo.png

PX_CUSTOM_COOKIE_HEADER

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_DEC_URL_RESERVED_CHARS

📘

This configuration was added in version 4.1.0.

By design, the Enforcer treats reserved characters in URLs differently from their percent-encoded counterparts. For example, the URL https://example.com/path-with-%3F-mark will be parsed as having path /path-with-%3F-mark, while the URL https://example.com/path-with-?-mark would be parsed as having path /path-with- and query parameters -mark.

However, some servers, frameworks, or business logic may apply percent decoding to reserved characters within the URL path. Setting this configuration to true will apply percent decoding to reserved characters in the URL path prior to parsing.

Possible values:

  • true - Reserved characters will be percent-decoded in the URL path
  • false - Reserved characters will not be percent-decoded in the URL path

Default: false

PX_SECURED_PXHD_ENABLED

📘

This configuration was added in version 4.1.0.

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

Possible values:

  • true - PXHD cookie will be set with the Secure attribute
  • false - PXHD cookie will not be set with the Secure attribute

Default: false

PX_CORS_SUPPORT_ENABLED

🚧

CORS Preflight Requests

Since Akamai EdgeWorkers do not currently support the OPTIONS method, CORS preflight requests are always filtered, and will not pass through the EdgeWorker.
It is important to handle preflight requests properly, either elsewhere in your Akamai Property Manager or in your origin server.

Whether to add CORS headers to block responses. If enabled, CORS requests will receive block responses with either the default or customized CORS response headers.

Access-Control-Allow-Origin: <ORIGIN_REQUEST_HEADER_VALUE>  
Access-Control-Allow-Credentials: true

CORS block response headers can be customized using the px_cors_create_custom_block_response_headers function. If it returns a falsy value, then the default headers will be set on the block response.

Possible values:

  • true - CORS support is enabled
  • false - CORS support is disabled

Default: false

GraphQL Configurations

PX_GRAPHQL_ENABLED

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

Possible values:

  • true - GraphQL parsing is enabled
  • false - GraphQL parsing is disabled

Default: true

PX_GRAPHQL_ROUTES

A regular expression that matches all routes that should be considered GraphQL routes. If px_graphql_enabled is true, all POST requests with routes that match the regular expression (PCRE) configured here will have their bodies parsed for GraphQL operations. For case-insensitive matching, the regex should end with the i flag.

📘

Note

Must match those configured in the PXSetGraphqlBypassResponseProviderRule in the Akamai Property Manager.

Default: /^/graphql$/i

PX_SENSITIVE_GQL_OP_TYPES

A comma-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: Empty

Example: mutation,subscription

PX_SENSITIVE_GQL_OP_NAMES

A regular expression (PCRE) of operation names or keywords that should be considered sensitive if found in the query. If any GraphQL operation is found to have an operation name or extracted keyword that matches the configured regex, the HTTP request will trigger a Risk API call even if it contains a valid, unexpired cookie. For case-insensitive matching, the regex should end with the i flag.

Default: Empty

Example: /^(LoginOperation|SignIn)$/

PX_GRAPHQL_KEYWORDS

A regular expression (PCRE) used to identify important terms from the GraphQL operation queries. All strings in a GraphQL query matching the pattern configured here will be extracted and reported to HUMAN. These keywords are used to determine the purpose of the operation (e.g., login, checkout, search), and can also be used to specify which GraphQL operations should be considered sensitive. See the PX_SENSITIVE_GQL_OP_NAMES configuration for more information.

Default: Empty

Example: /(\w*[Ll]ogin\w*)|(\w*[Ss]ignup\w*)/i

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: Empty

Example: auth

PX_JWT_COOKIE_USERID_NAME

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

Default: Empty

Example: nameID

PX_JWT_COOKIE_ADDL_FIELDS

The field names in the JWT object, extracted from the JWT cookie, that should be extracted and reported in addition to the user ID. The field names should be configured as a comma-separated list.

Default: Empty

Example: exp,iss

PX_JWT_HEADER_NAME

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

Default: Empty

Example: x-jwt-authorization

PX_JWT_HEADER_USERID_NAME

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

Default: Empty

Example: sub

PX_JWT_HEADER_ADDL_FIELDS

The field names in the JWT object, extracted from the JWT header, that should be extracted and reported in addition to the user ID. The field names should be configured as a comma-separated list.

Default: Empty

Example: exp,iss

Credential Intelligence Configurations

PX_CI_EXTRACT_ENABLED

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

Possible values:

  • true - Credential Intelligence is enabled
  • false - Credential Intelligence is disabled

Default: false

PX_CI_EXTRACT_DETAILS

An array of JSON object configurations 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, how to extract the credentials from the request, and how to determine if the request operation (login, signup, etc.) was successful based on the returned HTTP response.

📘

Note

The HumanSecurityFunctionsConfiguration object defined within the Akamai EdgeWorker code also includes a px_login_credentials_extraction field for defining login endpoints that require custom logic for extracting credentials or determining login success.

Each configuration endpoint should be defined once: either in the px_login_credentials_extraction (EdgeWorker) if custom functions must be implemented, or in PX_CI_EXTRACT_DETAILS (Property Manager) if no custom functions.

Regardless, all paths and methods for all credential extraction endpoints must be accounted for in the PXSetCIBypassResponseProviderRule.

Each credential endpoint configuration object contains the following fields:

path

Required. The path of the request that contains the credentials. It can be either an exact path or a string in the form of a regular expression. For case-insensitive matching, the regex should end with the i flag.

📘

Note

The path values in the PX_CI_EXTRACT_DETAILS array must match the list of paths configured in the Property Manager rule named PXSetCIBypassResponseProviderRule.

{
    // ...
    "path": "/sign-up",
    // ...
}

path_type

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

📘

Note

The path values in the PX_CI_EXTRACT_DETAILS array must match the list of paths configured in the Property Manager rule named PXSetCIBypassResponseProviderRule.

Possible values:

  • "exact" - The value set in path must match the request path exactly as is.
  • "regex" - The value set in path represents a regular expression to be matched against the request path.

Default: "exact"

{
    // ...
    "path": "/^/auth/[A-Za-z0-9]{12}/login/i",
    "path_type": "regex",
    // ...
}

method

Required. The HTTP method of the request that contains the credentials. This can be set to any string representing an HTTP method (e.g., "GET", "POST", "PUT").

{
    // ...
    "method": "POST",
    // ...
}

sent_through

Required. Whether the credentials should be extracted from the request headers, query parameters, body, or via a defined custom callback.

Possible values:

  • "body" - The credentials will be extracted according to the configured user_field and pass_field values from the request body.
  • "header" - The credentials will be extracted from the request headers according to the configured user_field and pass_field.
  • "query-param" - The credentials will be extracted from the query parameters according to the configured user_field and pass_field.
  • "custom" - The credentials will be extracted by invoking the extract_credentials_callback. If this value is chosen, the credential endpoint configuration should be defined in the Akamai EdgeWorker code.

📘

Note

If "body" is configured as the sent_through value, the Enforcer must read and parse the incoming request body. The Enforcer parses the request body based on the Content-Type request header.

Supported content types are listed below.

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

user_field

Required only if sent_through is set to "body", "header", or "query-param".

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

{
    // ...
    "sent_through": "body",
    "user_field": "username",
    // ...
}

pass_field

Required only if sent_through is set to "body", "header", or "query-param".

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

{
    // ...
    "sent_through": "body",
    "pass_field": "password",
    // ...
}

📘

Note

The user_field and pass_field configurations support subfields in cases of Content-Type: application/json bodies with nested objects. The subfields can be separated with periods.

For example, the credential endpoint configuration object can include a user_field with the value "user_info.username" and a pass_field with the value "authentication.password" to support extracting the credentials from the following JSON body:

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

extract_credentials_callback

Required only if sent_through is set to "custom".

📘

Note

This function must be implemented within the Akamai EdgeWorker. Note that this function will be invoked as part of the responseProvider event since this is the only Akamai event that provides access to the request body.

A custom credential extraction callback that returns the raw credentials from the request. It receives the HTTP request as a parameter and should return a Credentials object of the following type.

type Credentials = {
    user?: string;  // the raw username
    pass?: string;  // the raw password
};

If neither the username nor the password can be extracted from the request, the function should return null.

🚧

Warning

The request body cannot be read more than once! If you plan on reading the request body in this function,
please use the HumanSecurityUtils.getRequestBody() function to read the request body safely.

{
    // ...
    sent_through: 'custom',
    extract_credentials_callback: async (request: EW.ResponseProviderRequest): Promise<{ user?: string; pass?: string; }> => {
        const body: string | undefined = await HumanSecurityUtils.getRequestBody(request);
        
        // custom logic to extract credentials from the request body
        
        if (!username || !password) {
            return null;
        }
        return { user: username, pass: password };
    },
    // ...
}

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"

{
    // ...
    "protocol": "v2",
    // ...
}

login_successful_reporting_method

Required. 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 login_successful_statuses configuration.
  • "body" - The Enforcer will determine if the login request was successful by evaluating the response body content against the login_successful_body_regex configuration.
  • "header" - The Enforcer will determine if the login request was successful by evaluating the response headers against the login_successful_header_name and login_successful_header_value configurations.
  • "custom" - The Enforcer will determine if the login request was successful by invoking the login_successful_callback. If this value is chosen, the credential endpoint configuration should be defined in the Akamai EdgeWorker code.

Default: "status"

login_successful_statuses

Optional.

An array of HTTP statuses signifying a successful login. All other status codes will be treated as unsuccessful login attempts. Takes effect only when the login_successful_reporting_method is set to "status".

Default: [200]

{
    // ...
    "login_successful_reporting_method": "status",
    "login_successful_statuses": [200, 202],
    // ...
}

login_successful_body_regex

Required only if login_successful_reporting_method is set to "body".

A regular expression (or string representing a regular expression) against which the response body will be evaluated. A match indicates a successful login. For case-insensitive matching, the regex should end with the i flag.

{
    // ...
    "login_successful_reporting_method": "body",
    "login_successful_body_regex": "/Welcome, [A-Za-z0-9_]+!/i",
    // ...
}

login_successful_header_name

Required only if login_successful_reporting_method is set to "header".

A response header name signifying a successful login response. If the login_successful_header_value field is empty or not configured, any response containing this header name will be considered a successful login. If the login_successful_header_value is configured, the response header value must be an exact match.

{
    // ...
    "login_successful_reporting_method": "header",
    "login_successful_header_name": "x-login-successful",
    // ...
}

login_successful_header_value

Optional. If this value is configured, a login attempt will be considered successful only if the response contains a header name matching the login_successful_header_name, and whose value is exactly equal to this configuration value. Takes effect only when the login_successful_reporting_method is set to "header".

{
    // ...
    "login_successful_reporting_method": "header",
    "login_successful_header_name": "x-user-status",
    "login_successful_header_value": "logged-in",
    // ...
}

login_successful_callback

Required only if login_successful_reporting_method is set to "custom".

📘

Note

This function must be implemented within the Akamai EdgeWorker. Note that this function will be invoked as part of the responseProvider event.

A custom callback that accepts the HTTP response and returns a boolean or Promise resolving to a boolean that indicates whether the login attempt was successful.

  • Parameters
    • response: { status: number; headers: Record<string, string[]>; body: any }
  • Returns a boolean or Promise resolving to a boolean.

Default: null

🚧

Warning

The response body cannot be read more than once! If you plan on reading the response body in this function, please use the HumanSecurityUtils.getResponseBody() function to read the response body safely.

{
    // ...
    login_successful_reporting_method: 'custom',
    login_successful_callback: async (response: { status: number; headers: Record<string, string[]>; body: any }): Promise<boolean> => {
        return response.status === 200 
                && response.headers['set-cookie']?.some((val) => val.includes('session_token='))
                && await HumanSecurityUtils.getResponseBody(response).includes('Welcome!');
    },
    // ...
}

PX_CI_COMPROMISED_HEADER

The header name to be set on the incoming request if the credentials are compromised. If this header is added, its value will always be 1. If credentials have not been identified as compromised, the header will not be added to the request.

Default: px-compromised-credentials

PX_CI_SEND_RAW_USERNAME

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.

Possible values:

  • true - The raw username will be reported if the credentials are compromised and the login request was successful.
  • false - The raw username will not be reported.

Default: false

PX_CI_AS2S_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. Enabling this configuration disables the automatic sending of the additional_s2s activity.

Possible values:

  • true - Disables the automatic sending of the additional_s2s activity and instead adds the following headers are 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.
  • false - The additional_s2s activity will be sent automatically and no headers will be added to the origin request.

Default: false

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}`);
    }
}

PX_CI_VERSION

Warning

This configuration has been deprecated. Please use the "protocol" field in the PX_CI_EXTRACT_DETAILS configuration instead.

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. This configuration applies to all credential extraction endpoints.

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_CI_LS_REPORTING_METHOD

🚧

Warning

This configuration has been deprecated. Please use the "login_successful_reporting_method" field in the PX_CI_EXTRACT_DETAILS configuration instead.

Optional. The method by which the Enforcer will determine whether the login request was successful. This configuration applies to all credential extraction endpoints.

Possible values:

  • status - The Enforcer will determine if the login request was successful by evaluating the response status code against the login_successful_statuses configuration.
  • body - The Enforcer will determine if the login request was successful by evaluating the response body content against the login_successful_body_regex configuration.
  • header - The Enforcer will determine if the login request was successful by evaluating the response headers against the login_successful_header_name and login_successful_header_value configurations.

Default: status

PX_CI_LS_STATUS

🚧

Warning

This configuration has been deprecated. Please use the "login_successful_statuses" field in the PX_CI_EXTRACT_DETAILS configuration instead.

Optional. A comma-separated list of HTTP statuses signifying a successful login. All other status codes will be treated as unsuccessful login attempts. Takes effect only when the PX_CI_LS_REPORTING_METHOD is set to status. This configuration applies to all credential extraction endpoints.

Default: 200

PX_CI_LS_BODY_REGEX

🚧

Warning

This configuration has been deprecated. Please use the "login_successful_body_regex" field in the PX_CI_EXTRACT_DETAILS instead.

Optional. A regular expression against which the response body will be evaluated. A match indicates a successful login. This configuration applies to all credential extraction endpoints. For case-insensitive matching, the regex should end with the i flag.

Default: Empty

Example: /Welcome, [A-Za-z0-9_]+!/i

PX_CI_LS_HEADER_NAME

🚧

Warning

This configuration has been deprecated. Please use the "login_successful_header_name" field in the PX_CI_EXTRACT_DETAILS instead.

Optional. A response header name signifying a successful login response. If the PX_CI_LS_HEADER_VALUE field is empty or not configured, any response containing this header name will be considered a successful login. If the login_successful_header_value is configured, the response header value must be an exact match. This configuration applies to all credential extraction endpoints.

Default: Empty

Example: x-user-status

PX_CI_LS_HEADER_VALUE

🚧

Warning

This configuration has been deprecated. Please use the "login_successful_header_value" field in the PX_CI_EXTRACT_DETAILS instead.

Optional. If this value is configured, a login attempt will be considered successful only if the response contains a header name matching the PX_CI_LS_HEADER_NAME, and whose value is exactly equal to this configuration value. Takes effect only when thePX_CI_LS_REPORTING_METHOD is set to header. This configuration applies to all credential extraction endpoints.

Default: Empty

Example: logged-in

Remote Configurations

📘

Note

Remote Configurations requires access to Akamai EdgeKV and
adding the EdgeKV helper library to your Akamai EdgeWorker.

PX_LOGGER_AUTH_TOKEN

The token used to authenticate with HUMAN's enforcer logging services. This value is required for setting up the header-based logger feature as well as configuring the enforcer from the HUMAN Portal.

Security Settings: Hidden

Default: Empty

PX_RC_ID

The ID of the remote configuration. This value is required for configuring the enforcer from the HUMAN Portal.

Default: Empty

PX_RC_AUTH_TOKEN

The token used to authenticate the enforcer with the HUMAN remote configuration service. This value is required for configuring the enforcer from the HUMAN Portal.

Security Settings: Hidden

Default: Empty

PX_RC_MAX_FETCH_ATTEMPTS

The maximum number of times to try fetching the remote configuration. If the enforcer fails to fetch the remote configuration after the specified number of attempts, it will continue to use the last known configuration.

Default: 5

PX_RC_RETRY_INTERVAL

Interval time in milliseconds between attempts to fetch the remote configuration.

Default: 1000

HumanSecurityFunctionsConfiguration

The HumanSecurityFunctionsConfiguration object is used to define custom functions that can be used to configure the enforcer's behavior. These functions may be invoked during the onClientRequest, onClientResponse, or responseProvider events. Since the request and response objects vary in structure between events, we strongly recommend performing runtime checks for the existence of properties and methods before accessing them directly.

The Akamai EdgeWorkers site provides information about which request and response methods are available in which events.

px_custom_is_enforced_request

📘

Note

This configuration is meant for cases that require more complex custom logic. It is recommended to use the PX_ENFORCED_ROUTES Property Manager variable for simpler cases.

Customers may want certain, but not all, endpoints to be enforced by HUMAN, even when the Enforcer is in monitor mode. This configurable function provides a way to define which requests should be enforced based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be enforced (the request will behave as if in active blocking mode) or not.

Default: null

const config: HumanSecurityFunctionsConfiguration = {
    // ...
    px_custom_is_enforced_request: (request: EW.IngressClientRequest | EW.ResponseProviderRequest): boolean | Promise<boolean> => {
        return request.method === 'POST' && request.path.startsWith('/enforced_route');
    },
    // ...
}

px_custom_is_monitored_request

📘

Note

This configuration is meant for cases that require more complex custom logic. It is recommended to use the PX_MONITORED_ROUTE Property Manager variable for simpler cases.

Customers may want certain, but not all, endpoints to be monitored by HUMAN, even when the Enforcer is in active_blocking mode. This configurable function provides a way to define which requests should be monitored based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be monitored (the request will behave as if in monitor mode) or not.

Default: null

const config: HumanSecurityFunctionsConfiguration = {
    // ...
    px_custom_is_monitored_request: (request: EW.IngressClientRequest | EW.ResponseProviderRequest): boolean | Promise<boolean> => {
        return request.method === 'GET' && request.path.startsWith('/monitored');
    },
    // ...
}

px_custom_is_sensitive_request

📘

Note

This configuration is meant for cases that require more complex custom logic. It is recommended to use the PX_SENSITIVE_ROUTES Property Manager variable for simpler cases.

Requests can be configured as sensitive, meaning risk API calls will be made even if the request contains a valid, unexpired cookie. This configurable function provides a way to define which requests should be considered sensitive based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be considered sensitive or not.

Default: null

const config: HumanSecurityFunctionsConfiguration = {
    // ...
    px_custom_is_sensitive_request: (request: EW.IngressClientRequest | EW.ResponseProviderRequest): boolean | Promise<boolean> => {
        return request.method === 'POST' || request.method === 'PUT';
    },
    // ...
}

px_custom_is_filtered_request

📘

Note

This configuration is meant for cases that require more complex custom logic. It is recommended to use the various PX_FILTER_BY_* Property Manager variables for simpler cases.

Customers may prefer to filter certain requests (i.e., not apply HUMAN enforcement at all). These requests will not be blocked, and they will not generate any risk or async activities. This configurable function provides a way to define which requests should be filtered based on custom logic. The function accepts the incoming request as an argument and returns a boolean indicating whether the request should be filtered or not.

Default: null

const config: HumanSecurityFunctionsConfiguration = {
    // ...
    px_custom_is_filtered_request: (request: EW.IngressClientRequest | EW.ResponseProviderRequest): boolean | Promise<boolean> => {
        return request.method === 'GET' && request.path.startsWith('/static/');
    },
    // ...
}

px_cors_create_custom_block_response_headers

If the default CORS response headers are not sufficient, this configuration 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; only those headers specified in the returned object will be added to the block response.

Default: null

const config: HumanSecurityFunctionsConfiguration = {
    // ...
    px_cors_create_custom_block_response_headers: (
        request: EW.IngressClientRequest | EW.ResponseProviderRequest,
    ): Record<string, string[]> => {
        return {
            'Access-Control-Allow-Origin': [request.getHeader('origin')?.[0] ?? '*'],
            'Access-Control-Allow-Credentials': ['false'],
            'Access-Control-Allow-Methods': ['GET', 'POST', 'PUT'],
            'X-Custom-Header': ['1']
        };
    },
    // ...
}

px_additional_activity_handler

The additional activity handler is a custom function passed to the enforcer. The enforcer runs this callback just before sending page_requested or block activity to the collector, before forwarding the request to the next step in the pipeline. A common use case of the additional activity handler is to set the score as a variable or header. Then the application can read the score and do what is defined within the application's logic.

Default: null

const config: HumanSecurityFunctionsConfiguration = {
    // ...
    px_additional_activity_handler: (
        config: HumanSecurityConfiguration,
        context: IContext,
        request: EW.IngressClientRequest | EW.ResponseProviderRequest
    ): void => {
        if ('setHeader' in request) {
            request.setHeader('x-px-score', `${context.score}`);
            request.setHeader('x-px-rtt', `${context.riskApiData.riskRtt}`);
        }
    },
    // ...
}

🚧

Warning

The request body cannot be read more than once! If you plan on reading the request body in this function, please use the HumanSecurityUtils.getRequestBody() function to read the request body safely.

px_enrich_custom_parameters

This custom function enriches activities sent from the enforcer to HUMAN with additional custom data. This data can include user information, session IDs, or other data that HUMAN should have access to. These custom parameters are defined by a configurable function that must return an object that contains these custom parameters. There is a limit of 10 custom parameters.

Default: null

const config: HumanSecurityFunctionsConfiguration = {
    // ...
    px_enrich_custom_parameters: async (
        config: HumanSecurityConfiguration,
        request: EW.IngressClientRequest | EW.ResponseProviderRequest,
    ): CustomParameters | Promise<CustomParameters> => {
        let body = null;
        if ('body' in request && request.method === 'POST') {
            try {
                body = JSON.parse(await HumanSecurityUtils.getRequestBody(request))
            } catch {
                // fail silently
            }
        }
        return {
            custom_param1: 'hardcoded value',
            custom_param2: request.headers.get('header-name'),
            custom_param3: body?.['body_property']
        };
    },
    // ...
}

🚧

Warning

The request body cannot be read more than once! If you plan on reading the request body in this function, please use the HumanSecurityUtils.getRequestBody() function to read the request body safely.

px_extract_graphql_keywords

A custom function for identifying key terms from GraphQL operation queries, providing an alternative to the PX_GRAPHQL_KEYWORDS Property Manager variable. If a regular expression is insufficient to extract the GraphQL keywords, this custom function offers more flexibility.

The function accepts the GraphQL query string and must return an array of strings representing all keywords found in the query. These keywords are used to determine the purpose of the operation (e.g., login, checkout, search), and can also be used to specify which GraphQL operations should be considered sensitive. See the PX_SENSITIVE_GQL_OP_NAMES Property Manager variable for more information.

🚧

Warning

If this function is defined and returns an array (even an empty array), then the returned array will be used as the GraphQL keywords. If this function is defined and returns null, then the query will continue to be evaluated using px_graphql_keywords.

  • Parameters
    • graphqlQuery: string
  • Returns string[] | Promise<string[]>

Default: null

const config: HumanSecurityFunctionsConfiguration = {
    // ...
    px_extract_graphql_keywords: (graphqlQuery: string): string[] | Promise<string[]> => {
        if (/userId\d+/.test(graphqlQuery)) {
            // report no keywords for this query
            return [];
        } else if (/perform(Login|Signin)/.test(graphqlQuery)) {
            // always report 'login' as the only keyword for this query
            return ['login'];
        } else {
            // process query according to px_graphql_keywords configuration
            return null;
        }
    },
    // ...
}

Updated 9 days ago