V4-Upgrading to Version 4

Benefits

Installable NPM Package

Prior to version 4, the enforcer was provided as pre-bundled zip files rather than an installable library, which meant it was difficult to distinguish between the enforcer (HUMAN code) and the Lambda function (your code). These were separated within the files provided, but it made customizations and updates complicated and cumbersome.

Version 4 of the HUMAN AWS Lambda@Edge Enforcer provides the enforcer as an installable NPM library rather than a zipped Lambda. This allows for a cleaner separation between HUMAN code and your Lambda code, more flexibility in how you write and deploy your Lambda function, and easier upgrades going forward. For information on how to install and use the NPM package, see the installation instructions here.

TypeScript Support

For those who prefer TypeScript, version 4 of the HUMAN AWS Lambda@Edge Enforcer also provides TypeScript definition files for the enforcer library. Adding TypeScript support reduces the likelihood of errors when configuring and integrating the enforcer into your Lambda function.

Async/Await Syntax Support

AWS Lambda functions can be written in either async/await and callback syntax. AWS recommends using async/await syntax, which is supported and used as the default in version 4. (Callback syntax is still supported by calling .then() on the Promise returned by the enforce function.)

Updating the AWS Lambda@Edge Enforcer Integration

1. In the AWS Console, navigate to your HumanEnforce (formerly PXEnforcer) Lambda function.
2. In the top right corner, click Download and then Download function code .zip (previously Actions > Export). When prompted, download the deployment package and save it locally on your computer. This will download your existing HumanEnforce (PXEnforcer) Lambda function as a .zip file, which is crucial not only for backup purposes but also to conserve your existing configuration and customizations.
3. Transfer the enforcer configuration to your new AWS Lambda@Edge project, modifying the configuration keys and values accordingly (see below). Package the code as needed.
4. In the code tab on the right, click the Upload From button and select .zip.
5. Upload the packaged code for the HumanEnforce Lambda and click Save. This will delete the old PXEnforcer Lambda function and install the new HumanEnforce Lambda instead.
6. Click the Deploy button to save the changes to AWS.
7. After testing the upgraded HumanEnforce Lambda function, deploy the function to Lambda@Edge by publishing a new version and associating the published version with your CloudFront distribution.
8. Repeat these steps with the HumanFirstParty (PXFirstParty) and HumanActivities (PXActivities) Lambda functions as needed.

Updating the Configuration

If you're upgrading from version 3.x or below of the AWS Lambda@Edge, many of the configuration fields have remained the same.

Rather than set custom functions by calling PerimeterX.SetCustomFunction(func), you can define them directly in the HumanSecurityConfiguration object.

The following configurations have changed:

• The px_pxhd_secure_enabled configuration has been renamed to px_secured_pxhd_enabled.
• SetAdditionalActivityHandler has been changed. The function signature has been modified from (pxCtx, config) => void to (config, context, request) => Promise<void> | void.
• SetEnrichCustomParamsFunction has been changed. The function signature has been modified from (customParams, request) => CustomParameters to (config, request) => Promise<CustomParameters>.
• SetCorsCustomPreflightFunction has been changed. The function signature has been modified from (request) => Response to (request) => Promise<{ body: string, headers: Record<string, string[]>, status: number }>.
• SetCorsCustomBlockResponseHeadersFunction has been changed. The function signature modified from (request) => Promise<Record<string, string>> to (request) => Promise<Record<string, string[]>>.
• SetCustomIsSensitiveRequestFunction has been changed. The function signature modified from (request, config) => boolean to (request) => boolean | Promise<boolean>
• SetLoginSuccessfulCustomCallbackFunction has been changed. The function signature modified from (response) => boolean to (response) => boolean | Promise<boolean>

The following configuration fields have been removed:

• SetCustomRequestHandler custom function
• SetExtractUserIpFunction custom function
• SetModifyContextFunction custom function
• px_send_async_activities_enabled
• px_dynamic_configuration_enabled
• px_cd_first_party_enabled
• px_testing_mode_enabled
• px_custom_template_root
• px_proxy_url
• px_telemetry_header