API

createDefaultHttpTrigger

Uses the provided configuration and secret key to produce the default HTTP trigger Azure Function required for a Front Door + Function App integration.

createDefaultHttpTrigger(params: ConfigurationParams, secretKey: string) => AzureFunction

• Parameters
  • params: ConfigurationParams
  • secretKey: string
• Returns an AzureFunction

The secretKey is the value that should be present on the x-enforcer-auth header, which indicates to the Front Door service that the enforcer has already processed the request. See installing the Front Door for more information.

In the event that the request should be passed to the origin, the default HTTP trigger proxies the request to the value present in the x-forwarded-host request header, which is the domain associated with the Front Door service.

Sample Usage:

import { createDefaultHttpTrigger } from 'perimeterx-azure-js-sdk';

// create an enforcer configuration
const config = {
    px_app_id: '<APP_ID>',
    px_auth_token: process.env['PX_AUTH_TOKEN'],
    px_cookie_secret: process.env['PX_COOKIE_SECRET']
};

// create a default HTTP trigger with the config and the Front Door secret key
const httpTrigger = createDefaultHttpTrigger(config, process.env['SECRET_KEY']);

// export the trigger function
export default httpTrigger;

Enforcer

The entity responsible for performing HUMAN enforcement.

Sample Usage:

import { Enforcer } from 'perimeterx-azure-js-sdk';

// create an enforcer configuration
const config = {
    px_app_id: "<APP_ID>",
    px_auth_token: "<AUTH_TOKEN>",
    px_cookie_secret: "<COOKIE_SECRET>"
};

// create a new enforcer
const enforcer = new Enforcer(config);
    
// define an HTTP trigger function
const httpTrigger = async (context: Context, req: HttpRequest) => {
    // call enforce
    const res = await enforcer.enforce(context, req);
    if (res) {
        // set response and exit if it exists
        context.res = res;
        return;
    }

    // proxy request to origin, uses provided host and additional headers
    // using 'x-forwarded-host' as host proxies the request back to Front Door
    // setting 'x-enforcer-auth' to Front Door secret key bypasses enforcer
    const response = await enforcer.proxyRequestToOrigin(req, req.headers['x-forwarded-host'], { 'x-enforcer-auth': process.env['SECRET_KEY'] });
    
    // call postEnforce and set the response
    await enforcer.postEnforce(context, response);
    context.res = response;
};

export default httpTrigger;

constructor

Creates a new instance of the Enforcer class from a ConfigurationParams object.

constructor(params: ConfigurationParams) => Enforcer

• Parameters
  • params: ConfigurationParams
• Returns a new instance of the Enforcer class

enforce

Executes the enforcement functionality, returning either null when the request should be passed to the origin, or an HttpResponse in the case of blocked or first-party requests.

enforce(context: Context, request: HttpRequest) => Promise<null | HttpResponse>

• Parameters
  • context: Context
  • request: HttpRequest
• Returns a Promise resolving to null or an HttpResponse

proxyRequestToOrigin

Sends the provided HttpRequest to the given origin and returns the response. The function automatically switches the Host header for the provided originHost value, and adds the other provided headers onto the request.

proxyRequestToOrigin(request: HttpRequest, originHost: string, headers?: Record<string, string>) => Promise<HttpResponse>

• Parameters
  • request: HttpRequest
  • originHost: string
  • headers?: Record<string, string>
• Returns a Promise resolving to an HttpResponse

In the default HTTP trigger, the originHost is taken from the x-forwarded-host header since the request is sent back to the Front Door domain. The x-enforcer-auth header, signifying that the enforcer has validated the request, is added here as well.

postEnforce

Performs any post-enforcement processing actions and final modifications to (i.e., setting cookies or headers on) the response if needed.

postEnforce(context: Context, response: HttpResponse) => Promise<void>

• Parameters
  • context: Context
  • response: HttpResponse
• Returns a Promise that resolves to void

Azure API

See the following links for more specific information about the Azure JavaScript Functions API.

• Azure Functions Node.js Reference
• NPM Azure/Functions Library