DNS Approval
DNS approval requires you to publish a DNS record at the
_acme-challenge or _pki-validation
subdomain below each hostname in your desired certificate.
For example, ordering a
certificate for host.example.com may require publishing
a record at _pki-validation.host.example.com.
The certificate authority queries for the record and only
issues a certificate if the correct record is found.
For wildcard hostnames, the * component is removed when constructing
the record name.
For example, ordering a certificate for *.host.example.com would
require publishing a record at
_acme-challenge.host.example.com or _pki-validation.host.example.com.
Automatic record publication
If you integrate SSLMate with your DNS provider, SSLMate will automatically add the DNS record, allowing fully automated provisioning and renewal of certificates.
SSLMate integrates with the following DNS providers:
- Azure
- Cloudflare
- DNSimple
- DNS Made Easy
- DigitalOcean
- Gandi
- Google Cloud DNS
- Linode
- Name.com
- NS1
- Route 53
To integrate with one of these providers, visit your account's integrations page.
Security: when supported by the provider, SSLMate uses OpenID Connect (or equivalent) or OAuth to avoid the sharing of long-term API credentials. We request the minimum permissions allowed by the provider. Additionally, all access to your DNS integration is logged and mediated by a hardened service to prevent unauthorized access. Read more about the security of our DNS integration system.
DNS record delegation
Instead of integrating with your DNS provider, you can
delegate the _acme-challenge and _pki-validation subdomains
to SSLMate using an NS or CNAME record, allowing SSLMate to publish the required DNS records automatically.
The delegation only has to be done once per hostname. As long as you keep the NS or CNAME record for a hostname
in place, SSLMate will be able to automatically obtain certificates (including rekeys and renewals) for the hostname
without you needing to touch your DNS. This is not as automatic as integrating with your DNS provider,
but is significantly more convenient than manually publishing a new record every time the certificate renews.
To delegate using NS records, publish the following DNS records, which are displayed in standard zone file format. Replace HOSTNAME with the fully-qualified domain name of the hostname, and ACCOUNT_ID with your SSLMate account ID.
_acme-challenge.HOSTNAME NS ACCOUNT_ID.dns-approval.sslmate.com.
_pki-validation.HOSTNAME NS ACCOUNT_ID.dns-approval.sslmate.com.
If your DNS provider doesn't support NS records, you can publish these CNAME records instead:
_acme-challenge.HOSTNAME CNAME _acme-challenge.HOSTNAME.ACCOUNT_ID.dns-approval.sslmate.com.
_pki-validation.HOSTNAME CNAME _pki-validation.HOSTNAME.ACCOUNT_ID.dns-approval.sslmate.com.
We recommend using NS records if possible, since they're shorter.
To obtain your account ID and get instructions tailored to your account and DNS provider, visit your account's DNS Approval Delegation page.
How to use DNS approval
Specify the --approval=dns flag when ordering a certificate
with the sslmate command, or set the
approval field to dns when ordering a certificate
with the REST API.
If you have set up a DNS integration or delegation as described above, SSLMate will be able to automatically issue the certificate, and renew it in the future, without any further action on your part.
If you haven't set up an integration or delegation, then the SSLMate CLI, web console, or API
will provide the details of the DNS record that you need to publish. Once you have published
the DNS record, the certificate will be issued. Note that the sslmate command
outputs DNS records in standard zone file format.
By default, the DNS record displayed by SSLMate is an NS record. If your DNS provider doesn't
support NS records, you can configure SSLMate to display a CNAME record instead, by visiting your
account's Certificate Settings page.
To resume issuance of a certificate which was interrupted because the DNS record wasn't published yet,
run sslmate retry-approval NAME. If the record is not correctly
published, SSLMate will output it again. If it is correctly published, SSLMate
will proceed to issue the certificate.
To change an existing certificate to use DNS approval, run:
sslmate edit NAME --approval=dns.