CloudFront

Supertab Connect integrates with AWS CloudFront for two purposes: serving your RSL license at /license.xml via your domain, and enforcing the Crawler Authentication Protocol (CAP) using Lambda@Edge and CloudFront Functions.

Publishing RSL License

Your RSL license needs to be accessible at https://yourdomain.com/license.xml. CloudFront proxies this path to the Supertab Connect origin using a CloudFront Function for URI rewriting, a new origin, and a dedicated cache behavior.

CloudFront Function

Create a function with runtime cloudfront-js-2.0. This runs on viewer request and rewrites the URI before CloudFront selects the origin.

function handler(event) {
  var request = event.request;
  var merchantURN = "YOUR_WEBSITE_URN";
  request.uri = "/merchants/systems/" + merchantURN + request.uri;
  return request;
}

Publish the function after saving.

Origin

Add an origin to your distribution:

Origin domain:  api-connect.supertab.co
Protocol:       HTTPS only
Name:           supertab-connect-origin

Cache Behavior

Create a cache behavior for /license.xml:

Setting	Value
Path pattern	`/license.xml`
Origin	`supertab-connect-origin`
Viewer protocol policy	Redirect HTTP to HTTPS
Cache policy	CachingOptimized
Origin request policy	`AllViewerExceptHostHeader`
Viewer request function	Your published CloudFront Function

Use AllViewerExceptHostHeader, not AllViewer. The SDK needs viewer headers like User-Agent for bot detection, but forwarding the Host header causes origin routing failures.

The /license.xml behavior must sit above the default * behavior in the behaviors list. Deployment takes 10–15 minutes after saving.

Terraform Alternative

If you manage your distribution with Terraform, use this configuration instead of the manual steps above.

resource "aws_cloudfront_function" "supertab_rewrite_license_path" {
  name    = "supertab-rewrite-license-path"
  runtime = "cloudfront-js-2.0"
  publish = true
  comment = "Rewrites /license.xml to the Supertab Connect URN path"

  code = <<-EOT
function handler(event) {
  var request = event.request;
  var merchantURN = "YOUR_WEBSITE_URN";
  request.uri = "/merchants/systems/" + merchantURN + request.uri;
  return request;
}
EOT
}

resource "aws_cloudfront_distribution" "your_distribution" {
  # ... your existing config ...

  origin {
    domain_name = "api-connect.supertab.co"
    origin_id   = "supertab-connect-origin"

    custom_origin_config {
      http_port              = 80
      https_port             = 443
      origin_protocol_policy = "https-only"
      origin_ssl_protocols   = ["TLSv1.2"]
    }
  }

  ordered_cache_behavior {
    path_pattern     = "/license.xml"
    allowed_methods  = ["GET", "HEAD"]
    cached_methods   = ["GET", "HEAD"]
    target_origin_id = "supertab-connect-origin"

    forwarded_values {
      query_string = false
      headers      = ["Origin"]
      cookies { forward = "none" }
    }

    function_association {
      event_type   = "viewer-request"
      function_arn = aws_cloudfront_function.supertab_rewrite_license_path.arn
    }

    viewer_protocol_policy = "redirect-to-https"
    min_ttl                = 0
    default_ttl            = 86400
    max_ttl                = 31536000
    compress               = true
  }

  depends_on = [aws_cloudfront_function.supertab_rewrite_license_path]
}

CAP Enforcement

CloudFront CAP deployment combines two edge features:

CloudFront Function (viewer request): Identifies Authorization: License headers on every request, including cache hits, without adding latency for regular traffic.
Lambda@Edge (origin request): Runs the Supertab Connect SDK to verify the token and record usage. Fires only on cache misses.

CloudFront Functions fire on every request including cache hits. Lambda@Edge origin-request fires only on cache misses. This distinction matters for billing and completeness of usage recording.

Lambda@Edge functions must be deployed in us-east-1.

Prerequisites

You need Node.js 22+, npm, and the AWS CLI configured (aws configure or aws login). If you have PowerUserAccess, that covers all IAM requirements. Otherwise, the deploying user needs a scoped policy.

