CloudFront Proxy Integration

Fingerprint Pro JS agent v3.6.0 or later is required.

🚧

Private Beta

Fingerprint Pro CloudFront Integration is in the private beta phase. The integration is available to select customers only and some limitations may apply. Reach out to our support at [email protected] to get more information. This guide expects a basic understanding of AWS.

Fingerprint Pro CloudFront Integration is responsible for proxying identification and agent-download requests that are performed on your AWS infrastructure.

Fingerprint Pro CloudFront Integration consists of several fundamental parts.

  • Your website, usually already running on AWS CloudFront.
  • AWS [email protected] Function that handles requests to Fingerprint Pro resources.
  • Management Lambda function that is responsible for updating the integration.
  • Additional cache behavior that enables using [email protected] function for proxying requests.
  • Other supporting resources such as CodeBuildServiceRole or Artifact Storage that are defined in the CloudFormation stack.

Fingerprint Pro CloudFormation stack creates a [email protected] Function that's available on the specific path on your site. The rest of your site is not affected.

In this documentation page, we will refer to [email protected] Function and Lambda function interchangeably.

The Lambda function code and the whole CloudFormation stack are 100% open-source and available on GitHub. Once the Fingerprint Pro JavaScript agent is configured on your site correctly, the Lambda function is responsible for delivering the latest fingerprinting client-side logic as well as proxying identification requests and responses between your site and Fingerprint Pro's APIs.

The benefits of using the CloudFront Integration

  • Significant increase in accuracy in browsers with strict privacy features such as Safari or Firefox.
  • Cookies are now recognized as “first-party.” This means they can live longer in the browser and extend the lifetime of visitor information.
  • Ad blockers will not block our Fingerprint Pro JS agent from loading. Attempts to connect to an external URL will be stopped by most ad blockers while attempts to connect to the same site URL will be allowed.
  • Ad blockers will not block our identification requests since they are sent to the specific path or subdomain that belongs to the same site.
  • Insight and control over the identification requests that can be combined with other AWS features like CloudWatch.
  • With the CloudFront Integration, you can manage an unlimited number of subdomains and paths and provide Fingerprint Pro services to all your customers at any scale while benefiting from all the 1st-party integration improvements.
  • Easy to meet compliance and auditing requirements.
  • Improved performance without the need to do the TLS handshakes.

Prerequisites

An existing CloudFront distribution that serves the web app's content or a new CloudFront distribution that is configured to serve content on the same eTLD + 1 or on any of its subdomains.

This guide discusses the configuration of Fingerprint Pro on top of the AWS CloudFront by adding cache behavior to proxy Fingerprint Pro agent and identification requests to the Fingerprint Pro API.

Integration setup

The integration setup consists of several manual and automatic steps. Each of the following steps is discussed in detail in a separate section below.

  1. Contact our support to obtain environment variables and client-side JavaScript configuration for your client-side environment.
  2. Issue a Proxy Pre-Shared Secret in the dashboard.
  3. Create a new secret in the AWS Secrets Manager to store environment variables and the Proxy Pre-Shared Secret.
  4. Install the CloudFormation application containing all the necessary resources for the integration.
  5. Configure the CloudFront distribution with the Lambda function and the cache behavior.
  6. Configure Fingerprint Pro JavaScript agent on your client side.

Step 1 - Contact support

Contact our support at [email protected] and provide us with your application name and account email. These pieces of information can be found in your dashboard.

Before the next steps, you need to obtain FPJS_BEHAVIOR_PATH, FPJS_AGENT_DOWNLOAD_PATH, and FPJS_GET_RESULT_PATH environment variables from our support team, first.

Step 2 - Issue a Proxy Pre-Shared Secret

You need to issue a Proxy Pre-Shared Secret to authenticate requests from your [email protected] function.

  1. Go to the Fingerprint Pro dashboard and select your application.
  2. In the left menu, click App settings a switch to the API keys tab.
  3. Click Create key and select Proxy Pre-Shared Secret.
  4. Click Create.

This Proxy Pre-Shared Secret value will be used later in the FPJS_PRE_SHARED_SECRET variable.

Step 3 - Create a new secret in the AWS Secrets Manager

  1. Go to AWS Secrets Manager and click Store a new secret.
  2. Choose Other type of secret as the secret type.
  3. Add the 4 required values in the Key/value pairs section:
    • The key FPJS_PRE_SHARED_SECRET with value the of the Proxy Pre-Shared Secret which was issued in step 2.
    • FPJS_BEHAVIOR_PATH, FPJS_AGENT_DOWNLOAD_PATH, and FPJS_GET_RESULT_PATH you obtained from our support team.
2000

Secrets Manager configuration.

  1. Cick Next.
  2. Specify the secret name — it will be used further in the configuration. Click Next.
  3. Leave Automatic rotation disabled and click Next.
  4. Click Store.
  5. Your secret is created. Remember the Secret name and which Region it was created in (see the upper-right corner of the screen)

Step 4 - Install the CloudFormation application

[email protected] function and corresponding settings (AWS Lambda execution role and cache policy for CDN) are provided as a CloudFormation application. Go to the application page to open the deployment dialog.

📘

Lambda region

[email protected] functions that are used to handle requests to CloudFront and responses from CloudFront must be deployed to the us-east-1 region. Make sure that you’ve selected this region before deploying the application.

