Server-Side IntegrationEdgio Edge Functions

Installation

Prerequisites

The HUMAN Edgio Enforcer uses Node.js and Edgio’s Edge Functions. See the prerequesites for using Edge Functions here.

The Enforcer is supported for Edgio Core v7.x and Node.js 16.x.

Installation

Cookie V2

The Edgio Edge Function Enforcer uses Bot Defender Cookie V2. If you are unable to validate this by navigating to Bot Defender > Product Settings > Security Policy > Risk Cookie Key (Advanced Settings), please reach out to our support team.

  1. Create an Edgio property and router (if you haven’t already) by following the instructions here.
  2. Install the HUMAN Enforcer NPM package into your Edgio project.
1npm i --save @humansecurity/edgio-edge-function-enforcer
  1. Modify the edgio.config.js file to include the following four origins, replacing <PX_APP_ID> with your application ID (e.g., PX12345678). For more information on the Edgio configuration file, see here.
1module.exports = {
2    name: 'example-edgio-site-name',
3    // ...
4    origins: [
5        // after including your origins...
6        {
7            name: 'hs-sapi-origin',
8            override_host_header: 'sapi-<PX_APP_ID>.perimeterx.net',
9            hosts: [{ location: 'sapi-<PX_APP_ID>.perimeterx.net' }],
10        },
11        {
12            name: 'hs-collector-origin',
13            override_host_header: 'collector-<PX_APP_ID>.perimeterx.net',
14            hosts: [{ location: 'collector-<PX_APP_ID>.perimeterx.net' }],
15        },
16        {
17            name: 'hs-client-origin',
18            override_host_header: 'client.perimeterx.net',
19            hosts: [{ location: 'client.perimeterx.net' }],
20        },
21        {
22            name: 'hs-captcha-origin',
23            override_host_header: 'captcha.px-cdn.net',
24            hosts: [{ location: 'captcha.px-cdn.net' }],
25        },
26    ],
27};
Origin Names

The default names of these origins are hs-sapi-origin, hs-collector-origin, hs-client-origin, and hs-captcha-origin. If the default hs-*-origin origin names are changed, the new origin names must be explicitly indicated in the Enforcer configuration using the px_backend_origin_name, px_backend_collector_origin_name, px_backend_client_origin_name, and px_backend_captcha_origin_name configurations, respectively.

  1. Integrate the HUMAN Enforcer into your Edge Function’s main file.

For an out-of-the box handler with the HUMAN Enforcer integrated into it already, simply import and use the createEnforcedRequestHandler function.

1import { createEnforcedRequestHandler } from '@humansecurity/edgio-enforcer';
2
3// define human security configuration
4const config = {
5    px_app_id: '<APP_ID>',
6    px_auth_token: '<AUTH_TOKEN>',
7    px_cookie_secret: '<COOKIE_SECRET>',
8    // any other configs...
9};
10
11// define what to do when requests pass HUMAN enforcement
12const onPass = (request) => {
13    console.log('handling HUMAN-validated request')
14    return fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
15};
16
17// define what to do for block responses (optional)
18const onResponse = (response) => {
19    console.log('handling response from HUMAN enforcer');
20    return response;
21};
22
23// create and export request handler
24export const handleHttpRequest = createEnforcedRequestHandler(config, onPass, onResponse);

The example below shows what the createEnforcedRequestHandler() function does behind the scenes. For a more customized solution, construct a new HumanSecurity instance, create an enforcer, and use it in the handleHttpRequest function.

The recommended usage is to:

  • create the HUMAN enforcer, call the enforce() function, and return any resulting response as early as possible in the request flow to minimize invocation of unnecessary logic.
  • call the postEnforce() right before returning the response from the request handler to ensure any necessary response modifications are performed and HUMAN data is sent to the collector.
1import { HumanSecurity } from '@humansecurity/edgio-edge-function-enforcer';
2
3// define human security configuration
4const config = {
5    px_app_id: '<APP_ID>',
6    px_auth_token: '<AUTH_TOKEN>',
7    px_cookie_secret: '<COOKIE_SECRET>',
8    // any other configs...
9};
10
11export async function handleHttpRequest(request, context) {
12    // create enforcer with configuration params
13    const enforcer = new HumanSecurity(config).createEnforcer();
14
15    // await enforcement
16    let response = await enforcer.enforce(request, context);
17
18    // return enforcer response (first party or block) if it exists
19    if (response) {
20        // if any block response modifications are needed, perform them here
21        return response;
22    }
23
24    // perform logic to fetch desired response, for example:
25    response = await fetch(request.url, { edgio: { origin: '<ORIGIN_NAME>' } });
26
27    // await any necessary post-processing
28    await enforcer.postEnforce(response);
29
30    // return response
31    return response;
32}
Using Fetch

See here for details on how to use Edgio’s built-in fetch function to make requests to your origin server.

Edge Function Limitations

Be aware of Edgio’s Edge Function limitations when developing your edge function!

  1. Use the Edgio CLI to test your edge function locally and deploy the Edgio property.
$# test locally
>edgio dev
>
># deploy to edgio
>edgio deploy