Configuration Options

The initial PerimeterX configuration is determined during the installation process. All configurations are set as Property Variables in the Akamai Property Editor.

🚧

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.

Module Enabled

A boolean flag to enable/disable the PerimeterX Enforcer.

Property Variable Name: PX_MODULE_ENABLED

Default: true

Module Mode

By default, the PerimeterX enforcer’s mode is set to monitor. To activate blocking mode, set the PMUSER_PX_MODULE_MODE property variable to active_blocking.

Property Variable Name: PX_MODULE_MODE

Default from v.1.1.0: monitor
Default up to v.1.0.6: 0

First Party

Indicates whether the enforcer is in first party mode or not. Be sure to complete the steps in the Integrate 1st-Party JS Snippet section to make sure your snippet is set up to serve the JavaScript Sensor via First-Party.

Property Variable Name: PX_FIRST_PARTY_ENABLED

Default: true

S2S Timeout

The number of milliseconds to wait for for the server-to-server call, after which a timeout is triggered and the request will pass.

Property Variable Name: PX_S2S_TIMEOUT

Default: 1000

Sensitive Headers

Comma-separated list of sensitive headers. These headers will be removed from all requests to the PerimeterX backend.

Property Variable Name: PX_SENSITIVE_HEADERS

Default: "cookie, cookies"

Filter by Route

Regex (PCRE) for allowed routes. Requests for these routes will pass without being enforced or monitored.

Property Variable Name: PX_FILTER_BY_ROUTE

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

Default: Empty

Filter by User Agent

Regex (PCRE) for filtered user agents. Requests with these user agents will pass without being enforced or monitored.

Property Variable Name: PX_FILTER_BY_USER_AGENT

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

Default: Empty

Filter by Extension

Comma-separated list of extensions.

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

Property Variable Name: PX_FILTER_BY_EXTENSION

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"

Enforced Routes

Regex (PCRE) for routes to enforce even when in monitor mode.

Property Variable Name: PX_ENFORCED_ROUTES

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

Default: Empty

Monitored Routes

Regex (PCRE) for routes to monitor even when in active blocking mode.

Property Variable Name: PX_MONITORED_ROUTES

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

Default: Empty

Bypass Monitor Header

Header name that will force active blocking flow even when the request should be monitored (either in monitor mode or if the route is monitored).

Property Variable Name: PX_BYPASS_MONITOR_HEADER

Default: Empty

Sensitive Routes

Sensitive routes trigger a server call to PerimeterX servers every time the route is called, regardless of viewing history.

Property Variable Name: PX_SENSITIVE_ROUTES

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

Default: Empty

CSS Ref

URL to a custom CSS file for the block page.

Property Variable Name: PX_CSS_REF

Default: Empty

JS Ref

URL to a custom JS file for the block page.

Property Variable Name: PX_JS_REF

Default: Empty

Custom Logo

Custom logo to display at the top of the block page (max-height = 150px, width = auto).

Property Variable Name: PX_CUSTOM_LOGO

Default: Empty

Custom Cookie Header

Specifies a header name that will contain the PerimeterX Cookie.

Property Variable Name: PX_CUSTOM_COOKIE_HEADER

Default: "cookie"

Custom Parameters

With the px_enrich_custom_parameters function you can add up to 10 custom parameters to be sent back to PerimeterX servers. When set, the function is called before setting the payload on every request to PerimeterX servers. The parameters should be passed according to the correct order (1-10) and their format must align as following: custom_param1, custom_param2, ... , custom_param10. The parameters passed along with the px_enrich_custom_parameters function are originalRequest which is the Akamai request object

Note: This function must be set in the custom/pxCustomFunctionsConfig.ts file.

Default: Empty

export function px_enrich_custom_parameters(originalRequest: IngressClientRequest): CustomParams {
  let customParams: CustomParams = {
    custom_param1: "hardcoded example",
  };

  customParams.custom_param2 = request.method
  // ...
  return customParams;
}

