Enforcer frameworksAkamai EdgeWorker EnforcerV4

Upgrading to the Akamai EdgeWorker Enforcer v4

The HUMAN Akamai EdgeWorker Enforcer requires Property Manager Rules and Variables, the EdgeWorker, and NetStorage to work together. Migrating to version 4 of the Akamai EdgeWorker Enforcer will require changes to all these components. See below for more detailed information about how to upgrade all the different components of the Enforcer.

Sometimes, you may encounter a 500 error when the EdgeWorker initialization exceeds the CPU limit for your resource tier. For example, you may see response headers such as:

$status=InitCpuTimeoutError
$init_cpu_time=60
$res_tier=200

This error comes from Akamai EdgeWorker’s runtime limits and not HUMAN’s service. To resolve this, we recommend moving to a higher Akamai EdgeWorker resource tier.

Updating the NetStorage Files

Follow these instructions to upgrade your NetStorage configuration to work with the Akamai EdgeWorker Enforcer v4.

  1. Obtain the new static files from the HUMAN Security Akamai EdgeWorker Enforcer NPM package. NetStorage files are located in the lib/netstorage/px directory of the NPM package.
  2. Navigate to the NetStorage service in the Akamai portal.
  3. Navigate to the File Manager in NetStorage.
  4. Click into the px folder.
  5. Upload the provided files into the folder. If necessary, remove the old files.

Updating the Property Manager Rules and Variables

  1. Navigate to the Akamai Property on which the HUMAN enforcer is installed.
  2. Since published properties are not editable, create a new version of the property.
  3. Make the required revisions to the Akamai Property rules and variables. See provided screenshots of the rules required for the Akamai EdgeWorker installation. Save the property.
  4. When ready, navigate to the activate tab and activate the property on either staging or production.
Mandatory Property Manager Variables Added in v4.xInitial ValueDescriptionVisibility
PX_BACKEND_DOMAINsapi-<PX_APP_ID>.perimeterx.netBackend domain used for risk, async and telemetry activities.Visible
PX_REQUEST_IDLeave blank.Visible
PX_BACKEND_REQLeave blank.Visible
BYPASS_EW_CLTREQ_EVENTfalseBypass the onClientRequest function (not bypassed by default)Visible
BYPASS_EW_CLTRESP_EVENTfalseBypass the onClientResponse function (not bypassed by default)Visible
Property Manager Variable Name in Version 3.xChanges in Version 4.x
PX_SEND_REQ_COOKIE_NAMESThe variable has been removed. All cookie names (no values) are reported on HUMAN activities.
PX_CI_VERSIONThe variable has been deprecated in favor of the protocol field defined in the PX_CI_EXTRACT_DETAILS variable.
PX_CI_LS_REPORTING_METHODThe variable has been deprecated in favor of the login_successful_reporting_method field defined in the PX_CI_EXTRACT_DETAILS variable.
PX_CI_LS_BODY_REGEXThe variable has been deprecated in favor of the login_successful_body_regex field defined in the PX_CI_EXTRACT_DETAILS variable.
PX_CI_LS_HEADER_NAMEThe variable has been deprecated in favor of the login_successful_header_name field defined in the PX_CI_EXTRACT_DETAILS variable.
PX_CI_LS_HEADER_VALUEThe variable has been deprecated in favor of the login_successful_header_value field defined in the PX_CI_EXTRACT_DETAILS variable.
PX_SENSITIVE_ROUTESThe variable now supports regex flags in the form of /<pattern>/<flags>. Use i for case-insensitivity (e.g. /<pattern>/i).
PX_ENFORCED_ROUTESThe variable now supports regex flags in the form of /<pattern>/<flags>. Use i for case-insensitivity (e.g. /<pattern>/i).
PX_MONITORED_ROUTESThe variable now supports regex flags in the form of /<pattern>/<flags>. Use i for case-insensitivity (e.g. /<pattern>/i).
PX_FILTER_BY_ROUTEThe variable now supports regex flags in the form of /<pattern>/<flags>. Use i for case-insensitivity (e.g. /<pattern>/i).
PX_FILTER_BY_USER_AGENTThe variable now supports regex flags in the form of /<pattern>/<flags>. Use i for case-insensitivity (e.g. /<pattern>/i).
PX_SENSITIVE_GQL_OP_NAMESThe variable now supports regex flags in the form of /<pattern>/<flags>. Use i for case-insensitivity (e.g. /<pattern>/i).

Updating the EdgeWorker

  1. Use the HUMAN Security Akamai EdgeWorker Enforcer Template to create a new EdgeWorker bundle.
  2. Navigate to the EdgeWorkers service in the Akamai portal.
  3. Select the relevant EdgeWorker.
  4. Create a new version of the EdgeWorker. Upload the zipped bundle provided.
  5. When ready, activate the new version on either staging or production.

Note the following changes in the custom functions:

Function Name in Version 3.xChanges in Version 4.x
px_enrich_custom_parametersThe function signature has changed to accept the configuration and the original request rather than the original request and the HUMAN context.
px_custom_cors_block_response_headersThe function is now called px_cors_create_custom_block_response_headers. The function signature has changed to accept only the original request.
px_custom_extract_credentialsThe function has been removed in favor of the extract_credentials_callback defined in the px_login_credentials_extraction configuration.
px_login_successful_custom_callbackThe function has been removed in favor of the login_successful_callback defined in the px_login_credentials_extraction configuration.