PerimeterX enforcer built to support NextJS applications
npm install perimeterx-nextjs``bash`
npm install perimeterx-nextjs
`javascript`
perimeterx(pxConfig)
1. Assuming you already have NextJS application, if not create a new one
2. Edit middleware.js (or middleware.ts)`
javascript`
const {perimeterx} = require("perimeterx-nextjs")
const pxConfig = {
px_app_id: "
px_cookie_secret: "
px_auth_token: "
px_module_mode: "active_blocking",
}
export default perimeterx(pxConfig)
---
Add custom code after the enforcer
`javascript
const {perimeterx} = require("perimeterx-nextjs")
const pxConfig = {
onPass: (request) => {
// This request was verified by PerimeterX
},
onResponse: (request, response) => {
// Instead of returning the block page / first party / etc...
// write a custom logic here
},
px_app_id: "
px_cookie_secret: "
px_auth_token: "
px_module_mode: "active_blocking",
// Additional configurations
}
export default perimeterx(pxConfig)
`
Required values:
* px_app_id
* px_auth_token
* px_cookie_secret
The application ID. Required to initialize the Enforcer.
`ts`
const config: PerimeterXConfigurations = {
// ...
px_app_id: '
// ...
}
The token used for authorization with the Human/PerimeterX backend. Required to initialize the Enforcer.
`ts`
const config: PerimeterXConfigurations = {
// ...
px_auth_token: '
// ...
}
The secret used to encrypt and decrypt the risk cookie. Required to initialize the Enforcer.
`ts`
const config: PerimeterXConfigurations = {
// ...
px_cookie_secret: '
// ...
}
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
`ts`
const config: PerimeterXConfigurations = {
// ...
px_module_enabled: false,
// ...
}
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 responsesactive_blocking
* - the enforcer will return block responses when needed
Default: monitor
`ts`
const config: PerimeterXConfigurations = {
// ...
px_module_mode: 'active_blocking',
// ...
}
The verbosity of the logs generated by the enforcer. The enforcer will always use the console.log() function regardless
of the configured logger severity.
Possible values:
* none - No logs will be generatederror
* - Sparse logs will be generated only when errors occurdebug
* - Detailed logs will always be generated (not advisable for production environments)
Default: error
`ts`
const config: PerimeterXConfigurations = {
// ...
px_logger_severity: 'debug',
// ...
}
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
`ts`
const config: PerimeterXConfigurations = {
// ...
px_s2s_timeout: 2000,
// ...
}
By default, the IP is taken from request.ip
However, if this is inaccurate, the enforcer can extract the IP from the headers configured here. The headers are
traversed in the order they are listed. The first header value that exists will be used as the client IP.
Default: []
`ts`
const config: PerimeterXConfigurations = {
// ...
px_ip_headers: ['true-ip', 'true-client-ip'],
// ...
}
#### px_advanced_blocking_response_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 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.
Default: true
`ts`
const config: PerimeterXConfigurations = {
// ...
px_advanced_blocking_response_enabled: false,
// ...
}
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 PerimeterX sensor from making
requests to the PerimeterX backends, which greatly limits PerimeterX's detection capabilities. To avoid this problem, first_party
enables the enforcer to be used as a proxy for PerimeterX servers, and to serve content to the browser from a first party
endpoint (i.e., an endpoint on the customer’s domain).
Default: true
`ts`
const config: PerimeterXConfigurations = {
// ...
px_first_party_enabled: false,
// ...
}
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: Empty
`ts`
const config: PerimeterXConfigurations = {
// ...
px_bypass_monitor_header: 'x-px-block',
// ...
}
Customers may want certain, but not all, endpoints to be enforced by PerimeterX, 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 defined routes will behave as if in Blocking Mode.
Default: []
`ts`
const config: PerimeterXConfigurations = {
// ...
px_enforced_routes: ['/enforced_route'],
// ...
}
Enables certain endpoints to be monitored rather than enforced by PerimeterX, even when the enforcer is in active blocking mode.
Default: []
`ts`
const config: PerimeterXConfigurations = {
// ...
px_monitored_routes: ['/monitored_route'],
// ...
}
The PerimeterX 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 PerimeterX backend. Configuring these header names as
sensitive headers will remove these headers from requests sent to other backends by PerimeterX.
Default: ['cookie', 'cookies']
`ts`
const config: PerimeterXConfigurations = {
// ...
px_sensitive_headers: ['x-sensitive-token'],
// ...
}
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.
Default: []
`ts`
const config: PerimeterXConfigurations = {
// ...
px_sensitive_routes: ['/login', '/checkout'],
// ...
}
PerimeterX does not enforce static assets such as images and documents. To prevent unnecessary API calls to PerimeterX
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.
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'
]
`ts`
const config: PerimeterXConfigurations = {
// ...
px_filter_by_extension: ['.css', '.js', '.png'],
// ...
}
PerimeterX does not enforce static assets such as images and documents. To prevent unnecessary API calls to PerimeterX
servers and needless computation, the enforcer filters all requests with a valid static file extension.
Default: []
`ts`
const config: PerimeterXConfigurations = {
// ...
px_filter_by_http_method: ['OPTIONS'],
// ...
}
Filters out requests according to their IP address, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs.
Default: []
`ts`
const config: PerimeterXConfigurations = {
// ...
px_filter_by_ip: ['1.1.1.1', '2.2.2.2/8'],
// ...
}
Routes (endpoints) specified here will not be blocked, regardless of the score they receive. A client request to an allowed
route will not generate any risk or async activities.
Default: []
`ts`
const config: PerimeterXConfigurations = {
// ...
px_filter_by_route: ['/filtered_route'],
// ...
}
Filters out requests according to their user agent value, avoiding unnecessary traffic in the enforcer verification flow and reducing operation costs.
Default: []
`ts`
const config: PerimeterXConfigurations = {
// ...
px_filter_by_user_agent: ['filtered_UA'],
// ...
}
Provides a way to include an additional custom .css file to add to the block page.
Default: Empty
`ts`
const config: PerimeterXConfigurations = {
// ...
px_css_ref: 'https://www.example.com/custom_style.css',
// ...
}
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
`ts`
const config: PerimeterXConfigurations = {
// ...
px_js_ref: 'https://www.example.com/custom_script.js',
// ...
}
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
`ts`
const config: PerimeterXConfigurations = {
// ...
px_custom_logo: 'https://www.example.com/custom_logo.png',
// ...
}
The Enforcer attempts to extract the PerimeterX cookies from the 'Cookie' header. If the PerimeterX cookies are transferred
on a header other than 'Cookies', the header name should be configured here.
Default: "x-px-cookies"
`ts`
const config: PerimeterXConfigurations = {
// ...
px_custom_cookie_header: 'x-px-cookie',
// ...
}
The maximum length of the User-Agent header. If the user agent header value exceeds this length, it will be truncated
to this length prior to processing.
Default: 8528
`ts`
const config: PerimeterXConfigurations = {
// ...
px_user_agent_max_length: 2048,
// ...
}
#### px_additional_activity_handler
The additional activity handler is a custom function passed to the enforcer. The enforcer runs this callback after
sending page_requested or block activity to the collector, and 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.
* Parameters
* config: PerimeterXConfigurations
* context: IContext
* Returns void | Promise
Default: null
`ts${context.score}
const config: PerimeterXConfigurations = {
// ...
px_additional_activity_handler: (
config: PerimeterXConfigurations,
context: IContext,
): void => {
context.requestData.request.headers.set('x-px-score', );${context.riskApiData.riskRtt}
context.requestData.request.headers.set('x-px-rtt', );`
},
// ...
}
#### px_enrich_custom_parameters
This custom function enriches activities sent from the enforcer to PerimeterX with additional custom data. This data can include
user information, session IDs, or other data that PerimeterX 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.
* Parameters
* config: PerimeterXConfigurations
* httpRequest: IIncomingRequest
* Returns CustomParameters | Promise
Default: null
`ts
import {IIncomingRequest} from "perimeterx-js-core";
const config: PerimeterXConfigurations = {
// ...
px_enrich_custom_parameters: async (
config: PerimeterXConfigurations,
httpRequest: IIncomingRequest,
): CustomParameters | Promise
try {
const body = httpRequest.method === 'POST' ? await httpRequest.json() : null;
return {
custom_param1: 'hardcoded value',
custom_param2: httpRequest.headers.get('header-name'),
custom_param3: body?.['body_property']
};
} catch (e) {
return null;
}
},
// ...
}
``