Skip to content

Commit 32c046c

Browse files
JuroUhlarJuroUhlar
committed
docs: update readme
1 parent 2e25b96 commit 32c046c

File tree

1 file changed

+52
-146
lines changed

1 file changed

+52
-146
lines changed

‎README.md

Lines changed: 52 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<a href="https://fingerprint.com">
33
<picture>
44
<source media="(prefers-color-scheme: dark)" srcset="https://fingerprintjs.github.io/home/resources/logo_light.svg" />
5-
<source media="(prefers-color-scheme: light)" srcset=https://fingerprintjs.github.io/home/resources/logo_dark.svg" />
5+
<source media="(prefers-color-scheme: light)" srcset="https://fingerprintjs.github.io/home/resources/logo_dark.svg" />
66
<img src="https://fingerprintjs.github.io/home/resources/logo_dark.svg" alt="Fingerprint logo" width="312px" />
77
</picture>
88
</a>
@@ -14,148 +14,54 @@
1414
<a href="https://discord.gg/39EpE2neBg"><img src="https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white" alt="Discord server"></a>
1515
</p>
1616

17-
> **Warning**
18-
> This project is in the Private Beta phase. For more information, reach out
19-
> to [[email protected]](mailto:[email protected]).
20-
21-
## How to Install
22-
23-
### Using a new CloudFront distribution
24-
25-
1. Create a new directory `mkdir fingerprint_integration` and go inside `cd fingerprint_integration`
26-
2. Create a file `touch fingerprint.tf` and add below content, do not forget to replace
27-
placeholders (`AGENT_DOWNLOAD_PATH_HERE`, `RESULT_PATH_HERE`, `PROXY_SECRET_HERE`):
28-
```terraform
29-
module "fingerprint_cloudfront_integration" {
30-
source = "[email protected]:necipallef/terraform-module-proxy-lambda.git/?ref=v0.7.1"
31-
32-
fpjs_agent_download_path = "AGENT_DOWNLOAD_PATH_HERE"
33-
fpjs_get_result_path = "RESULT_PATH_HERE"
34-
fpjs_shared_secret = "PROXY_SECRET_HERE"
35-
}
36-
```
37-
3. Create a file called `cloudfront_distribution.tf` and add below content (feel free to make any changes that makes
38-
sense for your setup):
39-
```terraform
40-
41-
resource "aws_cloudfront_distribution" "fpjs_cloudfront_distribution" {
42-
comment = "Fingerprint distribution (created via Terraform)"
43-
44-
origin {
45-
domain_name = module.fingerprint_cloudfront_integration.fpjs_origin_name
46-
origin_id = module.fingerprint_cloudfront_integration.fpjs_origin_id
47-
custom_origin_config {
48-
origin_protocol_policy = "https-only"
49-
http_port = 80
50-
https_port = 443
51-
origin_ssl_protocols = ["TLSv1.2"]
52-
}
53-
custom_header {
54-
name = "FPJS_SECRET_NAME"
55-
value = module.fingerprint_cloudfront_integration.fpjs_secret_manager_arn
56-
}
57-
}
58-
59-
enabled = true
60-
61-
http_version = "http1.1"
62-
63-
price_class = "PriceClass_100"
64-
65-
default_cache_behavior {
66-
allowed_methods = ["GET", "HEAD", "OPTIONS", "PUT", "POST", "PATCH", "DELETE"]
67-
cached_methods = ["GET", "HEAD"]
68-
cache_policy_id = module.fingerprint_cloudfront_integration.fpjs_cache_policy_id
69-
origin_request_policy_id = module.fingerprint_cloudfront_integration.fpjs_origin_request_policy_id
70-
target_origin_id = module.fingerprint_cloudfront_integration.fpjs_origin_id
71-
viewer_protocol_policy = "https-only"
72-
compress = true
73-
74-
lambda_function_association {
75-
event_type = "origin-request"
76-
lambda_arn = module.fingerprint_cloudfront_integration.fpjs_proxy_lambda_arn
77-
include_body = true
78-
}
79-
}
80-
81-
viewer_certificate {
82-
cloudfront_default_certificate = true
83-
}
84-
85-
restrictions {
86-
geo_restriction {
87-
restriction_type = "none"
88-
}
89-
}
90-
}
91-
```
92-
If you wish to connect a custom domain for first-party benefits, consider changing `viewer_certificate` field
93-
accordingly. Refer
94-
to [official documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudfront_distribution)
95-
by HashiCorp for further customization.
96-
4. Run `terraform init`
97-
5. Run `terraform plan`, if all looks good run `terraform apply`
98-
99-
### Using existing CloudFront distribution
100-
101-
1. Create a file called `fingerprint.tf` and add below content, do not forget to replace
102-
placeholders (`AGENT_DOWNLOAD_PATH_HERE`, `RESULT_PATH_HERE`, `PROXY_SECRET_HERE`):
103-
```terraform
104-
module "fingerprint_cloudfront_integration" {
105-
source = "[email protected]:necipallef/terraform-module-proxy-lambda.git/?ref=v0.7.1"
106-
107-
fpjs_agent_download_path = "AGENT_DOWNLOAD_PATH_HERE"
108-
fpjs_get_result_path = "RESULT_PATH_HERE"
109-
fpjs_shared_secret = "PROXY_SECRET_HERE"
110-
}
111-
```
112-
2. Go to your CloudFront distribution block and add below content, do not forget to replace
113-
placeholders (`YOUR_INTEGRATION_PATH_HERE`):
114-
```terraform
115-
resource "aws_cloudfront_distribution" "cloudfront_dist" {
116-
// more code here
117-
118-
#region fingerprint start
119-
120-
origin {
121-
domain_name = module.fingerprint_cloudfront_integration.fpjs_origin_name
122-
origin_id = module.fingerprint_cloudfront_integration.fpjs_origin_id
123-
custom_origin_config {
124-
origin_protocol_policy = "https-only"
125-
http_port = 80
126-
https_port = 443
127-
origin_ssl_protocols = ["TLSv1.2"]
128-
}
129-
custom_header {
130-
name = "FPJS_SECRET_NAME"
131-
value = module.fingerprint_cloudfront_integration.fpjs_secret_manager_arn
132-
}
133-
}
134-
135-
ordered_cache_behavior {
136-
path_pattern = "YOUR_INTEGRATION_PATH_HERE/*"
137-
138-
allowed_methods = ["GET", "HEAD", "OPTIONS", "PUT", "POST", "PATCH", "DELETE"]
139-
cached_methods = ["GET", "HEAD"]
140-
cache_policy_id = module.fingerprint_cloudfront_integration.fpjs_cache_policy_id
141-
origin_request_policy_id = module.fingerprint_cloudfront_integration.fpjs_origin_request_policy_id
142-
target_origin_id = module.fingerprint_cloudfront_integration.fpjs_origin_id
143-
viewer_protocol_policy = "https-only"
144-
compress = true
145-
146-
lambda_function_association {
147-
event_type = "origin-request"
148-
lambda_arn = module.fingerprint_cloudfront_integration.fpjs_proxy_lambda_arn
149-
include_body = true
150-
}
151-
}
152-
153-
#endregion
154-
155-
// more code here
156-
}
157-
```
158-
3. Run `terraform plan`, if all looks good run `terraform apply`
159-
160-
> [!NOTE]
161-
> If your project doesn't use `hashicorp/random` module, then you will need to run `terraform init -upgrade`.
17+
# Fingerprint Pro CloudFront Integration (Terraform module)
18+
19+
[Fingerprint](https://fingerprint.com/) is a device intelligence platform offering 99.5% accurate visitor identification.
20+
21+
Fingerprint Pro CloudFront Integration is responsible for
22+
23+
- Proxying download requests of the latest Fingerprint Pro JS Agent between your site and Fingerprint CDN.
24+
- Proxying identification requests and responses between your site and Fingerprint Pro's APIs.
25+
26+
This [improves](https://dev.fingerprint.com/docs/cloudfront-proxy-integration#the-benefits-of-using-the-cloudfront-integration) both accuracy and reliability of visitor identification and bot detection on your site.
27+
28+
You can install the CloudFront proxy integration using a [CloudFormation template](https://github.com/fingerprintjs/fingerprint-pro-cloudfront-integration) or as a Terraform module included in this repository. For more details, see the [full documentation](https://dev.fingerprint.com/docs/cloudfront-proxy-integration-v2).
29+
30+
## Requirements
31+
32+
- AWS Account.
33+
- Access to an IAM role in AWS with privileges to manage IAM roles, CloudFront distributions, Secrets Manager, Lambda Functions, and S3 Read Only access.
34+
- Terraform project using the [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) with the IAM role described above.
35+
- [Terraform CLI](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli).
36+
37+
> [!IMPORTANT]
38+
> The AWS CloudFront Proxy Integration is exclusively supported for customers on the Enterprise Plan. Other customers are encouraged to use [Custom subdomain setup](https://dev.fingerprint.com/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](https://dev.fingerprint.com/docs/cloudflare-integration).
39+
40+
> [!WARNING]
41+
> The underlying data contract in the identification logic can change to keep up with browser updates. Using the AWS CloudFront Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.
42+
43+
## How to install
44+
45+
To set up CloudFront integration using Terraform, you need to:
46+
47+
1. Add the Fingerprint Terraform module to your Terraform project.
48+
2. Use the module in the configuration of your CloudFront distribution.
49+
3. Deploy your Terraform project.
50+
4. Configure the Fingerprint Pro JS Agent on your site to communicate with your created Lambda@Edge function using the [scriptUrlPattern](https://dev.fingerprint.com/docs/js-agent#scripturlpattern) and [endpoint](https://dev.fingerprint.com/docs/js-agent#endpoint) parameters.
51+
52+
See [CloudFront Proxy Integration guide](https://dev.fingerprint.com/docs/cloudfront-proxy-integration-v2) in our documentation for step-by-step instructions and follow the [Terraform installation method](https://dev.fingerprint.com/docs/aws-cloudfront-integration-via-terraform). If you have any questions, reach out to our [support team](https://fingerprint.com/support/).
53+
54+
## Examples
55+
56+
This repository also includes the following Terraform project examples:
57+
58+
- Adding the Fingerprint proxy integration to an [existing CloudFront distribution](./examples//existing-ditribution/)
59+
- [Creating a new CloudFront distribution](./examples/standalone-distribution/) just for the Fingerprint proxy integration
60+
61+
## How to update
62+
63+
The Terraform module does include any mechanism for automatic updates. To keep your integration up to date, please run `terraform apply` regularly.
64+
65+
## License
66+
67+
This project is licensed under the MIT license. See the [LICENSE](/LICENSE) file for more info.

0 commit comments

Comments
 (0)