> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn how to configure a custom domain for Auth0 authentication features.

# Configure Features to Use Custom Domains

export const AuthCodeBlock = ({filename, icon, language, highlight, children}) => {
  const [displayText, setDisplayText] = useState(children);
  const [copyText, setCopyText] = useState(children);
  const wrapperRef = React.useRef(null);
  useEffect(() => {
    let unsubscribe = null;
    function init() {
      if (!window.autorun || !window.rootStore) {
        return;
      }
      unsubscribe = window.autorun(() => {
        let processedChildrenForDisplay = children;
        let processedChildrenForCopy = children;
        for (const [key, value] of window.rootStore.variableStore.values.entries()) {
          const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
          let displayValue = value;
          if (key === "{yourClientSecret}" && value !== "{yourClientSecret}") {
            displayValue = value.substring(0, 3) + "*****MASKED*****";
          }
          processedChildrenForDisplay = processedChildrenForDisplay.replaceAll(new RegExp(escapedKey, "g"), displayValue);
          processedChildrenForCopy = processedChildrenForCopy.replaceAll(new RegExp(escapedKey, "g"), value);
        }
        setDisplayText(processedChildrenForDisplay);
        setCopyText(processedChildrenForCopy);
      });
    }
    if (window.rootStore) {
      init();
    } else {
      window.addEventListener("adu:storeReady", init);
    }
    return () => {
      window.removeEventListener("adu:storeReady", init);
      unsubscribe?.();
    };
  }, [children]);
  useEffect(() => {
    if (!wrapperRef.current) return;
    const originalWriteText = navigator.clipboard.writeText.bind(navigator.clipboard);
    let isOverriding = false;
    const handleClick = e => {
      const button = e.target.closest('[data-testid="copy-code-button"]');
      if (!button || !wrapperRef.current.contains(button)) return;
      isOverriding = true;
      navigator.clipboard.writeText = text => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
          return originalWriteText(copyText);
        }
        return originalWriteText(text);
      };
      setTimeout(() => {
        if (isOverriding) {
          isOverriding = false;
          navigator.clipboard.writeText = originalWriteText;
        }
      }, 100);
    };
    const wrapper = wrapperRef.current;
    wrapper.addEventListener('click', handleClick, true);
    return () => {
      wrapper.removeEventListener('click', handleClick, true);
      if (navigator.clipboard.writeText !== originalWriteText) {
        navigator.clipboard.writeText = originalWriteText;
      }
    };
  }, [copyText]);
  return <div ref={wrapperRef}>
      <CodeBlock filename={filename} icon={icon} language={language} lines highlight={highlight}>
        {displayText}
      </CodeBlock>
    </div>;
};

To configure Auth0 features to use your <Tooltip tip="Custom Domain: Third-party domain with a specialized, or vanity, name." cta="View Glossary" href="/docs/glossary?term=custom+domain">custom domain</Tooltip>, you may need to complete additional steps depending on the features you are using. For example, you may need to make changes before you can use your custom domain on your login page or to call your APIs.

If you have been using Auth0 for some time and decide to enable a custom domain, you will have to migrate your existing apps and update the settings as described below, including to any VPN or firewall you use. Note that existing sessions created at `{yourDomain}` will no longer be valid once you start using your custom domain, so users will have to log in again.

## Prerequisites

You should have already configured and verified your custom domain.

## Features

