CloudFront Agent

Overview

The NetFUNNEL CloudFront agent is a NetFUNNEL-dedicated client that communicates with the NetFUNNEL server from AWS Lambda@Edge.

IAM Configuration

Create IAM Role

• Go to the IAM console in AWS.
• Click [Roles], then click [Create role].
• Select AWS service as the trusted entity and choose Lambda as the use case.
• Click [Next: Permissions].

Trust Entity Configuration

• After creating the role, go to the [Trust Entity] tab.
• Edit the Trust Entity and paste the JSON below.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "edgelambda.amazonaws.com",
          "lambda.amazonaws.com"
        ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Attach Policy

• Go to the role's [Permissions] tab.
• Click [Add permissions], then click [Create inline policy].
• Paste the policy below in the JSON tab. (This policy allows the Lambda function to create and write CloudWatch logs.)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    }
  ]
}

Create Lambda Function

warning

The Lambda function must be created in the us-east-1 (N. Virginia) region. This is an AWS requirement; this region serves as the central location for replicating the function globally.

• Go to the Lambda console in the us-east-1 region.
• Click [Create function].
• Select [Author from scratch].
• Enter a name for the function (e.g. "netfunnel-agent").
• Select Node.js as the runtime.
• In Step 1, select the IAM role you created above.
• Click [Create function].

Lambda Function Configuration

• Download the netfunnel-cloudfront-agent.js file from https://agent-lib.stclab.com/agents/cdn/cloudfront/netfunnel-cloudfront-agent-latest.js
• In the [Code] tab, add the netfunnel-cloudfront-agent.js file to the code source.
• Open the index.mjs file and add the following code.

info

You can find CLIENT_ID in the NetFUNNEL console.

import handleEvent from './netfunnel-cloudfront-agent.js';
const config = {
  clientID: "{{CLIENT_ID}}",
}
export const handler = async (event) => {
  return await handleEvent(event, config)
};

• Create a package.json file and paste the following code.

{
    "name": "cloudfront-agent",
    "type": "module",
    "dependencies": {}
}

• When finished, click the [Deploy] button.
• Go to the [Versions] tab and click [Publish new version].

CloudFront Configuration

Connect Lambda@Edge to CloudFront

• Select the CloudFront distribution ID to which you will apply Lambda@Edge.
• In the [Behaviors] tab, select an item and click [Edit].
• At the bottom under Function associations, enter the ARN of the Lambda function you created for Viewer request and Viewer response. Be sure to include the version suffix (e.g. add :1 if the version is 1).
• Click [Save changes].

CloudFront Invalidation

• Go to the [Invalidations] tab and click [Create invalidation].
• Enter /* in Object paths and click [Create invalidation].
• When invalidation completes, the Lambda@Edge association will be applied to CloudFront.

Additional Features

Good Bot Exception

You can exclude specific User-Agent values from agent behavior through Lambda configuration.

Lambda Configuration

• Open the Lambda function with the NetFUNNEL agent applied.
• Open the index.mjs file.
• Add the User-Agent values of the good bots you want to include to the goodBots array in the config object, as shown below.

info

Example code that excludes Google, Microsoft, Yahoo, Apple, and Facebook bots.

const config = {
  ...
  goodBots: ["Googlebot", "Bingbot", "Slurp", "Applebot", "facebookexternalhit"],
}

• When finished, click the [Deploy] button.
• Go to the [Versions] tab, click [Publish new version], and update the version.

CloudFront Configuration

• Select the CloudFront distribution ID with Lambda@Edge applied.
• In the [Behaviors] tab, select an item and click [Edit].
• Under Function associations at the bottom, update Viewer request and Viewer response to the new version.
• Click [Save changes].

Entry Key Auto-Return

The NetFUNNEL CloudFront agent automatically returns the NetFUNNEL key after entry so the next user in line can enter. Use this feature when you want the key to be returned at the segment timeout instead of returning it immediately.

Lambda Configuration

• Open the Lambda function with the NetFUNNEL agent applied.
• Open the index.mjs file.
• Set the returnKey property in the config object to enable or disable entry key auto-return, as shown below.

const config = {
  ...
  returnKey: true,
}

info

When set to true (default), the agent automatically returns the NetFUNNEL key when the user enters after waiting. When set to false, the key is returned at the timeout configured in the segment.

• When finished, click the [Deploy] button.
• Go to the [Versions] tab, click [Publish new version], and update the version.

CloudFront Configuration

• Select the CloudFront distribution ID with Lambda@Edge applied.
• In the [Behaviors] tab, select an item and click [Edit].
• Under Function associations at the bottom, update Viewer request and Viewer response to the new version.
• Click [Save changes].

Change Waiting Room Domain

The domain of the NetFUNNEL waiting room page is agent-lib.stclab.com. To change it to your service domain, contact the NetFUNNEL service team with your desired domain and update the Lambda configuration.

Lambda Configuration

• Open the Lambda function applied to viewer-request.
• Open the index.mjs file.
• Set the vwrPageDomain property in the config object to the waiting room URL you want to use.

info

Example code that changes the waiting room domain to wait.stclab.com.

const config = {
  ...
  vwrPageDomain: "https://wait.stclab.com",
}

• When finished, click the [Deploy] button.
• Go to the [Versions] tab, click [Publish new version], and update the version.

CloudFront Configuration

• Select the CloudFront distribution ID with Lambda@Edge applied.
• In the [Behaviors] tab, select an item and click [Edit].
• Under Function associations at the bottom, update Viewer request and Viewer response to the new version.
• Click [Save changes].

Cookie Domain Configuration

Keys issued by the NetFUNNEL server are stored in cookies based on the current page domain. To share keys across different subdomains, configure the main domain to be stored in the cookie.

info

Set to .stclab.com so that cookies are shared across pages with different subdomains, such as develop.stclab.com and staging.stclab.com.

Lambda Configuration

• Open the Lambda function applied to viewer-request.
• Open the index.mjs file.
• Set the cookieDomain property in the config object in the format .MAIN_DOMAIN, as shown below.

info

Example code that sets the cookie domain to .stclab.com.

const config = {
  ...
  cookieDomain: ".stclab.com",
}

• When finished, click the [Deploy] button.
• Go to the [Versions] tab, click [Publish new version], and update the version.

CloudFront Configuration

• Select the CloudFront distribution ID with Lambda@Edge applied.
• In the [Behaviors] tab, select an item and click [Edit].
• Under Function associations at the bottom, update Viewer request and Viewer response to the new version.
• Click [Save changes].