Required IAM policy (replace YOUR_DISTRIBUTION_ID)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CLILogin",
      "Effect": "Allow",
      "Action": [
        "signin:AuthorizeOAuth2Access",
        "signin:CreateOAuth2Token"
      ],
      "Resource": "*"
    },
    {
      "Sid": "IAMRole",
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole",
        "iam:GetRole",
        "iam:AttachRolePolicy",
        "iam:PassRole"
      ],
      "Resource": "arn:aws:iam::*:role/supertab-edge-verify*"
    },
    {
      "Sid": "AllowServiceLinkedRoleForLambdaEdge",
      "Effect": "Allow",
      "Action": "iam:CreateServiceLinkedRole",
      "Resource": "arn:aws:iam::*:role/aws-service-role/replicator.lambda.amazonaws.com/*",
      "Condition": {
        "StringEquals": {
          "iam:AWSServiceName": "replicator.lambda.amazonaws.com"
        }
      }
    },
    {
      "Sid": "LambdaEdge",
      "Effect": "Allow",
      "Action": [
        "lambda:CreateFunction",
        "lambda:UpdateFunctionCode",
        "lambda:UpdateFunctionConfiguration",
        "lambda:GetFunction",
        "lambda:GetFunctionConfiguration",
        "lambda:PublishVersion",
        "lambda:AddPermission",
        "lambda:EnableReplication*"
      ],
      "Resource": "arn:aws:lambda:us-east-1:*:function:supertab-verify*"
    },
    {
      "Sid": "CloudFrontFunctionCreate",
      "Effect": "Allow",
      "Action": ["cloudfront:CreateFunction", "cloudfront:ListFunctions"],
      "Resource": "*"
    },
    {
      "Sid": "CloudFrontFunctionManage",
      "Effect": "Allow",
      "Action": ["cloudfront:GetFunction", "cloudfront:DescribeFunction", "cloudfront:UpdateFunction", "cloudfront:PublishFunction"],
      "Resource": "arn:aws:cloudfront::*:function/supertab-*"
    },
    {
      "Sid": "CloudFrontCachePolicyManage",
      "Effect": "Allow",
      "Action": ["cloudfront:ListCachePolicies", "cloudfront:CreateCachePolicy"],
      "Resource": "*"
    },
    {
      "Sid": "CloudFrontDistributionManage",
      "Effect": "Allow",
      "Action": [
        "cloudfront:GetDistribution",
        "cloudfront:GetDistributionConfig",
        "cloudfront:UpdateDistribution"
      ],
      "Resource": "arn:aws:cloudfront::*:distribution/YOUR_DISTRIBUTION_ID"
    }
  ]
}

Step 1: Build the Lambda Package

mkdir supertab-verify && cd supertab-verify
npm init -y
npm install @getsupertab/supertab-connect-sdk
npm install -D esbuild typescript @types/aws-lambda

Create index.ts:

import { SupertabConnect } from "@getsupertab/supertab-connect-sdk";
import type { CloudFrontRequestEvent, CloudFrontRequestResult } from "aws-lambda";

export async function handler(
  event: CloudFrontRequestEvent
): Promise<CloudFrontRequestResult> {
  return SupertabConnect.cloudfrontHandleRequests(event, {
    apiKey: "YOUR_MERCHANT_API_KEY", // from your Supertab Connect dashboard
  });
}

Add build scripts to package.json:

{
  "scripts": {
    "build": "esbuild index.ts --bundle --platform=node --target=node22 --outfile=dist/index.js --format=cjs",
    "package": "cd dist && zip -r function.zip index.js",
    "bundle": "npm run build && npm run package"
  }
}

Build:

npm run bundle

This produces dist/function.zip.

Step 2: Deploy to AWS

Deployment creates three resources: an IAM execution role (assumable by both lambda.amazonaws.com and edgelambda.amazonaws.com, with AWSLambdaBasicExecutionRole for CloudWatch logging), the Lambda function in us-east-1 (required for Lambda@Edge — CloudFront replicates it globally from there), and a published, numbered version that CloudFront is granted permission to invoke at the edge. Lambda@Edge cannot use $LATEST. The script below does all three and is idempotent — re-run it after any handler change and it publishes a new version. Save it as deploy.sh in your supertab-verify directory.