Send Request Cookie Names

Specifies the cookie names (not values) that will be reported on activities to the PerimeterX backend. This is due to Akamai's header size limits.

Property Variable Name: PX_SEND_REQ_COOKIE_NAMES (From v1.1.0, If upgrading the enforcer from an earlier version, make sure the variable exists in the Property Manager)
Property Variable Name: PX_COOKIE_WHITELIST (Up to v1.0.6)

Default: "_px2,_pxvid, _ga, dwanonymous_*, sid"

📘

CSS Ref, JS Ref, and Custom Logo

Note that the URLs for PX_CSS_REF, PX_JS_REF, and PX_CUSTOM_LOGO should be no longer than 150 characters combined. This is to ensure that the block responses from the edgeworker (especially on mobile) do not exceed Akamai's 2048 KB limit.

Credentials Intelligence

This feature extracts credentials (hashed username and password) from requests and adds a header to the original request if the credentials have been flagged as compromised. The feature can be toggled on and off and may be set for any number of unique login extraction paths.

Property Variable Name

Description

Default Value

Possible Values

PX_CI_EXTRACT_ENABLED

Whether credentials should be extracted for CI

false

true
false

PX_CI_EXTRACT_DETAILS

An array of JSON objects detailing how to extract credentials for CI (see below)

None

PX_CI_VERSION

Whether CI functions as a single- (v2) or multi-step login

v2

v2
multistep_sso

PX_CI_AS2S_HEADER_ENABLED

Whether to send the additional_s2s as a header or not. If false, the additional_s2s will be sent automatically.

false

true
false

PX_CI_COMPROMISED_HEADER

The name of the header to be sent to the origin when compromised credentials are identified

px-compromised-credentials

PX_CI_SEND_RAW_USERNAME

Whether the raw username of the credentials should be sent to PerimeterX to aid in detection

false

true
false

PX_CI_LS_REPORTING_METHOD

The login successful reporting method to use for identifying successful login requests when the additional_s2s activity is sent automatically

None

status
body
header
custom

PX_CI_LS_STATUS

If the PX_CI_LS_REPORTING_METHOD is status, a comma-separated list of status codes indicating successful login

200

PX_CI_LS_BODY_REGEX

If the PX_CI_LS_REPORTING_METHOD is body, a regex (PCRE) applied to the response body indicating successful login

None

PX_CI_LS_HEADER_NAME

If the PX_CI_LS_REPORTING_METHOD is header, the name of a response header indicating a successful login

x-px-login-successful

PX_CI_LS_HEADER_VALUE

If the PX_CI_LS_REPORTING_METHOD is header, the name of a response header indicating a successful login

1

Notes about Credentials Extraction Configuration

The value of the PMUSER_PX_CI_EXTRACT_DETAILS variable should be a valid JSON array of objects. Each object should contain the following properties:

Property Name

Type

Description

Possible Values

method

string

The HTTP method of the login request

path_type

string

Whether the path property should be an exact match or evaluated as a regular expression

exact,
regex

path

string

The path of the login request as an exact string or regular expression

sent_through

string

The location of the credentials on the request

body,
header,
query-param
custom

user_field

string

The name of the username field

pass_field

string

The name of the password field

Below is an example of a valid array which lists out three different login endpoints from which credentials should be extracted:

[{
    "method": "get",
    "path_type": "exact",
    "path": "/login/query",
    "sent_through": "query-param",
    "pass_field": "password",
    "user_field": "username"
}, {
    "method": "post",
    "path_type": "exact",
    "path": "/login-nested-object",
    "sent_through": "body",
    "pass_field": "nested.password",
    "user_field": "nested.username"
}, {
    "method": "post",
    "path_type": "regex",
    "path": "^/user/[A-Za-z0-9]{8,12}/session$",
    "sent_through": "body",
    "pass_field": "password",
    "user_field": "username"
}, {
    "method": "post",
    "path_type": "exact",
    "path": "/login/custom",
    "sent_through": "custom"
}]

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

