Files

GitHub Actions f64e3feef8 chore: clean .gitignore cache

2026-01-26 19:22:05 +00:00

7.1 KiB

Raw Blame History

AWS Route 53 DNS Provider Setup

Overview

Amazon Route 53 is AWS's scalable DNS service. This guide covers setting up Route 53 as a DNS provider in Charon for wildcard certificate management.

Prerequisites

AWS account with Route 53 access
Domain hosted in Route 53 (public hosted zone)
IAM permissions to create users and policies
AWS CLI (optional, for verification)

Step 1: Create IAM Policy

Create a custom IAM policy with minimum required permissions:

Log in to AWS Console
Navigate to IAM → Policies
Click Create Policy
Select JSON tab
Paste the following policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "route53:ListHostedZones",
        "route53:GetChange"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": "arn:aws:route53:::hostedzone/*"
    }
  ]
}

Click Next: Tags (optional tags)
Click Next: Review
Name: CharonRoute53DNSChallenge
Description: Allows Charon to manage DNS TXT records for ACME challenges
Click Create Policy

Tip: For production, scope the policy to specific hosted zones by replacing * with your zone ID.

Step 2: Create IAM User

Create a dedicated IAM user for Charon:

Navigate to IAM → Users
Click Add Users
User name: charon-dns
Select Access key - Programmatic access
Click Next: Permissions
Select Attach existing policies directly
Search for and select CharonRoute53DNSChallenge
Click Next: Tags (optional)
Click Next: Review
Click Create User
Save the credentials (shown only once):
- Access Key ID
- Secret Access Key

Warning: Download the CSV or copy credentials immediately. AWS won't show the secret again.

Step 3: Configure in Charon

Navigate to DNS Providers in Charon
Click Add Provider
Fill in the form:
- Provider Type: Select AWS Route 53
- Name: Enter a descriptive name (e.g., "AWS Route 53 - Production")
- AWS Access Key ID: Paste the access key from Step 2
- AWS Secret Access Key: Paste the secret key from Step 2
- AWS Region: (Optional) Specify region (default: us-east-1)

Advanced Settings (Optional)

Expand Advanced Settings to customize:

Propagation Timeout: 120 seconds (Route 53 propagation can take 60-120 seconds)
Polling Interval: 10 seconds (default)
Set as Default: Enable if this is your primary DNS provider

Step 4: Test Connection

Click Test Connection button
Wait for validation (may take 5-10 seconds)
Verify you see: ✅ Connection successful

The test verifies:

Credentials are valid
IAM user has required permissions
Route 53 hosted zones are accessible

If the test fails, see Troubleshooting below.

Step 5: Save Configuration

Click Save to store the DNS provider configuration. Credentials are encrypted at rest using AES-256-GCM.

Step 6: Use with Wildcard Certificates

When creating a proxy host with a wildcard domain:

Navigate to Proxy Hosts → Add Proxy Host
Enter a wildcard domain: *.example.com
Select AWS Route 53 from the DNS Provider dropdown
Configure remaining settings
Save

Charon will automatically obtain a wildcard certificate using DNS-01 challenge.

Example Configuration

Provider Type: route53
Name: AWS Route 53 - example.com
Access Key ID: AKIAIOSFODNN7EXAMPLE
Secret Access Key: ****************************************
Region: us-east-1
Propagation Timeout: 120 seconds
Polling Interval: 10 seconds
Default: Yes

Required IAM Permissions

The IAM user needs the following Route 53 permissions:

Action	Resource	Purpose
`route53:ListHostedZones`	`*`	List available hosted zones
`route53:GetChange`	`*`	Check status of DNS changes
`route53:ChangeResourceRecordSets`	`arn:aws:route53:::hostedzone/*`	Create/delete TXT records for challenges

Security Best Practice: Scope ChangeResourceRecordSets to specific hosted zone ARNs:

"Resource": "arn:aws:route53:::hostedzone/Z1234567890ABC"

Troubleshooting

Connection Test Fails

Error: Invalid credentials

Verify Access Key ID and Secret Access Key were copied correctly
Check IAM user exists and is active
Ensure no extra spaces or characters in credentials

Error: Access denied

Verify IAM policy is attached to the user
Check policy includes all required permissions
Review CloudTrail logs for denied API calls

Error: Hosted zone not found

Ensure domain has a public hosted zone in Route 53
Verify hosted zone is in the same AWS account
Check zone is not private (private zones not supported)

Certificate Issuance Fails

Error: DNS propagation timeout

Route 53 propagation typically takes 60-120 seconds
Increase Propagation Timeout to 180 seconds
Verify hosted zone is authoritative for the domain
Check Route 53 name servers match domain registrar settings

Error: Rate limit exceeded

Route 53 has API rate limits (5 requests/second per account)
Increase Polling Interval to 15-20 seconds
Avoid concurrent certificate requests
Contact AWS support to increase limits

Region Configuration

Issue: Specifying the wrong region

Route 53 is a global service; region typically doesn't matter
Use us-east-1 (default) if unsure
Some endpoints may require specific regions
Check Charon logs if region-specific errors occur

Security Recommendations

IAM User: Create a dedicated user for Charon (don't reuse credentials)
Least Privilege: Use the minimal policy provided above
Scope to Zones: Limit policy to specific hosted zones in production
Rotate Keys: Rotate access keys every 90 days
Monitor Usage: Enable CloudTrail for API activity auditing
MFA Protection: Enable MFA on the AWS account (not the IAM user)
Access Advisor: Review IAM Access Advisor to ensure permissions are used

AWS CLI Verification (Optional)

Test credentials before adding to Charon:

# Configure AWS CLI with credentials
aws configure --profile charon-dns

# List hosted zones
aws route53 list-hosted-zones --profile charon-dns

# Verify permissions
aws iam get-user --profile charon-dns

7.1 KiB Raw Blame History