deploy.sh

#!/bin/bash

FUNCTION_NAME="supertab-verify"
ROLE_NAME="supertab-edge-verify"

ACCOUNT_ID=$(aws sts get-caller-identity --query 'Account' --output text)
if [ -z "$ACCOUNT_ID" ]; then
  echo "❌ AWS CLI not configured. Run 'aws configure' first."
  exit 1
fi

echo ""
echo "=== Deploying Lambda@Edge (Account: $ACCOUNT_ID) ==="
echo ""

# 1. Create execution role
echo "Step 1/4 — Creating IAM role..."
cat > /tmp/trust-policy.json << 'EOF'
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": { "Service": ["lambda.amazonaws.com", "edgelambda.amazonaws.com"] }, "Action": "sts:AssumeRole" }] }
EOF

if aws iam create-role --role-name $ROLE_NAME \
  --assume-role-policy-document file:///tmp/trust-policy.json; then
  echo "  ✅ Created role: $ROLE_NAME"
else
  if aws iam get-role --role-name $ROLE_NAME > /dev/null 2>&1; then
    echo "  ✅ Role already exists: $ROLE_NAME"
  else
    echo "  ❌ Failed to create role"
    exit 1
  fi
fi

echo "  ⏳ Attaching execution policy..."
aws iam attach-role-policy --role-name $ROLE_NAME \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole || true
echo "  ✅ Logging permissions attached"
echo "  ⏳ Waiting for IAM propagation..."
sleep 10

# 2. Create or update Lambda function (must be us-east-1)
echo "Step 2/4 — Deploying function..."
if aws lambda get-function --function-name $FUNCTION_NAME --region us-east-1 > /dev/null 2>&1; then
  echo "  ℹ️  Function exists, updating..."
  aws lambda update-function-code --function-name $FUNCTION_NAME \
    --zip-file fileb://dist/function.zip --region us-east-1 || {
    echo "  ❌ Failed to update function"
    exit 1
  }
  aws lambda wait function-updated --function-name $FUNCTION_NAME --region us-east-1 || {
    echo "  ❌ Failed waiting for function update"
    exit 1
  }
  echo "  ✅ Code updated"
else
  echo "  ℹ️  Creating new function..."
  aws lambda create-function --function-name $FUNCTION_NAME --runtime nodejs22.x \
    --role arn:aws:iam::${ACCOUNT_ID}:role/${ROLE_NAME} --handler index.handler \
    --zip-file fileb://dist/function.zip --timeout 10 --memory-size 128 \
    --region us-east-1 || {
    echo "  ❌ Failed to create function"
    exit 1
  }
  echo "  ✅ Function created"
fi

echo "  ⏳ Waiting for function to be ready..."
sleep 5

# 3. Publish version (Lambda@Edge requires numbered versions, not $LATEST)
echo "Step 3/4 — Publishing version..."
VERSION=$(aws lambda publish-version --function-name $FUNCTION_NAME \
  --region us-east-1 --query 'Version' --output text) || {
  echo "  ❌ Failed to publish version"
  exit 1
}
echo "  ✅ Published version: $VERSION"

# 4. Grant CloudFront permission to invoke at edge locations
echo "Step 4/4 — Granting edge permissions..."
aws lambda add-permission --function-name ${FUNCTION_NAME}:${VERSION} \
  --statement-id "cf-get-${VERSION}" --action lambda:GetFunction \
  --principal edgelambda.amazonaws.com --region us-east-1 || true

aws lambda add-permission --function-name ${FUNCTION_NAME}:${VERSION} \
  --statement-id "cf-invoke-${VERSION}" --action lambda:InvokeFunction \
  --principal edgelambda.amazonaws.com --region us-east-1 || true
echo "  ✅ CloudFront can invoke version $VERSION"

# Done
ARN="arn:aws:lambda:us-east-1:${ACCOUNT_ID}:function:${FUNCTION_NAME}:${VERSION}"
echo ""
echo "=== ✅ Done ==="
echo "Function ARN (copy this for Step 4):"
echo "  $ARN"
echo ""