If the sent_through is custom, the user_field and pass_field do not need to be defined. Instead, a custom function must be defined in the Akamai EdgeWorker code that accepts the request and PX Context and returns the extracted credentials in the form of an object with the keys username and password. All login endpoints that have custom as the value for sent_through will trigger this function.

If the request body is needed, it should be read using the async function readAndSetRequestBody() to optimize performance.

Note: This function must be set in the custom/pxCustomFunctionsConfig.ts file.

export async function px_custom_extract_credentials(
    originalRequest: EW.ResponseProviderRequest,
    pxContext: PXRequestContext,
): Promise<LoginCredentials> {
    // body is plaintext '<USERNAME>,<PASSWORD>' example:
    // const body = (await readAndSetRequestBody(originalRequest, ReadRequestBodyMethod.TEXT, pxContext)) as string;
    // const [username, password] = body?.split(',') || [];
    // return username && password ? { username, password } : null;
    return null;
}

If the PX_CI_LS_REPORTING_METHOD is custom, a custom function must be defined in the Akamai EdgeWorker code that accepts the response object from the origin as well as the PX response context and returns a boolean or a Promise resolving to a boolean that indicates if the login was successful or not.

If the response body is needed, it should be read using the async function readAndSetResponseBody(response, responseContext) to optimize performance.

Note: This function must be set in the custom/pxCustomFunctionsConfig.ts file.

export async function px_login_successful_custom_callback(
    response: EW.Response,
    responseContext: PXResponseContext,
): Promise<boolean> {
    // example: return response.status === 200 && response.getHeader('set-cookie')[0].includes('login_session');
    return false;
}

GraphQL

This feature parses request body data on GraphQL paths to determine request sensitivity and enhance detection. The enforcer never reports sensitive or personally identifiable data (e.g., variable values). This feature can be toggled on or off, and set for any number of different GraphQL routes.

Property Name

Description

Default Value

Possible Values

PMUSER_PX_GRAPHQL_ENABLED

Whether GraphQL details should be extracted from GraphQL request bodies

true

true
false

PMUSER_PX_GRAPHQL_ROUTES

Regex (PCRE) for routes to enable GraphQL on (note: must match those configured in the PM rules)

/graphql

PMUSER_PX_SENSITIVE_GQL_OP_TYPES

Regex (PCRE) for operation types (e.g., "query", "mutation", "subscription") to flag as sensitive

empty

PMUSER_PX_SENSITIVE_GQL_OP_NAMES

Regex (PCRE) for operation names to flag as sensitive

empty

Note: The paths configured for PMUSER_PX_GRAPHQL_ROUTES must match the list of paths configured in the Property Manager rule named PXSetGraphqlBypassResponseProviderRule.

User Identifiers

PerimeterX uses the User Identifiers to identify clients during and across sessions. The identifiers are:
JWT - JSON Web Token is an encrypted token with a JSON object containing metadata on the user
request, including the app user ID. It can be stored in a cookie or header.
CTS - Cross Tab Session is represented by a token stored on the pxcts cookie.

Property Name

Description

Default Value

PMUSER_PX_JWT_COOKIE_NAME

The name of the cookie that contains the JWT token

None

PMUSER_PX_JWT_COOKIE_USERID_NAME

The name of the JWT payload field that contains the user ID

None

PMUSER_PX_JWT_COOKIE_ADDL_FIELDS

Comma-separated list of additional fields to be extracted from the JWT

None

PMUSER_PX_JWT_HEADER_NAME

The name of the header that contains the JWT token

None

PMUSER_PX_JWT_HEADER_USERID_NAME

The name of the JWT payload field that contains the user ID

None

PMUSER_PX_JWT_HEADER_ADDL_FIELDS

Comma-separated list of additional fields to be extracted from the JWT

None