Docs

Custom Domains

articles

Custom Domains

Feature availability

Auth0 custom domains are available with any paid subscription plan. If you want to manage the SSL/TLS certificates yourself, you will need an Enterprise subscription. For more information refer to Auth0 pricing plans.

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. See Universal Login to determine if your use case requires custom domains.

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/
https://login.northwind.com/authorize... 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).

Whitelisting

Be aware that Auth0 does not provide a static list of IP addresses because they are subject to change. We recommend that you whitelist your custom domain instead.

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 to custom-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 not in the list are not supported by Auth0 with custom domains.

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, G Suite, 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

Certificate management options

Auth0-managed certificates

With the Auth0-managed certificate approach, Auth0 uses Let’s Encrypt to get 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.

Keep reading