Run it:

chmod +x deploy.sh
./deploy.sh

Save the version ARN from the output — you need it in Step 4.

Prefer the console? Create the role with the Lambda + edgelambda trust policy (shown in the script above), create the function (nodejs22.x, us-east-1, handler index.handler, timeout 10s, memory 128 MB), upload dist/function.zip, publish a numbered version, then grant lambda:GetFunction and lambda:InvokeFunction to the edgelambda.amazonaws.com principal on that version. If you update your handler later, publish a new version and repoint the behavior to the new ARN.

Step 3: Create the Filtering Function

Create a CloudFront Function (cloudfront-js-2.0 runtime) that runs on viewer request. It checks whether the Authorization header contains a license token. If it does, it adds x-license-auth to the request headers — this header is used in the cache key to separate licensed and unlicensed cache entries, and its presence triggers the Lambda@Edge function on cache misses.

function isLicenseRequest(request) {
  var authHeader = (request.headers || {}).authorization;
  var authValue = authHeader && authHeader.value ? authHeader.value : "";
  return authValue.length > 7 && authValue.slice(0, 8).toLowerCase() === "license ";
}

function handler(event) {
  var request = event.request;
  var headers = request.headers || {};

  if (isLicenseRequest(request)) {
    request.headers["x-license-auth"] = { value: event.context.requestId };
    request.headers["x-original-request-url"] = {
      value: (headers.host && headers.host.value ? headers.host.value : "") + request.uri,
    };
  }

  return request;
}

Publish the function after saving.

Step 4: Configure the Cache Behavior

Edit the behavior for the path you want to protect (the default * behavior for all requests, or a specific path like /articles/*). Cache policy — Create a custom cache policy with x-license-auth included in the cache key headers. This ensures that requests with and without a license token produce separate cache entries — without it, a cached response from a licensed request could be served to unlicensed requests. Keep defaults for TTL, query strings, cookies, and compression. Origin request policy — Set to AllViewerExceptHostHeader. This forwards viewer headers (including User-Agent for bot detection) to the origin while letting CloudFront set the correct origin hostname.

Do not use AllViewer — it forwards the original Host header, which causes routing failures on S3 and API Gateway origins.

Function associations:

Event	Type	Value
Viewer request	CloudFront Functions	Your published filtering function from Step 3
Origin request	Lambda@Edge	Published version ARN from Step 2

Save and wait for the distribution to deploy (10–15 minutes).

Purge Cached License

After you publish a new license version, CloudFront may keep serving the cached copy for up to 24 hours. Invalidate the license path to force a refresh. In the console, open your distribution → Invalidations → Create invalidation, and enter:

/merchants/systems/YOUR_WEBSITE_URN/license.xml

Or via the CLI:

aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/merchants/systems/YOUR_WEBSITE_URN/license.xml"

Invalidation completes in 5–15 minutes. Confirm the update at https://yourdomain.com/license.xml.

Deploy in Your CDN

CDN-agnostic guide covering RSL serving, CAP enforcement, and robots.txt.

Other CDNs

Generic CDN patterns for platforms not listed above.

Introduction

Guides

Licensing

Reference

Publishing RSL License

CloudFront Function

Origin

Cache Behavior

CAP Enforcement

Prerequisites

Step 1: Build the Lambda Package

Step 2: Deploy to AWS

Step 3: Create the Filtering Function

Step 4: Configure the Cache Behavior

Purge Cached License

Deploy in Your CDN

Other CDNs

​Publishing RSL License

​CloudFront Function

​Origin

​Cache Behavior

​CAP Enforcement

​Prerequisites

​Step 1: Build the Lambda Package

​Step 2: Deploy to AWS

​Step 3: Create the Filtering Function

​Step 4: Configure the Cache Behavior

​Purge Cached License

​Related Docs

Deploy in Your CDN

Other CDNs

Publishing RSL License

CloudFront Function

Origin

Cache Behavior

CAP Enforcement

Prerequisites

Step 1: Build the Lambda Package

Step 2: Deploy to AWS

Step 3: Create the Filtering Function

Step 4: Configure the Cache Behavior

Purge Cached License

Related Docs