Installing the Enforcer
Prerequisites
Installing & configuring PerimeterX AWS lambda edge enforcer requires basic knowledge in the following AWS services - CloudFront, Lambda, CloudWatch, IAM. Basic knowledge is also required in NodeJS for configuring the enforcer, adding custom functions, etc.
An AWS Account with necessary permissions for CloudFront, Lambda, CloudWatch, and IAM services is a prerequisite to install PerimeterX AWS lambda edge enforcer. This should include the necessary permissions to create and edit IAM roles. The application does not require the use of root privileges for deployment or operation.
Completing the enforcer deployment is estimated to take between 30-60 mins and will result with creating 1-3 new lambda functions, with a max size of 250kb (each), which are billable services according to your agreement with Amazon. There is no need to change current set service limits in relation to PerimeterX added Lambda functions. More information can be found here & here. The PXEnforcer Lambda function is the only mandatory function in order to enable PerimeterX Bot Defender solution on AWS.
IAM Specifications
The minimum required IAM specifications for using the PerimeterX AWS [email protected] Enforcer are the same as they would be for any [email protected] function as mentioned here. Required services include Lambda, CloudFront, IAM (to create the necessary [email protected] role and permissions), and CloudWatch (for [email protected] logging).
In order to use the PerimeterX CDN Deploy Tool to upload the PXEnforcer Lambda function and associate it with the distribution, an API Access Key is necessary. This may require permissions to create, update, and list access keys in IAM as well. The access key used for the enforcer installation must be associated with a user that has read and write access to Lambda Functions, CloudFront, and CloudWatch.
Secrets Manager
PerimeterX provides you with an application ID (px_app_id) along with two sensitive tokens: an authentication token (px_auth_token) used for validating requests sent to PerimeterX servers and a cookie secret (px_cookie_secret) used for encrypting and decrypting the PerimeterX cookie. Both of these secrets must be accessed in the PerimeterX enforcer as part of the AWS [email protected] Function.
While it is possible to hard-code these strings in the PerimeterX AWS Lambda Enforcer, it is best practice to store sensitive tokens in the AWS Secrets Manager. For more information on how to use the AWS Secrets Manager with [email protected] click here.
Enforcer Installation
Creating the Lambda Function on AWS
- In the AWS console, click Services > Compute > Lambda.
- Click Create function.
- Set the Name field to PXEnforcer, set Runtime to Node.js 16.x, and select an existing role or create a new role.
- Click Create function.
Uploading the PerimeterX Lambda Function and Required Configuration
- Under Code entry type select Upload a .ZIP file.
- Click Upload, navigate to the
PXEnforcer.zip
file provided to you by PerimeterX, and click Save. - If you haven't already, add the following mandatory parameters to the
pxConfig
object in thecustom/config.js
file:
const pxConfig = {
px_app_id: '<your app ID>',
px_cookie_secret: '<your cookie key>',
px_auth_token: '<your auth token>',
px_first_party_enabled: false,
}
Where:
Parameter | Description |
---|---|
| The PerimeterX custom application id in the format of |
| The key used by the cookie signing page. The cookie key is generated in the PerimeterX portal policy page |
| The JWT token for REST API. The Authentication Token is generated in the PerimeterX portal application page |
| first-party mode must be set to |
- Click Save.
- Click Actions and select Publish New Version. Fill in a description for the version and click Publish.
Where Can I Find the App ID, the Cookie Secret, and the Auth Token?
The PerimeterX Application ID / AppId and PerimeterX Token / Auth Token can be found in the Portal, under Platform Settings -> Applications.
PerimeterX Risk Cookie / Cookie Key can be found in the Portal, under Platform Settings -> Policies.
The Policy from where the Risk Cookie / Cookie Key is taken must correspond with the Application from where the Application ID / AppId and PerimeterX Token / Auth Token are taken.
Adding the PerimeterX Lambda Function Trigger
- Select CloudFront from the menu on the left side of the screen.
- Set CloudFront event to Viewer request.
- Ensure the box under Enable trigger and replicate is checked.
- Click Add and then Save.
First Party Installation
First party mode enables the module to send/receive data to/from the sensor, acting as a reverse-proxy for client requests and sensor activities. To setup First party mode for the PerimeterX AWS [email protected] Function, follow the steps below.
Please Note
Installing First Party is highly recommended but not mandatory to get the enforcer deployed successfully. The following steps are required only for first party mode configurations where the PXEnforcer Lambda function is triggered on the
viewer-request
event. If the PXEnforcer Lambda is triggered on theorigin-request
event or if your setup is in third party mode, the following steps are not required.
Configuring the PerimeterX First Party Cache Policy
- In the AWS console, navigate to the Cloudfront service.
- Create a new cache policy called
PXFirstPartyCachePolicy
with the following field values:
Field | Value |
---|---|
Name |
|
Description | PerimeterX cache policy for first party requests |
Minimum TTL | 0 |
Maximum TTL | 10 |
Default TTL | 5 |
Headers | Include the following: |
Cookies | Include specified cookies: |
Query Strings | All |
Creating the First-Party Lambda Function on AWS
- In the AWS console Click Services > Compute > Lambda.
- Click Create function.
- set the Name field to PXFirstParty, set Runtime to Node.js 16.x, and select an existing role or create a new role.
- Click Create function.
Uploading and Configuring the First-Party Lambda Function
- Under Code entry type select Upload a .ZIP file.
- Click Upload, navigate to the
PXFirstParty.zip
file provided to you by PerimeterX, and click Save. - If you haven't already, add the
px_app_id
field to thepxConfig
object in thecustom/config.js
file. (Only thepx_app_id
is used for this function, so it is not necessary to add your other configurations.) - Click Save.
- Click Actions and select Publish new version. Fill in a description for the version and click Publish.
Creating the First Party Cloudfront Behavior
- Select CloudFront from the menu on the left side of the screen.
- Click into the Cloudfront distribution.
- Create a new Cloudfront Behavior with the following field values:
Field | Value |
---|---|
Path Pattern |
|
Allowed HTTP Methods |
|
Cache Key and Origin Requests | Cache policy and origin request policy Cache Policy: |
Function Associations | Event: Origin Request |
- Create the behavior.
PXActivities Installation
As part of Credentials Intelligence, the PerimeterX AWS Lambda module can send the additional_s2s
activity to PerimeterX on the origin-response
event, allowing PerimeterX to analyze data related to the origin response and not just the request. This includes information about the returned HTTP status code and whether an attempted login was successful.
Please Note
The following steps are required only for configurations where credentials intelligence is enabled and the
additional_s2s
activity should be sent automatically to PerimeterX. If credentials intelligence is not enabled or if theadditional_s2s
activity will be sent manually, the following steps are not required.
Creating the PXActivities Lambda Function on AWS
- In the AWS console Click Services > Compute > Lambda.
- Click Create function.
- Set the Name field to PXActivities, set Runtime to Node.js 16.x, and select an existing role or create a new role.
- Click Create function.
Uploading and Configuring the PXActivities Lambda Function
- Under Code entry type select Upload a .ZIP file.
- Click Upload, navigate to the
PXActivities.zip
file provided to you by PerimeterX, and click Save. - If you haven't already, add the
px_app_id
field to thepxConfig
object in thecustom/config.js
file. (Only thepx_app_id
is used for this function, so it is not necessary to add your other configurations.) - Click Save.
- Click Actions and select Publish new version. Fill in a description for the version and click Publish.
Adding the PXActivities Lambda Function Trigger
- Select CloudFront from the menu on the left side of the screen.
- Set CloudFront event to Origin Response.
- Check the Confirm deploy to [email protected] checkbox.
- Click Add and then Save.
Updated 4 months ago