From 131a0cd17cd3dddc6a135533ff9761f555dec8e0 Mon Sep 17 00:00:00 2001 From: Necip Allef Date: Mon, 23 Oct 2023 23:43:21 +0300 Subject: [PATCH 1/2] docs(readme): mention how to install and how to use --- README.md | 203 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 195 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 4e97faa..f4993cc 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,210 @@ +

+ + + + + Fingerprint logo + + +

+ + Current version + + + MIT license + + + Discord server + + > :warning: **Work in progress**: This is a beta version of the library # Fingerprint Pro Akamai Integration Property Rules +[Fingerprint](https://fingerprint.com) is a device intelligence platform offering 99.5% accurate visitor identification. +The Fingerprint Akamai Integration Property Rules is the repository that contains property rules and variables for the Fingerprint Akamai proxy integration. + +## Requirements +- An Akamai property + +> :warning: The Akamai integration is only available to Fingerprint customers on the Enterprise plan. Talk to our sales teams for more information. + + +## How to install + +> :warning: If you are not using Terraform, please contact our support. + +If you are using Terraform to maintain your infrastructure, then go to [the latest release](https://github.com/fingerprintjs/fingerprint-pro-akamai-integration-property-rules/releases/latest), +you will find two files: +1. Add `fingerprint-property-rules-for-terraform.json` file to the property's rules. You can find more info on this [here](https://techdocs.akamai.com/terraform/docs/set-up-property-provisioning#update-rules). +2. Merge `fingerprint-property-variables-for-terraform.json` file with your property's variables file. You do this by modifying `rules.variables` path of your rules JSON. +3. Make changes to your property's Terraform configuration. + 1. If you are using plain JSON file for rules and not using rules template, _please reach our support_. + 2. If you are using rules template, you need to specify 3 randomized values and the Fingerprint proxy secret. The 3 randomized paths are `fpjs_integration_path`, `fpjs_agent_path` and `fpjs_result_path`. You can use any valid URL paths for the 3 randomized values. + Go to the Fingerprint Dashboard [API Keys section](https://dashboard.fingerprint.com/api-keys) and press **+ Create Proxy Key** button to create the Fingerprint proxy secret. + ```hcl + data "akamai_property_rules_template" "rules" { + template_file = abspath("${path.root}/rules/main.json") # Assuming this is property's rules file + variables { + name = "fpjs_integration_path" + value = "YOUR_INTEGRATION_PATH_HERE" + type = "string" + } + variables { + name = "fpjs_agent_path" + value = "YOUR_AGENT_PATH_HERE" + type = "string" + } + variables { + name = "fpjs_result_path" + value = "YOUR_RESULT_PATH_HERE" + type = "string" + } + variables { + name = "fpjs_proxy_secret" + value = "YOUR_PROXY_SECRET_HERE" + type = "string" + } + } + ``` + The best practice for these fields is to use HashiCorp's [random provider](https://registry.terraform.io/providers/hashicorp/random/latest/docs), to use `variable` blocks and `terraform.tfvars` file. + The full example looks like below: + ```hcl + # property.tf file + resource "random_string" "fpjs_integration_path" { + length = 8 + special = false + lower = true + upper = false + numeric = true + } + + resource "random_string" "fpjs_agent_path" { + length = 8 + special = false + lower = true + upper = false + numeric = true + } + + resource "random_string" "fpjs_result_path" { + length = 8 + special = false + lower = true + upper = false + numeric = true + } + + variable "fpjs_integration_path" { + type = string + validation { + condition = can(regex("(^$|^[a-zA-Z0-9-]+$)", var.fpjs_integration_path)) + error_message = "Variable value must be a valid URL path" + } + } + + variable "fpjs_agent_path" { + type = string + validation { + condition = can(regex("(^$|^[a-zA-Z0-9-]+$)", var.fpjs_agent_path)) + error_message = "Variable value must be a valid URL path" + } + } + + variable "fpjs_result_path" { + type = string + validation { + condition = can(regex("(^$|^[a-zA-Z0-9-]+$)", var.fpjs_result_path)) + error_message = "Variable value must be a valid URL path" + } + } + + variable "fpjs_proxy_secret" { + type = string + validation { + condition = can(regex("^([a-zA-Z0-9-])+$", var.fpjs_proxy_secret)) + error_message = "Variable value must be obtained from Fingerprint dashboard" + } + } + + locals { + fpjs_integration_path = var.fpjs_integration_path != "" ? var.fpjs_integration_path : random_string.fpjs_integration_path.result + fpjs_agent_path = var.fpjs_agent_path != "" ? var.fpjs_agent_path : random_string.fpjs_agent_path.result + fpjs_result_path = var.fpjs_result_path != "" ? var.fpjs_result_path : random_string.fpjs_result_path.result + } + + data "akamai_property_rules_template" "rules" { + template_file = abspath("${path.root}/rules/main.json") # Assuming this is property's rules file + variables { + name = "fpjs_integration_path" + value = local.fpjs_integration_path + type = "string" + } + variables { + name = "fpjs_agent_path" + value = local.fpjs_agent_path + type = "string" + } + variables { + name = "fpjs_result_path" + value = local.fpjs_result_path + type = "string" + } + variables { + name = "fpjs_proxy_secret" + value = var.fpjs_proxy_secret + type = "string" + } + } + ``` + ```hcl + # terraform.tfvars file + fpjs_integration_path = "" + fpjs_agent_path = "" + fpjs_result_path = "" + fpjs_proxy_secret = "" + ``` + Note: You can leave the randomized values (`fpjs_integration_path`, `fpjs_agent_path` and `fpjs_result_path`) empty at first. They are known after `terraform apply` is run. You can then find them in the `terraform.tfstate` file and replace in your `terraform.tfvars` file. + +4. Run `terraform plan` to check your changes. If it asks you to provide values for randomized values, press enter to leave empty. They will be generated automatically. +5. Run `terraform apply` to apply changes. If it asks you to provide values for randomized values, press enter to leave empty. They will be generated automatically. +6. After `terraform apply` is completed and the property is activated, the installation is complete. You can then get randomized values from `terraform.tfstate` file and replace them inside `terraform.tfvars` file. + +## How to use + +Configure Pro Agent with corresponding randomized paths: +```js +const fpPromise = FingerprintJS.load({ + apiKey: "", + endpoint: [ + "https://your-property.com/YOUR_INTEGRATION_PATH_HERE/YOUR_RESULT_PATH_HERE", // <- ADDED THIS + defaultEndpoint + ], + scriptUrlPattern: [ + "https://your-property.com/YOUR_INTEGRATION_PATH_HERE/YOUR_AGENT_PATH_HERE?apiKey=&version=&loaderVersion=", // <- ADDED THIS + defaultScriptUrlPattern + ] +}) +``` + ## How to build property rules -### For Terraform +This section shows how to generate rules locally. This can be useful for those who don't use Terraform, don't use rules template or who want to make changes to the rules before applying them. +Please talk to Fingerprint support first if you need any help. -`yarn build --type terraform` +### For Terraform -This command generates: +Run `yarn install`. Then run `yarn build --type terraform` to generate: - `dist/terraform/json/fingerprint.json` - `dist/terraform/json/variables.json` - `dist/terraform/example.tf` -Which you can use in your current Terraform configuration. +files. Use them in your existing Terraform configuration. + +### For Akamai Public API (HTTP Patch Body) -### For API (Patch Body) +Run `yarn install`. Then run `yarn 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`. This command generates `dist/patch-body/body.json`. This file includes all rules and property variables for the integration. Use Akamai's [public API](https://techdocs.akamai.com/property-mgr/reference/patch-property-version-rules) for applying it to your property. -`yarn build --type patchBody --integration-path abc --agent-path qwe --result-path klm --proxy-secret FPJSABC123 ` +## License -This command generates `dist/patch-body` which contains `body.json`. -You can use this file to add Fingerprint Proxy Integration to your Akamai Property +This project is licensed under the MIT license. See the [LICENSE](https://github.com/fingerprintjs/fingerprint-pro-akamai-integration-property-rules/blob/main/LICENSE) file for more info. From c886276d7d341df532d6ecb472fdbd96816d43e4 Mon Sep 17 00:00:00 2001 From: Necip Allef Date: Mon, 23 Oct 2023 23:43:43 +0300 Subject: [PATCH 2/2] refactor(example): better error message --- assets/example.tf | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assets/example.tf b/assets/example.tf index 3bb3556..dbc6f85 100644 --- a/assets/example.tf +++ b/assets/example.tf @@ -50,7 +50,7 @@ variable "fpjs_proxy_secret" { type = string validation { condition = can(regex("^([a-zA-Z0-9-])+$", var.fpjs_proxy_secret)) - error_message = "Variable value must follow Fingerprint Proxy Secret pattern" + error_message = "Variable value must be obtained from Fingerprint dashboard" } }