Fingerprint Pro Akamai Proxy Integration

Fingerprint is a device intelligence platform offering industry-leading accuracy.

Fingerprint Akamai Proxy Integration is responsible for proxying identification and agent-download requests between your website and Fingerprint through your Akamai infrastructure. The integration consists of a set of property rules you need to add to your Akamai property configuration. The property rules template is available in this repository.

🚧 Requirements and expectations

• Limited to Enterprise plan: The Akamai Proxy Integration is accessible and exclusively supported for customers on the Enterprise Plan. Other customers are encouraged to use Custom subdomain setup or Cloudflare Proxy Integration.

• Manual updates occasionally required: The underlying data contract in the identification logic can change to keep up with browser updates. Using the Akamai Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.

Warning

Tested property types

This integration has been tested with the Dynamic Site Accelerator (DSA) Akamai property type only. Ion (Standard / Premier) and API Acceleration (AA) have not been formally tested. These property types might work because Akamai's Property Manager exposes the same rule tree across them, but compatibility is not guaranteed. Validate the integration in a staging property before activating it in production. Contact support if you encounter issues.

How to install with Terraform

Note

This section assumes you use Terraform to manage your site infrastructure on Akamai and that your site uses the latest Akamai rule format.

• If you do not use Terraform, see How to install without Terraform.
• If your Akamai property uses a different rule format, please contact our support team.

This is a quick overview of the installation setup. For detailed step-by-step instructions, see the Akamai proxy integration guide in our documentation.

1. Go to Fingerprint Dashboard > API Keys and click Create Proxy Key to create a proxy secret. You will use it later to authenticate your requests to Fingerprint APIs.

2. Add the following variable blocks to the Akamai property Rules template in your Terraform configuration file. If you are using a plain JSON file instead of a rules template, reach out to our support team.

   # main.tf
   data "akamai_property_rules_template" "rules" {
         # Assuming this is property's rules file
         template_file = "/rules/main.json" 
         variables {
           name  = "fpjs_integration_path"
           value = "YOUR_INTEGRATION_PATH_HERE" # any random string that's a valid URL
           type = "string"
         }
         variables {
           name  = "fpjs_integration_path_escaped"
           value = "YOUR_INTEGRATION_PATH_ESCAPED_HERE" # same as fpjs_integration_path but with / escaped as \\/ and . escaped as \.
           type = "string"
         }
         variables {
           name  = "fpjs_agent_path"
           value = "deprecated-agent" # APIv3 only; unused on APIv4 — see note below
           type = "string"
         }
         variables {
           name  = "fpjs_result_path"
           value = "deprecated-result" # APIv3 only; unused on APIv4 — see note below
           type = "string"
         }
         variables {
           name  = "fpjs_proxy_secret"
           value = "YOUR_PROXY_SECRET_HERE" # Use the proxy secret from the previous step
           type = "string"
         }
   }

Note

fpjs_agent_path and fpjs_result_path only affect APIv3 routing. Because the integration supports both APIv3 and APIv4, you must define them even if you plan to use APIv4 only — terraform plan fails with a missing-key error if either is absent. On APIv4 the values are arbitrary; you can leave them set to "deprecated-agent" and "deprecated-result" as shown above. The status page only checks that fpjs_result_path is set, so with these placeholders it reports APIv3 as configured even if you do not use it.

3. Go to this repository latest releases and download these two JSON files:

   • terraform-fingerprint-property-rules.json
   • terraform-fingerprint-property-variables.json

4. Add the files to the rules directory of your Terraform project.

5. Reference the files inside your rules/main.json file:

   // rules/main.json
   {
     "rules": {
       "name": "default",
       "behaviors": [
         // ...
       ],
       "children": [
         //...
         // Add the downloaded rules file as a child
         "#include:terraform-fingerprint-property-rules.json" 
       ],
       // Add the downloaded variables file (or merge it with existing variables file)
       "variables": "#include:terraform-fingerprint-property-variables.json"
       // ...
     }
   }

6. Run terraform plan to review your changes and terraform apply to deploy them.

7. Configure the Fingerprint JS Agent on your website using the paths defined in Step 2.

   import * as Fingerprint from '@fingerprint/agent'
   
   const fp = Fingerprint.start({
     apiKey: 'PUBLIC_API_KEY',
     endpoints: 'https://yourwebsite.com/YOUR_INTEGRATION_PATH_HERE',
   });

See the Akamai proxy integration guide in our documentation for more details.

Building property rules for Terraform locally

If you prefer, you can clone this repository and build the property rules and variables locally.

1. Run pnpm install.
2. Run pnpm build --type terraform. It will generate the following files you can use in your Terraform configuration as described above.

• dist/terraform/terraform-fingerprint-property-rules.json
• dist/terraform/terraform-fingerprint-property-variables.json
• dist/terraform/example.tf

The JSON files are equivalent to the JSON files available in the latest releases.

How to install using Akamai Property Manager API (without Terraform)

You can clone this repository and build the property rules locally into a single body.json file. You can then apply them as a patch update to your property configuration using Akamai Property Manager API. This allows you to install the integration in an automated way even if you do not use Terraform.

1. Run pnpm install.
2. Run pnpm build --type patchBody --integration-path YOUR_INTEGRATION_PATH_HERE --agent-path YOUR_AGENT_PATH_HERE --result-path YOUR_RESULT_PATH_HERE --proxy-secret YOUR_PROXY_SECRET_HERE.
   • Use the same values you would use in Step 2 if you were installing with Terraform.
   • The command generates a dist/patch-body/body.json file. This file includes all rules and property variables necessary for the integration.
3. Use the Patch a property's rule tree endpoint of the Akamai Property Manager API to apply the generated JSON to your Akamai property.

For detailed instructions please see the Deploy Akamai Integration using Property Manager API documentation.

If you have any questions, reach out to our support team.

Status page

Once the integration is deployed, open https://yourwebsite.com/YOUR_INTEGRATION_PATH_HERE/status to check it. The page shows:

• The integration version.
• Whether the integration is Configured or Misconfigured. It is configured if at least one of the APIv4 or APIv3 checks passes.
• Whether proxy_secret and result_path are present or missing. Only presence is reported, the values are never displayed.

APIv4 requires proxy_secret; if it is missing, APIv4 and APIv3 are both reported as an error. APIv3 additionally requires result_path; if only that is missing, APIv3 is reported as a warning that can be ignored if you only use APIv4. integration_path and agent_path are not reported, as Akamai does not let you deploy the rules without them.

License

This project is licensed under the MIT license. See the LICENSE file for more info.