Connect an Amazon Route 53 domain

Setup type: Automatic (access role or API key). You let CustomDomain™ change the zone through a limited role in your own AWS account (recommended, nothing secret to paste), or paste an IAM access key once, and the app writes the records for you; nothing to copy by hand.

Amazon Route 53 connects through AWS's own access controls and CustomDomain™ writes the records for you, no copy-paste. The recommended way is an access role: one IAM role in your AWS account, created from our CloudFormation template, that lets us change only this domain's records in the hosted zone.

What you'll need

• A domain whose DNS is managed at Amazon Route 53.
• Access to your app's CustomDomain™ dashboard (it shows the exact target for your account).
• Permission in the AWS account that holds the hosted zone to create a CloudFormation stack (for the access role), or an IAM access key limited to that zone.

The records

CustomDomain™ gives you the authoritative records for your account in the dashboard, typically a CNAME (or apex A/ALIAS) pointing your domain at the edge. Use the values shown there; the shape is always the same, the target is per-account. There is no separate ownership TXT to add on this path: control is proven by the rail itself, or by the records appearing in your own authoritative DNS. See Setup types.

Setting it up on Amazon Route 53

1. In the console's connect flow, the access role is offered first. It opens AWS CloudFormation with our template, which creates one role limited to this zone.
2. Create the stack in your AWS account, then paste the role's ARN back into the connect flow.
3. CustomDomain™ assumes the role, writes the records for you and verifies them.

Or, with an IAM access key: use an IAM user allowed route53:ListHostedZonesByName, plus route53:ListResourceRecordSets and route53:ChangeResourceRecordSets on the hosted zone, and paste the access key ID and secret access key (and the session token, for temporary ASIA keys). The widget doesn't take provider keys from your customers; it shows them the records to add by hand.

Amazon Route 53 specifics

• The role can only add or update A, AAAA, CNAME, TXT and CAA records at the connected name, its www name and their _acme-challenge and _customdomain-challenge names, in the one hosted zone you pick. It cannot delete anything. Delete the CloudFormation stack to remove it.
• If you use a key instead, use an IAM credential scoped to Route 53, never the account's root keys.

How you know it worked

CustomDomain™ polls public DNS and issues the TLS certificate automatically. When the dashboard shows the domain live, HTTPS is serving. Drift monitoring then watches the records so a later change at the provider doesn't silently break the domain.

FAQ

What AWS permissions does this need?

Permission to change resource record sets in the specific Route 53 hosted zone for your domain, not broad AWS access. The access role's template grants that, plus reading that one zone and looking up its id by name; with a key, scope its IAM policy the same way.

Related

• All DNS providers, the full connection catalog.
• How custom domains work