Fill in the required values to the application settings and deploy the application to your AWS account.

  • TheDistributionId is the identifier of your CloudFront distribution.
  • The SecretName is the name of the secret you created in the previous step.
  • The SecretRegion is the region where the secret is stored e.g.: us-east-1.

📘

Custom IAM roles

This application creates the custom IAM roles that allow us to modify CloudFront distribution to keep the [email protected] function up to date. You can review these policies in the SAM template.

After deployment, you will be redirected to the application page where you can see a list of resources created by the application.

3010

CloudFormation stack resources.

Open the Deployments tab (see the screenshot below) and wait for the CREATE_COMPLETE status message.

3000

Deployment status.

📘

Deployment status

The Status indicates the current state of deployment. It starts from REVIEW_IN_PROGRESS to CREATE_IN_PROGRESS, and finally CREATE_COMPLETE. If you see a different status (CREATE_FAILED, ROLLBACK_IN_PROGRESS, ROLLBACK_COMPLETE, etc), please contact our support.

Once the application is fully deployed (AWS Stack has status CREATE_COMPLETE), you can click CloudFormation stack, switch to the Outputs tab, and find the names of created entities.

2062

CloudFormation outputs.

The export name of the LambdaFunctionName is a unique name of the created [email protected] function.

The export name of the CachePolicyName is a unique name of the CloudFront cache policy, which will be applied in a cache behavior for Fingerprint Pro requests.

Step 5 - Configure the CloudFront distribution

Step 5.1 - Create a new origin

  1. Go to your CloudFront distribution, switch to the Origins tab, and click Create origin.
  2. Fill required fields in the wizard:
    1. Set the origin domain to fpcdn.io.
    2. Set the protocol to HTTPS only.
    3. Set minimum origin SSL protocol to TLSv1.2.
    4. Set name to fpcdn.io.
    5. Add the following custom headers:
      • FPJS_SECRET_NAME is the name of the secret created in step 3.
      • FPJS_SECRET_REGION is the region where the secret is stored, for example, us-east-1.
    6. Finally, click Create origin.

Step 5.2 - Create a cache behavior

In this step, you will create a cache behavior to proxy requests to Fingerprint Pro API.

  1. Go to your CloudFront distribution.
  2. Switch to the Behaviors tab and click Create behavior.
  3. Fill in the required fields in the wizard
    1. Set Path pattern to a value that matches all routes under FPJS_BEHAVIOR_PATH. For example, for FPJS_BEHAVIOR_PATH=random-path you need to use random-path/*.
    2. Set Origin and origin groups to fpcdn.io.
    3. Set the Viewer protocol policy to Redirect HTTP to HTTPS.
    4. Set the Allowed HTTP methods to GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
    5. Set Cache key and origin requests to Cache policy and origin request policy (recommended).
    6. Set Cache policy to a Custom policy named FingerprintProCDNCachePolicy-{id} (you can find the name of your cache policy on the AWS Stack’s output of the application).
    7. Set Origin request policy to AllViewer.
    8. Click Create behavior.

Step 5.3 - Attach the Lambda function to the cache behavior

  1. Go to your AWS Lambda Applications and open the newly created application.
  2. On the Overview tab, scroll down to Resources a click FingerprintProCloudfrontLambda.
3012

CloudFormation Lambda function.

  1. Scroll down and switch to the Configuration tab.
  2. On the left, click Triggers, then click Add trigger.
  3. Select CloudFront as the source and click Deploy to [email protected].
1644

Add a trigger for the Lambda function.

  1. Select an option to Configure new CloudFront trigger.
    1. Select your distribution.
    2. Select the cache behavior you created in the previous step.
    3. Set CloudFront event to Origin Request.
    4. Check Include body.
    5. Check Confirm deploy to [email protected].
    6. Click Deploy.

It may take up to several minutes to add a trigger to the CloudFront distribution.
Go to the General tab of your CloudFront distribution and check the Last modified time.

Step 6 - Configure the Fingerprint Pro JavaScript agent on your client

Configure your frontend application according to the instructions provided by the Fingerprint Pro support team. If everything is configured correctly, you should receive data through your CloudFront distribution successfully.

Cost calculation for AWS

You can use AWS Calculator to estimate your expenses.

[email protected] service

  • The number of requests is roughly equal to visitor identification events multiplied by two.
    There are up to 2 requests for each visitor identification. The first request downloads the agent script, and the second calls the identification endpoint. The download agent request is cached. Caching the identification request is up to you, but most of our frontend libraries have a caching mechanism built-in.
  • The duration of each request depends on your CloudFront availability settings. The typical duration of the agent download request is 200ms, for identification requests it is 500ms.
  • The amount of memory allocated is 128MB.

Secrets Manager

  • The number of secrets is 1.
  • The number of API calls is approximately 12 calls per hour per each used AWS region.

Additional costs for the CloudFront distribution

  • Data transfer from CloudFront distribution to clients:
    • The agent’s size is about 36kB.
    • The identification request result is up to 1kB per request.
  • Data transfer from clients to the CloudFront distribution:
    • The payload size for the identification requests is approximately 5-10kB.

Troubleshooting

When troubleshooting the integration, please provide our support team with the following information.
Open your CloudFormation stack, go to the Events tab and copy the contents of the Status reason column for any failed statuses.

2052

CloudFormation errors.