Custom Domains
Auth0 allows you to map the domain for your tenant to one custom domain of your choosing. This allows you to maintain a consistent experience for your users by keeping them on your domain instead of redirecting or using Auth0's domain. You must register and own the domain name to which you are mapping your Auth0 domain. For example, if your Auth0 domain is northwind.auth0.com, you can have your users to see, use, and remain on login.northwind.com.
We recommend that you use custom domains with Universal Login for the most seamless and secure experience for your users. To determine whether your use case requires custom domains, see Universal Login.
HTTP best practices and common errors
It is important that you abide by HTTP best practices. Some common errors due to not following these best practices are:
Sending duplicate headers if field order is not correct. See https://tools.ietf.org/html/rfc7230#section-3.2.2 for details.
Creating a CNAME record without declaring it to Auth0, preventing Auth0 from verifying or using the custom domain.
Token issuance
Auth0 issues tokens with the iss
claim of whichever domain you used with the request. For example:
If you use | iss claim value with custom domain |
---|---|
https://northwind.auth0.com/authorize... https://northwind.auth0.com/oauth/token... |
https://northwind.auth0.com/ |
https://login.northwind.com/authorize... https://login.northwind.com/oauth/token... |
https://login.northwind.com/ |
If you get an Access Token for the Management API using an authorization flow with your custom domain, you must call the Management API using the custom domain (your token will be considered invalid otherwise).
Note that the tokens iss
claim is independant of the audience. Audience values remain the same for tokens obtained using a custom domain.
Metadata endpoints
Auth0 implements certain Metadata endpoints to ease interoperability and configuration of third-party IdPs and applications. When these metadata contain URIs pointing back to Auth0, the URL can either use the Auth0 subdomain or your custom domain depending on the hostname used to request the metadata.
If you use | Reference inside metadata |
---|---|
https://northwind.auth0.com/.well-known/... |
https://northwind.auth0.com/... |
https://northwind.auth0.com/samlp/metadata/... |
https://northwind.auth0.com/... |
https://login.northwind.com/samlp/metadata/... |
https://login.northwind.com/... |
This applies to the following features:
Allow listing
Be aware that Auth0 does not provide a static list of IP addresses because they are subject to change. We recommend that you add your custom domain to the Allow List instead.
Access exceptions
You can use either your YOUR_DOMAIN
domain to access Auth0 or your custom domain. There are, however, a few exceptions:
If you use embedded Lock or an SDK, the configuration is pre-defined to use either your custom domain or the
YOUR_DOMAIN
domain, so you have to use one or the other.If you start a session in
YOUR_DOMAIN
, and go tocustom-domain.com
, the user will have to login again.
Auth0 features that use custom domains
The following Auth0 features can use custom domains. See Configure Custom Domains for Specific Features for details.
Features/Flows | Details |
---|---|
Universal Login | For a seamless and secure user experience |
MFA | All factors |
Guardian | MFA Widget version 1.3.3/Guardian.js version 1.3.0 or later |
Emails | Links included in the emails use your custom domain |
Connections | Database, social, Google Workspace, Azure AD, ADFS, AD/LDAP |
Lock | Version 11 with cross-origin authentication |
Passwordless | With Universal Login (The email link sent using the custom domain if the option is enabled in Dashboard > Tenant Settings > Custom Domains.) |
SAML | Connections and applications |
WS-Federation | Auth0 as identity provider using WS-Fed add-on |
OAuth 2.0/OIDC-Compliant flows | Using the /authorize and /oauth/token endpoints |
Features not in the list are not supported by Auth0 with custom domains.
Certificate management options
Auth0-managed certificates
With the Auth0-managed certificate approach, Auth0 obtains the certificates for your domain and then manages the SSL handshake directly with the client.
Self-managed certificates
With the self-managed certificate approach, you are completely responsible for handling the SSL certificates and setting up and managing a reverse proxy for content to be sent to Auth0. Auth0 does not negotiate SSL with the end user’s client, but with the proxy. The proxy in turn negotiates SSL with the end user. To prevent someone from trying to use your Auth0 account from a domain you don’t own, Auth0 needs to validate that the domain belongs to you. Therefore, you need to send Auth0 a header (cname-api-key
) to validate. You must be an Enterprise customer to use this option.