> 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 Options

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

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

## Module Enabled

A boolean flag to enable/disable the HUMAN Enforcer.

**Property Variable Name**: `PX_MODULE_ENABLED`

**Default**: `true`

## Module Mode

By default, the HUMAN 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](/applications/integrate-1st-party-client) 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 HUMAN 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 HTTP Method

Requests for these HTTP Methods will pass without being enforced or monitored.

Defined as part of the Property Manager rules.

Edit your **PXWorkerRule**, under the Criteria section, add another match (+match bottom on the top right side) as follows:

**Logic**: AND

**Advanced Match:** Request Method is not

Choose any HTTP method you'd like to filter

**Example**:

![](/_fern-img/7597885b2fea2490046d1e5a317fb6ec6a77467bbaff991c607f68b578451989.webp)

## 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**: `^(\/webapi\/reservation\/confirm\/?)$`

**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 HUMAN 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

Allows to set a header name which is used to extract the HUMAN cookies (processed in addition to the Cookie header).

**Property Variable Name**: `PX_CUSTOM_COOKIE_HEADER`

**Default**: `x-px-cookies`

## Custom Parameters

With the `px_enrich_custom_parameters` function you can add up to 10 custom parameters to be sent back to HUMAN servers. When set, the function is called before setting the payload on every request to HUMAN 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](https://techdocs.akamai.com/edgeworkers/docs/request-object)

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

**Default:** Empty

> **Note**
>
> Since version 3.4.0, the px\_enrich\_custom\_parameters function accepts the pxContext as a second parameter and is async, meaning it can return either `CustomParams` or `Promise<CustomParams>`.

```javascript
export async function px_enrich_custom_parameters(originalRequest: IngressClientRequest, pxContext: PXRequestContext): Promise<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 HUMAN 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](/applications/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.

## CORS Support

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.

**Property Variable Name**: `PMUSER_PX_CORS_SUPPORT_ENABLED`

**Default**: `false`

The default CORS block response headers are:

| **Header Name**                    | **Header Value**                            |
| ---------------------------------- | ------------------------------------------- |
| `access-control-allow-origin`      | The `origin` header taken from the request. |
| `access-control-allow-credentials` | `true`                                      |

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

```typescript
export function px_custom_cors_block_response_headers(
    pxCtx: PXRequestContext,
    request: EnforcedRequest,
): Record<string, string> {
    // example: return { 'allow-custom-origin': request.getHeader('origin')[0] };
    return null;
}
```

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

> **CORS Preflight Requests**
>
> Since [Akamai EdgeWorkers do not currently support the OPTIONS method](https://techdocs.akamai.com/edgeworkers/docs/event-handler-functions#event-handler-methods), CORS preflight requests are always filtered, and will not pass through the edgeworker. It is important to handle preflight requests properly, either in the elsewhere in your Akamai Property Manager or in your origin server.

## 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. 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 HUMAN for multi-step integrations and/or data correlation purposes.               | `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 `PX_CI_LS_REPORTING_METHOD` is `status`, a comma-separated list of status codes indicating successful login.                                 | `200`                        | -                                    |
| `PX_CI_LS_BODY_REGEX`       | If `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 `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 `PX_CI_LS_REPORTING_METHOD` is `header`, the expected value of the 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   | Specifies 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, defined as an exact string or regular expression.                     | -                                         |
| `sent_through`    | string   | The location of the credentials in 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:

```json
[{
    "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.

```typescript
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.

```typescript
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`        | Indicates 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. Must match those configured in the Property Manager 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

HUMAN 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              |