Problem statement
After following the documented process to configure a custom domain using Auth0-managed certificates, why does the domain fail to verify?
Symptoms
The vast majority of customer attempts to create and publish their custom domain proceed without incident. However, a few of these attempts fail, with the new domain getting stuck in a “Pending verification” state.
These problems typically arise when:
- The ownership of the custom domain does not appear to be confirmed when the Verify button is pressed.
- The CNAME record is added to the DNS configuration, but the custom domain name will not resolve successfully.
A third and related issue may occur when the custom domain is successfully provisioned, but the applications do not work as expected.
Solution
Solve “Domain ownership” problems
When verifying ownership of a custom domain, a key behind-the-scenes process is publishing and linking the relevant security certificates to the new domain. Normally, this happens within a few minutes, but this may sometimes take several hours or more.
The following is a real-life example:
- A customer clicked the Verify button on August 4, 2023, @ 15:06 UTC.
- The certificates were not published until Sept 4, 2023, @ 20:37.
Auth0-managed certificates are sourced from Let’s Encrypt ( https://letsencrypt.org ), so Auth0 does not have any control over these types of unexpected delays. Until the certificates have been published, the custom domain will not be verified successfully.
If domain name ownership cannot be immediately verified, wait at least 8 hours before trying again. If after 8 hours, when clicking on Verify the process still fails, please create a support ticket.
Make sure the CNAME record is correctly configured
Once the custom domain has been verified, the next step is to add the CNAME record to the DNS configuration. This step is described in Add CNAME verification record to DNS record.
A few things can go wrong at this point:
- Verify you have correctly typed the name of the custom domain.
- If doing a copy and paste from a word processor (e.g., MS Word), ‘invisible’ characters may be accidentally introduced. Only copy from a plain text editor.
After adding the CNAME record, everything should work correctly.
To check that the DNS configuration is OK:
- Use a command-line tool such as ‘dig’, which has the format ‘dig ’, such as ‘login.example.com’.
- Use a 3rd party tool such as MXtoolbox ( DNS Lookup Tool - DNS Tools - MxToolbox ).
If those check out OK, logging in to the application using the new custom domain should be possible.
If the custom domain does not resolve successfully, it might be that the DNS provider has enabled a proxy on the CNAME by default. As mentioned in the documentation:
If your DNS provider enables a proxy on the CNAME record by default, it will leave the custom domain in a pending state indefinitely. You may need to check your DNS provider settings and request to disable the proxy.
Additional configuration for your custom domain
Once you have successfully provisioned your new custom domain, it is necessary to customize individual features to work productively with it. Review the details in Configure Features to Use Custom Domains.
If this step is omitted, the applications will not work as expected.
Additional Troubleshooting steps
If, after following all of the steps in the documentation, your custom domain still does not work, please review the troubleshooting tips in Troubleshoot Custom Domains.