- Print
- DarkLight
Darwinium can be configured to publish workers to Amazon CloudFront. This enables you to perform decisioning at the edge using your CloudFront infrastructure.
Configuring CloudFront requires an administrator with access to the AWS CloudFront dashboard and the ability to:
create a CloudFront Distribution (if there isn't one already)
create cross-account AWS IAM roles & policies
access to the Darwinium Portal to create the target and to enter the resulting AWS ARNs.
This guide assumes familiarity with AWS, your CloudFront configuration and the setup of IAM roles.
Summary
A typical Cloudfront deployment on a one-edge deployment device takes approximately 1 hour to setup and validate under a standard configuration. Manual configuration involving Terraform will take longer.
Darwinium just requires the following identifiers to deploy.
Name | Description |
CloudFront DistributionID | CloudFront DistributionID. This will form the target for where Darwinium will deploy lambdas |
Lambda@Edge execution role ARN | Role assumed by Darwinium Lambdas on your AWS account when they are running at the edge. Depending on your configuration, this execution role will be setup to write to your events S3 bucket (if bringing your own storage) |
Deployment Role ARN | Deployment IAM role. This is used when you publish changes to your journey. It enables Darwinium to deploy new lambdas to your infrastructure, create function associations between lambdas and routes on your Cloudfront distribution, and remove these as necessary when there are changes to your Darwinium journey configuration. |
Follow security best practices!
Darwinium highly recommends that you follow this guide for setting up a user with a role granted the minimum privileges necessary to perform a deployment to your CloudFront distribution.
Never use the root user for any configuration or operations
Step 1 - Note your ExternalID from the Darwinium Portal
In the Darwinium portal, navigate:
Make sure in desired node (top right green circle) > Node settings (left side menu) > Edge Deployment (tab)
Add a new target
Assign a Target Name
Naming Tips: Target names should be short but unique, as they are included within the naming of the lambdas and CloudFront functions
A good choice is the brand/channel that Darwinium will be deployed against.
Example: retailweb
Select AWS CloudFront as the CDN Vendor
A system generated External ID for this target will appear. Copy this down somewhere - it will be used within the AWS configuration roles.
Looks like: 8aabb990-abcd-1234-b6c3-aa0bb0ccf8ac
Step 2 - Note your AWS AccountID
Login to the AWS administrator console and click on your username to the top right. Note your AWS Account ID:
Note your AWS Account ID
This will be used in subsequent steps. In the example above, an Account ID of "1234-5678-9012" will be entered as "123456789012" in role ARNs
Step 3 - (if needed) Create a CloudFront distribution
Login to the AWS console and navigate to the CloudFront dashboard. Select Distributions from the navigation menu, then Create Distribution.
Set the origin domain - this is essentially the domain that exists behind your AWS private network. This typically points to another AWS resource such as an EC2 instance, load balancer or S3 bucket.
Additional settings for accessing your origin are configured below. This is contingent upon your origin's configuration and company communication policies. Darwinium recommends using HTTPS only or Match viewer
Your Origin path should likely be left blank (however this may differ from implementation to implementation)
Give your origin a name: eg
my-service
No custom headers are needed by Darwinium, but may be configured as needed by your organization
Enable Origin Shield should be set to No
Additional Settings should be left at the AWS defaults:
Connection attempts:3
Connection timeout:10
Response timeout:30
Keep-alive timeout:5
Default cache behavior:
The following settings should be set:
Path Pattern: Default (*)
Compress objects automatically: Yes
Viewer protocol policy: Redirect HTTP to HTTPS (this will vary upon your organizations security policies and configuration. Please consult an administrator)
Allowed HTTP Methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
Restrict Viewer Access: No (this will vary upon your organizations security policies and configuration)
Cache key and origin requests
Set this to Cache policy and origin request policy:
Cache Policy: CachingOptimized
Origin Request Policy AllViewer
Response Headers Policy: : SimpleCORS (this may vary depending on your organizations security policy
Additional Settings
Additional settings can be configured as part of the organizations policy. Darwinium recommends creating a Real-time log configuration for troubleshooting the operation of the Darwinium Edge workers
Function associations
These are configured automatically by darwinium and left as No association
Settings
Settings Contingent upon your configuration - we recommend selecting Use all edge locations (best performance) and configuring an SSL certificate using the AWS certificate manager. This is also where you will input alternate domain name (CNAME) settings for your edge workers.
Take note of your domains and Distribution ID
Step 4 - (if needed) Create Policy: getfunction
This policy is only needed if you intend to use your own lambdas and CloudFront functions, alongside the ones that Darwinium will deploy. It permits Darwinium to inspect the function and lambdas already on the distribution to confirm safe deployment against the existing ones.
Go to IAM > Policies > Create Policy, with the following policy contents
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["cloudfront:GetFunction", "lambda:GetFunction"],
"Resource": "*"
}
]
}
Darwinium’s deployment manager automatically finds Lambdas and Cloudfront Functions currently on your site and calls them from inside the newly installed lambdas. If you do not intend to use your own Lambdas/Cloudfront Functions alongside Darwinium, you can skip this step.
cloudfront:GetFunction
is needed when you have Cloudfront Functions on path that you wish to protect with Darwinium
lambda:GetFunction
is needed when you have a Lambda@Edge bound to a path that you wish to protect with Darwinium.
Step 5 - Create Role: Lambda@Edge Execution
Now we need to create the AWS Policies and Roles that will permit Darwinium to deploy and run lambdas on the CloudFront. First is to Create Lambda Execution Role to allow calling your existing Cloudfront Functions and/or Lambda@edge.
When you are using a Customer Hosted (BYO) S3 bucket, the Darwinium Lambda@Edge functions will write encrypted PII data directly to your S3 bucket on your infrastructure, with no part of this write process involving Darwinium infrastructure for maximum security and performance.
In the AWS console: Go to IAM > Roles > Create Role
Specify a custom trust policy with the following contents:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"edgelambda.amazonaws.com",
"lambda.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
On the Add Permissions menu add the following policies:
AWSLambdaBasicExecutionRole
The getfunction policy created in step 4 (if you use your own lambda & CloudFront functions)
S3 write policy (if using BYOS3 storage)
Extra Considerations for BYOS3 Event Storage
BYO S3 Event Storage outlines the process for optionally setting up Darwinium with your own S3 bucket to store event details. If using this functionality, the CloudFront additionally needs to be able to write to your S3, hence why adding the S3 write-only policy that was created upon that setup.
If your BYO S3 Bucket is in a different AWS account to your Lambdas and Lambda execution role, you must also create a bucket policy for it as described in BYO S3 installation.
You will also need to create a duplicate S3 write-only IAM policy for attaching to your Lambda execution role in the account with your Lambdas. This should be identical to the main S3 write-only IAM policy created in the account with the S3 bucket.
Save and note the role ARN
Choose a name for your role and note down the ARN. Will look something like
arn:aws:iam::123456789:role/lambdarole
Step 6 - Create Policy: Darwinium CloudFront Deployment
This IAM policy will be used by Darwinium to create Lambdas & CloudFront functions and attach them to the CloudFront distribution
Go to IAM > Policies > Create Policy
Find and replace all of the CAPITALISED IDs in the following custom policy with the following
DISTRIBUTION = Your CloudFront distributionID
Looks like: EDFDVBD6EXAMPLE
AWSACCOUNTID = Your AWSAccountID from step 2
Looks like: 123456789
EXECUTIONROLEARN = Your execution role ARN from step 5
Looks like: arn:aws:iam::123456789:role/lambdarole
{
"Statement": [
{
"Action": [
"lambda:UpdateFunctionConfiguration",
"lambda:UpdateFunctionCode",
"lambda:PublishVersion",
"lambda:EnableReplication*",
"lambda:DeleteFunction",
"lambda:CreateFunction"
],
"Effect": "Allow",
"Resource": [
"arn:aws:lambda:*:AWSACCOUNTID:function:dwn*"
]
},
{
"Action": [
"iam:PassRole",
"iam:GetRole"
],
"Effect": "Allow",
"Resource": [
"EXECUTIONROLEARN"
]
},
{
"Action": [
"cloudfront:UpdateDistribution",
"cloudfront:GetDistributionConfig",
"cloudfront:GetDistribution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:cloudfront::AWSACCOUNTID:distribution/DISTRIBUTION"
]
},
{
"Action": [
"cloudfront:UpdateFunction",
"cloudfront:PublishFunction",
"cloudfront:DescribeFunction",
"cloudfront:CreateFunction",
"cloudfront:DeleteFunction"
],
"Effect": "Allow",
"Resource": [
"arn:aws:cloudfront::AWSACCOUNTID:function/dwn*"
]
},
{
"Action": [
"iam:CreateServiceLinkedRole"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iam::AWSACCOUNTID:role/aws-service-role/replicator.lambda.amazonaws.com/AWSServiceRoleForLambdaReplicator",
"arn:aws:iam::AWSACCOUNTID:role/aws-service-role/logger.cloudfront.amazonaws.com/AWSServiceRoleForCloudFrontLogger"
]
},
{
"Action": [
"lambda:ListFunctions",
"lambda:GetFunction",
"lambda:ListVersionsByFunction",
"cloudfront:ListResponseHeadersPolicies",
"cloudfront:ListOriginRequestPolicies",
"cloudfront:ListFunctions",
"cloudfront:ListDistributions",
"cloudfront:ListCachePolicies"
],
"Effect": "Allow",
"Resource": "*"
}
],
"Version": "2012-10-17"
}
Scoping:
Darwinium always prefaces its own Lambdas and Cloudfront Functions with “dwn”, so create/update/publish/delete access is limited to these names.
Darwinium needs get/list access to all Lambdas and Functions in order to detect which functions are already configured on routes that Darwinium is to protect.
Note:
If you do not have an existing Lambda@Edge function on your CloudFront distribution, you can further restrict your Darwinium CloudFront builder IAM policy as follows:
Move
lambda:GetFunction
andlambda:ListVersionsByFunction
from the clause with Resource"*"
to the clause with Resource"arn:aws:lambda:*:AWSACCOUNTID:function:dwn"
Save and note the policy name
Save the edited result as the JSON Policy and note the name of the IAM policy as you will add it to the following role.
Step 7 - Create Role: Darwinium CloudFront Deployment
This IAM Role will be assumed by Darwinium to create Lambda functions and attach them to a CloudFront distribution
Go to IAM > Roles > Create Role
Find and replace all of the CAPITALISED IDs in the following custom policy with the following
EXTERNALID = The Darwinium ExternalID that you obtained in step 1 Looks like: 8aabb990-abcd-1234-b6c3-aa0bb0ccf8ac DWNACCOUNTID = Darwinium's AWS AccountID. Contact Darwinium personnel for this value. Looks like: 123456789
Use the edited result as the custom trust policy for your new IAM Role
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::DWNACCOUNTID:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": [
"EXTERNALID"
]
},
"ArnLike": {
"aws:PrincipalArn": "arn:aws:iam::DWNACCOUNTID:role/crossaccountassumers/*"
}
}
}
]
}
(optional, only if duplicate targets required) If multiple identical Darwinium targets, can add them to the ExternalId list This is unusual but can happen when sharing repositories between nodes with unbalanced targets (eg. sandbox has single distribution for everything, production has multiple distributions).
On Add Permissions menu, select the Darwinium CloudFront builder policy that you created above
Choose an appropriate name for the role, and note down the role's ARN once created. It will look like
arn:aws:iam::123456789:role/dwndeploymentrole
Step 8 - Add the IDs into the Darwinium Portal
Navigate to the Darwinium portal and login as a user who has sufficient privileges to edit node settings.
Navigate:
Select correct node (top right green circle) > Node settings (left side menu) > Edge Deployment (tab) > Target of the EXTERNALID you were using > Deployment config
Enter the details of the AWS constructs you have made:
CloudFront DistributionID,
Your CloudFront DistributionID (possibly created in step 3),
Looks like: EDFDVBD6EXAMPLE
Lambda@Edge execution role ARN
The role to permit execution, (including writing to S3 if BYOS3) created in step 5
Looks like: arn:aws:iam::123456789:role/lambdarole
Deployment Role ARN
The role to permit Darwinium to deploy lambdas/functions to the CloudFront distribution, created in step 5
Looks like: arn:aws:iam::123456789:role/dwndeploymentrole
Publish your first Journey
In order to complete your first deployment, you will need to publish a journey.
see: Editing Overview
Monitoring & Alerting
Darwinium suggests using monitoring & alerting for tracking: Request Errors and Lambda execution times
Additional AWS Considerations
There are AWS imposed limits to be aware of when Darwinium is in operation; always check AWS documentation for the latest guidance.
Headers & URL size limit
Requests served by CloudFront have a limit of 20,480 bytes for the combined size of URL and Headers.
The Darwinium profileBlob that is collected and inserted into header can feasibly be up to ~6KB with all toggles enabled (eg. geolocation) and multiple keyboard behavioural biometrics fields profiled. It should be validated in a staging environment that your existing requests are not exceeding the overall limit by including the Darwinium profiling with desired toggles.
“Custom Headers” are those added to the request to the origin by CloudFront and have size and number limits. The Darwinium profileBlob does not impact the limits here as it is not added by CloudFront. It is not the case by default, but the Darwinium journey file can be configured to insert additional derived values into the headers; those should be reviewed if configured, but are typically single attribute values that are well under the 1,783 character limit.
See Inserting Darwinium JS Profiling for context and approaches that reduce this if needed.
Cache Behaviour Limits
Darwinium creates a bespoke behaviour for each journey step configured.
On journeys with many steps or if behaviours are already in use too, the default number provisioned by AWS (25) can be exceeded. The Darwinium Deployment manager will not be able to deploy any more steps when at this soft limit.
This is a limit you can request AWS to increase directly from their limits page, under
General quotas on distributions > Cache behaviors per distribution
https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html#limits-general
You may need written justification; an example of requesting higher limit:
We request increasing the cache behaviors limit on CloudFront distributions from 25 to 100. We use ‘Darwinium’, who are on the AWS Marketplace for security and fraud detection. That necessitates more cache behaviors to cover our site journeys. This enhancement will better support our growing infrastructure and security needs.