API Domain Validation Using DNS CNAME Records
CNAME records, or Canonical Name records, are a fundamental part of DNS that allow one domain name to serve as an alias for another. They’re commonly used to simplify domain management, support third-party services, and route traffic through content delivery networks (CDNs). Whether you’re pointing www.example.com to a root domain or connecting a custom subdomain to a SaaS platform, CNAMEs offer a flexible and efficient way to manage DNS configurations.
Important Notes about CNAMEs
CNAME records behave a bit differently from other DNS records and come with a few important rules. When a DNS resolver encounters a CNAME while trying to look up another type of record – such as an A or MX record – it follows the alias and restarts the query using the new target name. However, if the resolver is specifically querying for a CNAME record, it simply returns the CNAME itself without restarting the lookup.
The destination of a CNAME can point to any valid domain, whether it’s within the same DNS zone or on a completely different server. That said, there are a couple key limitations to keep in mind
-
A domain with a CNAME record cannot have any other record types (such as A, MX, or TXT).
-
CNAMEs cannot be used at the root of a domain (also known as the zone apex), since that level requires records like NS, which must exist independently.
Create CNAME Record
Start by manually creating a CNAME record for the domain you want to secure with a certificate. This record delegates the DNS challenge to another domain where the actual TXT record will be hosted. The name of the CNAME record must begin with an underscore character “_”. The target domain in the CNAME record (where the TXT record will be hosted) may begin with an underscore, but it’s not required. The domain prefix must not be “_acme-challenge". You may use any other prefix for CNAMES with the GlobalSign Atlas APIs.
For example, if you’re issuing a certificate for example.com but want to host the TXT record at example.net, you would create one of the following CNAME records:
_globalsign-challenge.example.com CNAME _globalsign-challenge.example.net
_globalsign-challenge.example.com CNAME example.net
This tells the Atlas server and resolvers that the TXT validation token for example.com can be found at example.net.
Validate Your Domain
Once the CNAME record is in place, you may then proceed with validating the domain (also known as creating a domain claim). When you verify example.com, you specify the domain name used in the CNAME record you created in the previous step (_globalsign-challenge.example.com) in the API call as the place you want the Atlas server to look for the TXT record. The API will see that there is a CNAME record to example.net so the Atlas server will look there for the DNS TXT record. You don’t need to modify the example.com DNS in the process of this domain validation.
-
Using the Atlas API, request a domain to be verified: POST /claims/domains/{domain}.
-
Receive the token for validation.
-
Update your DNS to add a TXT record to example.net with the token (it’s OK if there are a few there already).
-
Using the Atlas API, POST /claims/domains/{claimID}/dns with the domain _globalsign-challenge.example.com (this is the domain name used in the CNAME record, not the original domain being validated).
-
The Atlas server recognizes the domain is valid by following the CNAME to example.net and locating the correct TXT record.
-
The valid TXT record is found at example.net, and the domain validation is approved.
You may delete the TXT record now if you would like.
Request the Certificate
Once the domain has been verified, you may request the certificate for example.com using the Atlas API: POST /certificates. The Atlas server will query the _globalsign-challenge.example.com record, confirm that validation has been completed, and issue the certificate for example.com.