Skip to content

Whitelabel Technical Implementation Guide

Overview

This guide provides technical details for implementing whitelabel domains for publishers using AWS CloudFront and Certificate Manager.

Architecture Components

AWS Services Used

  • AWS Certificate Manager (ACM) - SSL/TLS certificate provisioning and management
  • AWS CloudFront - Content delivery network and custom domain routing
  • Route 53 (optional) - DNS management for validation

Technical Flow

graph TD
    A[Publisher Domain Request] --> B[Add Domain to ACM]
    B --> C[DNS Validation Records Generated]
    C --> D[Publisher Updates DNS]
    D --> E[ACM Certificate Issued]
    E --> F[Add Domain to CloudFront Distribution]
    F --> G[Publisher Updates Final CNAME]
    G --> H[Domain Live on Platform]

Implementation Steps

Step 1: Certificate Request in ACM

  1. Navigate to AWS Certificate Manager
  2. Region: us-east-1 (required for CloudFront)

  3. Request a public certificate

  4. Add Domain Names 

    Domain name: publisher-domain.com
Additional names: *.publisher-domain.com (if wildcard needed)

  5. Validation Method

  6. Select: DNS validation
  7. This generates CNAME records for domain ownership verification

Step 2: DNS Validation Process

  1. Extract Validation Records 

    aws acm describe-certificate --certificate-arn arn:aws:acm:us-east-1:ACCOUNT:certificate/CERT-ID

  2. Provide Records to Publisher 

    Type: CNAME
Name: _validation_string.publisher-domain.com
Value: _validation_value.acm-validations.aws.
TTL: 300 (recommended)

  3. Monitor Validation Status

  4. Check ACM console for validation completion
  5. Typically completes within 24-48 hours

Step 3: CloudFront Distribution Configuration

  1. Locate Target Distribution
  2. Identify the CloudFront distribution serving the publisher platform

  3. Note the distribution ID

  4. Add Custom Domain (CNAME) 

    aws cloudfront get-distribution-config --id DISTRIBUTION_ID > current-config.json

  5. Update Distribution Configuration

  6. Add the new domain to the Aliases array
  7. Associate the ACM certificate ARN

  8. Update the distribution

  9. Example Configuration Update 

    {
  "Aliases": {
    "Quantity": 2,
    "Items": [
      "existing-domain.com",
      "new-publisher-domain.com"
    ]
  },
  "ViewerCertificate": {
    "ACMCertificateArn": "arn:aws:acm:us-east-1:ACCOUNT:certificate/CERT-ID",
    "SSLSupportMethod": "sni-only",
    "MinimumProtocolVersion": "TLSv1.2_2021"
  }
}

Step 4: Final DNS Configuration

  1. Provide CloudFront CNAME to Publisher 

    Type: CNAME
Name: publisher-domain.com
Value: d123456789.cloudfront.net
TTL: 300

  2. Verify Configuration 

    # Test DNS resolution
nslookup publisher-domain.com

# Test HTTPS connectivity
curl -I https://publisher-domain.com

Automation Scripts

Certificate Request Script

#!/bin/bash
DOMAIN=$1
REGION="us-east-1"

# Request certificate
CERT_ARN=$(aws acm request-certificate \
  --domain-name "$DOMAIN" \
  --validation-method DNS \
  --region $REGION \
  --query 'CertificateArn' \
  --output text)

echo "Certificate ARN: $CERT_ARN"

# Get validation records
aws acm describe-certificate \
  --certificate-arn "$CERT_ARN" \
  --region $REGION \
  --query 'Certificate.DomainValidationOptions[0].ResourceRecord'

Distribution Update Script

#!/bin/bash
DISTRIBUTION_ID=$1
NEW_DOMAIN=$2
CERT_ARN=$3

# Get current configuration
aws cloudfront get-distribution-config \
  --id "$DISTRIBUTION_ID" > current-config.json

# Update configuration (requires manual JSON editing)
# Then update distribution
aws cloudfront update-distribution \
  --id "$DISTRIBUTION_ID" \
  --distribution-config file://updated-config.json \
  --if-match $(jq -r '.ETag' current-config.json)

Monitoring and Troubleshooting

Health Checks

  1. Certificate Status 

    aws acm describe-certificate --certificate-arn CERT_ARN --query 'Certificate.Status'

  2. Distribution Status 

    aws cloudfront get-distribution --id DISTRIBUTION_ID --query 'Distribution.Status'

  3. Domain Resolution 

    dig publisher-domain.com CNAME
nslookup publisher-domain.com

Common Issues

Certificate Validation Fails - Verify DNS records are exactly as provided - Check for existing conflicting DNS records - Ensure TTL is not too high (recommend 300 seconds)

CloudFront Distribution Update Fails - Verify certificate is in ISSUED status - Check distribution is in Deployed status before updating - Ensure certificate is in us-east-1 region

Domain Not Accessible - Verify final CNAME points to correct CloudFront domain - Check CloudFront distribution deployment status - Test with different DNS resolvers

Logging and Monitoring

  1. CloudFront Access Logs
  2. Enable logging for the distribution

  3. Monitor for 4xx/5xx errors on new domains

  4. Certificate Expiration Monitoring

  5. Set up CloudWatch alarms for certificate expiration

  6. ACM auto-renews certificates with DNS validation

  7. Performance Monitoring

  8. Monitor CloudFront metrics for new domains
  9. Set up alerts for unusual traffic patterns

Security Considerations

Certificate Management

  • Use DNS validation (more secure than email validation)
  • Certificates are automatically renewed by ACM
  • Private keys never leave AWS infrastructure

Access Control

  • Limit ACM and CloudFront permissions to authorized personnel
  • Use IAM roles with least privilege principle
  • Log all certificate and distribution changes

Domain Security

  • Verify domain ownership before adding to platform
  • Monitor for unauthorized certificate requests
  • Implement CAA records for additional security

Best Practices

Certificate Management

  • Use wildcard certificates for subdomains when appropriate
  • Keep certificate ARNs documented and accessible
  • Monitor certificate expiration dates

CloudFront Configuration

  • Use appropriate cache behaviors for publisher content
  • Configure proper security headers
  • Enable compression for better performance

DNS Management

  • Use reliable DNS providers with good uptime
  • Implement proper TTL values for quick updates
  • Document all DNS changes and configurations

Rollback Procedures

Emergency Domain Removal

  1. Remove from CloudFront Distribution 

    # Update distribution to remove the domain from aliases
aws cloudfront update-distribution --id DISTRIBUTION_ID --distribution-config file://rollback-config.json

  2. Certificate Cleanup 

    # Delete certificate if no longer needed
aws acm delete-certificate --certificate-arn CERT_ARN

Partial Rollback

  • Remove domain from CloudFront but keep certificate for future use
  • Update DNS to point away from CloudFront temporarily

Contact and Escalation

Internal Contacts

  • DevOps Team: [Contact details]
  • Security Team: [Contact details]
  • Network Operations: [Contact details]

AWS Support

  • Use AWS Support for certificate or CloudFront issues
  • Escalate through appropriate support channels
  • Document all AWS support cases

Last updated: [Date to be added] Version: 1.0