| Feature                                                                             | Section to read                                                                                 |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [Universal Login](/docs/glossary?term=Universal+Login) with a customized login page | [Universal Login](#universal-login)                                                             |
| Lock embedded in your application                                                   | [Embedded Lock](#embedded-lock)                                                                 |
| Auth0 SPA SDK, Auth0.js, or other Auth0 SDKs                                        | [Auth0 SPA SDK, Auth0.js, and other SDKs](#auth0-spa-sdk-auth0-js-and-other-sdks)               |
| Custom domain with Auth0 emails and phone notifications                             | [Use custom domains in emails and phone notifications](#use-custom-domains-in-emails-and-phone) |
| Social identity providers                                                           | [Configure social identity providers](#configure-social-identity-providers)                     |
| Google Workspace connections with your custom domain                                | [Configure Google Workspace connections](#configure-g-suite-connections)                        |
| Issue Access Tokens for your APIs or access Auth0 APIs from your application        | [APIs](#apis)                                                                                   |
| [SAML](/docs/glossary?term=SAML) Identity Providers                                 | [Configure SAML identity providers](#configure-saml-identity-providers)                         |
| SAML applications                                                                   | [Configure SAML applications](#configure-saml-applications)                                     |
| Web Service Federation (WS-Fed) applications                                        | [Configure WS-Fed applications](#configure-ws-fed-applications)                                 |
| Azure AD connections                                                                | [Configure Azure AD connections](#configure-azure-ad-connections)                               |
| ADFS connections                                                                    | [Configure ADFS connections](#configure-adfs-connections)                                       |
| AD/LAP connections with Kerberos support                                            | [Configure AD/LAP connections](#configure-ad-ldap-connections)                                  |

## Universal Login

If you use [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login) and you have customized the login page, you must update the code to use your custom domain. If you use the **default** login page without customization, you do not need to make any changes. To learn more, read Auth0 <Tooltip tip="Universal Login: Your application redirects to Universal Login, hosted on Auth0's Authorization Server, to verify a user's identity." cta="View Glossary" href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>.

If you use [Lock for Web](/docs/libraries/lock), you must set the `configurationBaseUrl` and `overrides` options as seen in the following sample script:

```javascript lines theme={null}
var lock = new Auth0Lock(config.clientID, config.auth0Domain, {
  //code omitted for brevity
  configurationBaseUrl: config.clientConfigurationBaseUrl,
  overrides: {
  	__tenant: config.auth0Tenant,
  	__token_issuer: config.authorizationServer.issuer
  },
  //code omitted for brevity
});
```

If you use [Auth0.js](/docs/libraries/auth0js) on the Universal Login page, you must set the `overrides` option.

```javascript lines theme={null}
var webAuth = new auth0.WebAuth({
  clientID: config.clientID,
  domain: config.auth0Domain,
  //code omitted for brevity
  overrides: {
  	__tenant: config.auth0Tenant,
  	__token_issuer: config.authorizationServer.issuer
  },
  //code omitted for brevity
});
```

For most, the Auth0.js and Lock libraries retrieve the tenant name (required for `/usernamepassword/login`) and the issuer (required for `id_token` validation) from the domain. However, if you're a Private Cloud customer who uses a proxy or a custom domain name where the domain name is different from the tenant/issuer, you can use `__tenant` and `__token_issuer` to provide your unique values.

## Embedded Lock

If you use [Lock for Web](/docs/libraries/lock) embedded in your application, you must update the code to use your custom domain when initializing Lock. You will also need to set the `configurationBaseUrl` to the appropriate CDN URL.

export const codeExample1 = `var lock = new Auth0Lock('{yourClientId}', '{yourCustomDomain}', {
  //code omitted for brevity
  configurationBaseUrl: 'https://cdn.us.auth0.com'
  //code omitted for brevity
});`;

<AuthCodeBlock children={codeExample1} language="javascript" />

The CDN URL varies by region. Use `https://cdn.[us|eu|au|jp].auth0.com` (`us` for US, `eu` for Europe, `au` for Australia, or `jp` for Japan).

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The CDN URL varies by region. Tenants created before 11 June 2020 should use `https://cdn.auth0.com` if the region is the United States, or add `eu`, `au`, `jp` for Europe, Australia, or Japan. If your tenant was created after 11 June 2020, use `https://cdn.us.auth0.com` if the region is the United States.
</Callout>

## Auth0 SPA SDK, Auth0.js, and other SDKs

If you use the [Auth0 SPA SDK](/docs/libraries/auth0-single-page-app-sdk), [Auth0.js](/docs/libraries/auth0js), or [other SDKs](/docs/troubleshoot/customer-support/product-support-matrix#auth0-sdks), you will have to initialize the SDK using your custom domain. For example, if you are using the Auth0.js SDK, you must set the following:

export const codeExample2 = `webAuth = new auth0.WebAuth({
  domain: '{yourCustomDomain}',
  clientID: '{yourClientId}'
});`;

<AuthCodeBlock children={codeExample2} language="js" />

And for the Auth0 SPA SDK:

export const codeExample3 = `const auth0 = await createAuth0Client({
  domain: '{yourCustomDomain}',
  client_id: '{yourClientId}'
});`;

<AuthCodeBlock children={codeExample3} language="javascript" />

See APIs section below if you use a custom domain and also intend to perform [Management API actions with Auth0.js](/docs/libraries/auth0js#user-management).

## Use custom domains in emails and phone notifications

If you want to use your custom domain with your Auth0 emails or phone notifications, you must enable this feature.

1. Go to [Auth0 Dashboard > Branding > Custom Domains](https://manage.auth0.com/#/branding/custom_domains).
2. Enable the **Use Custom Domain in Emails** toggle.

## Configure Social identity providers

If you want to use your custom domain with Social <Tooltip tip="Identity Provider (IdP): Service that stores and manages digital identities." cta="View Glossary" href="/docs/glossary?term=identity+providers">identity providers</Tooltip> (IdP), you must update your IdP's list of Authorized Redirect URIs to include your custom domain (such as `https://login.northwind.com/login/callback`).

You cannot use [Auth0 developer keys](/docs/authenticate/identity-providers/social-identity-providers/devkeys) with custom domains.

## Configure Google Workspace connections

If you want to use your custom domain with Google Workspace connections, you must update the Authorized Redirect URI in your <Tooltip tip="OAuth 2.0: Authorization framework that defines authorization protocols and workflows." cta="View Glossary" href="/docs/glossary?term=OAuth">OAuth</Tooltip> Client Settings. In the Google Cloud Console, go to **Credentials**, choose your OAuth client in the list, and you will see a settings page with the app <Tooltip tip="Client ID: Identification value given to your registered resource from Auth0." cta="View Glossary" href="/docs/glossary?term=Client+ID">Client ID</Tooltip>, secret, and other fields. In the **Authorized redirect URIs** field, add a URL in the format `https://<YOUR-CUSTOM-DOMAIN>/login/callback` that includes your custom domain (such as `https://login.northwind.com/login/callback`).

## APIs

API identifiers (i.e. `audience`) will not change. This is a constant value for each API, and despite the fact that it's conventional to use a URI, it is completely independent of the domain used to obtain the token.

Auth0 issues tokens with the `iss` claim of whichever domain you used to obtain the token.

##### Auth0 APIs

Continue to use your default tenant domain name (such as `https://{yourDomain}/userinfo` and `https://{yourDomain}/api/v2/`) instead of your custom domain when specifying an `audience`. This is the only place to use your default tenant domain.

All requests (i.e. obtaining the token, and actually calling the API) must use the same domain. Tokens obtained via a custom domain must be used on an Auth0 API using the same custom domain.

If you use an authentication flow with your Custom Domain to request <Tooltip tip="Access Token: Authorization credential, in the form of an opaque string or JWT, used to access an API." cta="View Glossary" href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip> to access the <Tooltip tip="Management API: A product to allow customers to perform administrative tasks." cta="View Glossary" href="/docs/glossary?term=Management+API">Management API</Tooltip>, you must call the Management API endpoint with your Custom Domain too.

```json lines theme={null}
POST https://mycustomdomain.com/oauth/token
... // other parameters 
...
audience:https://defaulttenant.eu.auth0.com/api/v2/
```

Your Access Token request should be something similar to

```json lines theme={null}
GET https://mycustomdomain.com/api/v2/clients

Headers:
Authorization: Bearer <access_token>
```

##### Custom APIs

If you use Auth0 with a custom domain to issue Access Tokens for your APIs, you must validate the <Tooltip tip="JSON Web Token (JWT): Standard ID Token format (and often Access Token format) used to represent claims securely between two parties." cta="View Glossary" href="/docs/glossary?term=JWT">JWT</Tooltip> issuer(s) against your custom domain. For example, if you use the [express-jwt](https://github.com/auth0/express-jwt) middleware, you must make the following change:

```js lines theme={null}
app.use(jwt({
  issuer: 'https://<YOUR-CUSTOM-DOMAIN>/',
  //code omitted for brevity
}));
```

## Configure SAML identity providers

To use your custom domain with <Tooltip tip="Security Assertion Markup Language (SAML): Standardized protocol allowing two parties to exchange authentication information without a password." cta="View Glossary" href="/docs/glossary?term=SAML">SAML</Tooltip> Identity Providers (IdPs), you must update your **Assertion Consumer Service (ACS) URL(s)** with the Identity Provider(s). Depending on what is supported by the IdP, you can do this in one of two ways:

1. You can get the service provider metadata from Auth0 at `https://<YOUR-CUSTOM-DOMAIN>/samlp/metadata?connection=<YOUR-CONNECTION-NAME>`. This will include the updated ACS URL. Then, you must manually update this value in your IdP(s) settings. This change to your IdP(s) must happen at the same time as you begin using your custom domain in your applications. This can pose a problem if there are multiple IdPs to configure.
2. If supported by the IdP, you can use signed requests to fulfill this requirement:

* Download the signing certificate from `https://<TENANT>.auth0.com/pem`. Note that `https://<YOUR-CUSTOM-DOMAIN>.com/pem` will return the same certificate
* Give the certificate to the IdP(s) to upload. This enables the IdP to validate the signature on the `AuthnRequest` message that Auth0 sends to the IdP
* The IdP will import the certificate and, if necessary, signature verification should be enabled (exact steps vary by IdP)
* Turn on the **Sign Request** toggle in the Dashboard under **Connections > Enterprise > SAML > CONNECTION**. This will trigger Auth0 to sign the SAML `AuthnRequest` messages it sends to the IdP.

Once this is done, and you start using your custom domain when you initiate an authentication request in your application, the IdP will receive that custom domain in your signed request. Because your application’s signed request is trusted, the IdP should automatically override whatever was configured as your ACS URL and replace it with the value sent in the signed request. However, there are IdPs that do **not** accept the ACS URL in the signed request, so you must check with yours first to confirm whether this is supported or not.

If this is supported, it will prevent you from having to change one or many IdP settings all at the same time and allow you to prepare them to accept your signed requests ahead of time. You can then change the statically configured ACS URL in your IdP settings at a later date as well.

Note that if your SAML identity provider is configured to use your custom domain, testing the connection via the **Try** button in the Dashboard will **not** work and the default links for downloading metadata from Auth0 will always show the default domain, not the custom domain.

If you have an IdP-initiated authentication flow, you will need to update the IdP(s) and your application(s) at the same time to use the custom domain.

## Configure SAML applications

If you want to use your custom domain with SAML applications (when Auth0 is the IdP), you must update your service provider with new identity provider metadata from Auth0. You can obtain the updated metadata reflecting the custom domain from `https://<YOUR-CUSTOM-DOMAIN>/samlp/metadata/<YOUR-CLIENT-ID>`. Note that the issuer entity ID for the assertion returned by Auth0 will change when using a custom domain (from something like `urn:northwind.auth0.com` to one with the custom domain, such as `urn:login.northwind.com`).

If you have an IdP-initiated authentication flow, you will need to update the URL used to invoke the IdP-initiated authentication flow to reflect the custom domain. Instead of `https://<TENANT>.auth0.com/samlp/<YOUR-CLIENT-ID>`, you should use `https://<YOUR-CUSTOM-DOMAIN>/samlp/<YOUR-CLIENT-ID>`.

## Configure WS-Fed applications

If you want to use your custom domain with <Tooltip tip="Web Service Federation (WS-Fed): Protocol for managing user identities across domains." cta="View Glossary" href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> applications with Auth0 as the IdP, you must update your Service Provider with new identity provider metadata from Auth0. You can obtain the metadata reflecting the custom domain from `https://<YOUR-CUSTOM-DOMAIN>/wsfed/FederationMetadata/2007-06/FederationMetadata.xml`.

## Configure Azure AD connections

If you want to use your custom domain with Azure AD connections, you must update the Allowed Reply URL in your Azure AD settings. In your Azure Active Directory, go to **Apps registrations** and select your app. Then click **Settings -> Reply URLs** and add a URL with your custom domain in the format `https://<YOUR-CUSTOM-DOMAIN>/login/callback` (such as `https://login.northwind.com/login/callback`).

## Configure ADFS connections

If you want to use your custom domain with ADFS connections, you must update the endpoint in your ADFS settings. This will need to be updated to use your custom domain in the callback URL in the format `https://<YOUR-CUSTOM-DOMAIN>/login/callback` (such as `https://login.northwind.com/login/callback`).

## Configure AD/LDAP connections

If you do not need Kerberos support, AD/LDAP connections do not require further configuration.

In order to use AD/LDAP connections with Kerberos support, you will need to update the Ticket endpoint to work with the custom domain. As mentioned in the [Auth0 AD/LDAP connector documentation](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-to-auth0#point-an-ad-ldap-connector-to-a-new-connection), the `config.json` file needs to be modified, with the `PROVISIONING_TICKET` value changed to use your custom domain in the format `https://<YOUR-CUSTOM-DOMAIN>/p/ad/jUG0dN0R`.

Once this change is saved, you need to restart the AD/LDAP Connector service for the change to take effect.

## Learn more

* [Configure Custom Domains with Auth0-Managed Certificates](/docs/customize/custom-domains/auth0-managed-certificates)
* [Configure Custom Domains with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates)