You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
'twitter:description': Learn how to troubleshoot issues with custom domains.
9
9
'twitter:title': Troubleshoot Custom Domains
10
10
---
11
-
See the following video on common issues with <Tooltiptip="Custom Domain: Third-party domain with a specialized, or vanity, name."cta="View Glossary"href="/docs/glossary?term=custom+domains">custom domains</Tooltip> and refer to the sections below for troubleshooting steps for specific scenarios.
When you configure [custom domains with Auth0-managed certificates](/docs/customize/custom-domains/auth0-managed-certificates), there are two custom domain attributes that you can review to query their provision status:
15
+
16
+
*`verification`
17
+
*`certificate`
18
+
19
+
You can review the custom domain provision status using [Auth0 CLI](https://auth0.github.io/auth0-cli/) or the Management API.
20
+
21
+
### Auth0 CLI
22
+
Use the following command to list the existing domains and their status:
23
+
24
+
```bash
25
+
auth0 domains list
26
+
```
27
+
28
+
To learn more, read [Auth0 CLI](https://auth0.github.io/auth0-cli/auth0_domains_list.html) documentation.
29
+
30
+
### Auth0 Management API
31
+
32
+
Send a `GET` request to the `/api/v2/custom-domains` endpoint:
The response includes a list of your custom domains, including their `status`, `verification.status` and if verified, their `certificate.status`.
40
+
41
+
```json files
42
+
{
43
+
"custom_domain_id": "cd_9JPAp8JxtP0jvmbc",
44
+
"domain": "yellow.acmetest.org",
45
+
"primary": true,
46
+
"status": "ready",
47
+
"type": "auth0_managed_certs",
48
+
"verification": {
49
+
"methods": [...],
50
+
"status": "verified",
51
+
"last_verified_at": "2025-06-10T12:49:05Z"
52
+
},
53
+
"tls_policy": "recommended",
54
+
"certificate": {
55
+
"certificate_authority": "letsencrypt",
56
+
"status": "provisioned",
57
+
"renews_before": "2025-09-08T11:52:12Z"
58
+
}
59
+
}
60
+
```
61
+
62
+
### Verification process
63
+
64
+
When you first configure an Auth0-managed custom domain, Auth0 attempts to verify the provided custom domain DNS record. The initial custom domain `status` is set to `pending_verification` and its `verification.status` is set to `pending`.
65
+
66
+
### Certification process
67
+
68
+
Once the DNS record is successfully verified, the custom domain `verification.status` is set to `verified` and its `certificate.status` is set to `provisioning`.
69
+
70
+
When the certificate is successfully created and deployed, the `certificate.status` is set to `provisioned` and the `certificate.renews_before` attribute indicates the date by which Auth0 will automatically renew the certificate.
71
+
72
+
### Troubleshoot
73
+
74
+
If the verification process fails, the custom domain `status` is set to `failed`. You can review the `verification.error_msg` attribute to determine how to proceed.
75
+
76
+
The `verification.error_msg` attribute can be set to `DNS verification record issue`, `Domain conflicts with network configuration` or `CAA record issue`.
77
+
78
+
*`DNS verification record issue`: Auth0 could not verify your `CNAME` or `TXT` record. This can happen if the record does not exist, is incorrect, or has not propagated yet. Auth0 will attempt to verify the DNS record for up to seven days before failing.
This DNS record must remain in place permanently. Auth0 needs it to automatically renew the certificate in the future.
82
+
</Callout>
83
+
84
+
*`Domain conflicts with network configuration`: This typically means that you are using Cloudflare as the DNS provider and Zone Hold is enabled. The Zone Hold prevents Auth0 from verifying your custom hostname.
85
+
86
+
To address this error message:
87
+
1. Remove the Zone Hold from your DNS zone in Cloudflare.
88
+
2. Select **Verify** in the **Auth0 Dashboard > Branding > Custom Domains** to restart the process.
89
+
3. Once verification is successful, you can re-enable Cloudflare Zone Hold.
90
+
91
+
*`CAA record issue`: Auth0 cannot get the certificate for your custom domain.
92
+
This typically is due to your domain's DNS Certification Authority Authorization (CAA) records restricting which Certificate Authorities can issue certificates for your domain.
93
+
94
+
To address this error message:
95
+
The easiest solution is to remove your CAA records for the exact custom domain you are trying to verify. This will let Auth0 order and provision the certificate without restrictions.
96
+
97
+
You can determine your current CAA records using the `dig` command.
98
+
99
+
```bash
100
+
dig {your-custom-domain.com} +short CAA
101
+
```
102
+
103
+
Replace `your-custom-domain.com` with your actual custom domain.
14
104
15
105
## Custom domain is still pending verification
16
106
@@ -33,44 +123,26 @@ Auth0 recommends turning off CNAME flattening unless it's strictly necessary, ac
33
123
34
124
</Callout>
35
125
36
-
CNAME flattening affects the Auth0 verification and certificate renewal processes due to the way it handles DNS records. Enabling CNAME flattening in Cloudfare after setting up a custom domain does **not** prevent certificate renewal.
126
+
CNAME flattening affects the Auth0 verification and certificate renewal processes due to the way it handles DNS records. Enabling CNAME flattening in Cloudflare after setting up a custom domain does **not** prevent certificate renewal.
37
127
38
-
If you need to enable CNAME flattening for all subdomains managed by Cloudfare and also configure a specific subdomain to be an Auth0 custom domain, consider delegating the subdomain for Auth0 to another DNS provider. To learn more, read [Delegating Subdomains Outside of Cloudflare](https://support.cloudflare.com/hc/en-us/articles/360021357131-Delegating-Subdomains-Outside-of-Cloudflare) in the Cloudflare documentation. This will enable you to use CNAME flattening for all subdomains except the one used for Auth0.
128
+
If you need to enable CNAME flattening for all subdomains managed by Cloudflare and also configure a specific subdomain to be an Auth0 custom domain, consider delegating the subdomain for Auth0 to another DNS provider. To learn more, read [Delegating Subdomains Outside of Cloudflare](https://support.cloudflare.com/hc/en-us/articles/360021357131-Delegating-Subdomains-Outside-of-Cloudflare) in the Cloudflare documentation. This will enable you to use CNAME flattening for all subdomains except the one used for Auth0.
39
129
40
130
## "You should not be hitting this endpoint"
41
131
42
132
If you see this error when configuring a custom domain, you must perform additional configurations, which varies depending on your setup. To learn more, see [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains).
43
133
44
134
## "Service not found"
45
135
46
-
If your application issues an `/authorize` request with `audience=https://login.northwind.com/userinfo`, the server will return a `Service not found: https://login.northwind.com/userinfo` error. This is because even if you set a custom domain the API identifier for the `/userinfo` endpoint remains `https://{yourOriginalAuth0Domain}/userinfo`.
136
+
If your application issues an `/authorize` request with `audience=https://login.acmetest.org/userinfo`, the server will return a `Service not found: https://login.acmetest.org/userinfo` error. This is because even if you set a custom domain the API identifier for the `/userinfo` endpoint remains `https://{yourOriginalAuth0Domain}/userinfo`.
47
137
48
138
Similarly, using your custom domain in calls to the [Auth0 Management API](https://auth0.com/docs/api/management/v2) will error for the same reason.
49
139
50
140
To fix this your app should instead use `audience=https://{yourOriginalAuth0Domain}/userinfo`. You can also remove this `audience=[...]/userinfo` parameter altogether if your application is flagged as **OIDC-Conformant** in the **OAuth2** tab of the application's **Advanced Settings**.
51
141
52
-
## Errors related to Internet Explorer
53
-
54
-
If you are using Internet Explorer, you may see any of the following error messages:
55
-
56
-
* "No verifier returned from client"
57
-
* "Origin header required"
58
-
* "Failed cross origin authentication"
59
-
60
-
When both the Auth0 domain and the app domain are in the same trusted or local intranet zone, Internet Explorer does not treat the request as a cross-domain request and therefore does not send the cross-origins header.
61
-
62
-
If you see any of these errors and you are using Embedded Login, you can move one of the sites out of the trusted or local intranet zone. To do this:
63
-
64
-
1. Go to **Internet Options > Security**.
65
-
2. Select the **Local Intranet Zone** tab and go to Sites > Advanced. Add your domain.
66
-
3. Return to the **Security** tab, and make sure the proper zone has been selected.
67
-
4. Click **Custom Level** and look for **Access data sources across domains** under the **Miscellaneous** section. Check the radio button next to **Enable**.
68
-
69
-
Alternatively, you can remove reliance on cross-origin authentication by implementing [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login).
70
142
71
143
## Learn more
72
144
73
145
*[Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains)
74
146
*[Configure Custom Domains with Auth0-Managed Certificates](/docs/customize/custom-domains/auth0-managed-certificates)
75
147
*[Configure Custom Domains with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates)
76
-
*[TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl)
148
+
*[TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl)
0 commit comments