Configure Custom Domains with Self-Managed Certificates

You must have an Enterprise subscription to manage certificates in your custom domain. To learn more, read Auth0 Pricing and Login.

If you choose to manage the certificates for your custom domains without assistance from Auth0, you need to know how to manage your own proxy and certificates for inbound connections that require multiple DNS records on the domain. You have to purchase or provide the certificates and manage the renewals yourself. You will also need a reverse proxy where the certificate will be installed. Once the domain is verified, we will accept traffic from the proxy.

Choose this option to:

• Have more control of your certificates (such as choosing your own CA or certificate expiration).
• Enable additional monitoring over your API calls to Auth0.

To set up your custom domain using self-managed certificates, you need to provide your domain name to Auth0, verify that you own that domain, and configure the reverse proxy. Once your custom domain has been set up, you will need to configure your Auth0 features to start using your custom domain.

Your proxy to Auth0 must use TLS (SSL) version 1.2 or newer.

Provide your domain name to Auth0

1. Go to Dashboard > Settings > Custom Domains or Dashboard > Branding > Custom Domains. Enter your custom domain in the provided box, and select Self-managed Certificates from the drop-down menu.
2. Choose Add Domain. You can only add one domain per tenant even though the Add Domain button still appears after you add a domain.

Verify ownership

Before you can use the domain with Auth0, you’ll need to verify that you own it.

1. Go to Dashboard > Branding > Custom Domains.

   

2. Add the TXT verification information to your domain’s DNS record. These steps may vary for your domain host provider:

   1. Keep the Auth0 custom domain page open in your browser so you can copy values.

   2. Log in to your domain management service.

   3. Create a new record, and save it with these settings:

      Parameter	Value
      Record type	TXT
      Name	Copy and paste your domain’s TXT Record value from Auth0.
      Time to Live (TTL)	Use default value.
      Value	Copy and paste your domain’s TXT Content value from Auth0.

3. Click Verify to proceed.

   It may take a few minutes before Auth0 can verify your domain, depending on your DNS settings.

   If Auth0 successfully verified your domain name, you’ll see a confirmation window. Save the information provided in this window, specifically the cname-api-key value, since this is the only time you’ll see this value.

   For security purposes, this value is hashed when stored, so it cannot be recovered. If you fail to capture the cname-api-key at this time, you will have to recreate the custom domains.

   The verification process is complete, and within 1 to 2 minutes, your custom domain should be ready to use. If you are unable to complete the verification process within three days, repeat these steps.

Configure reverse proxy

The reverse proxy server retrieves resources on behalf of your application from one or more servers. These resources are then returned to the application, appearing as if they originated from the proxy server itself.

You can use a service such as Cloudflare, Azure CDN, Google Cloud Platform, or AWS Cloudfront and configure settings for your custom domain. You will add the new CNAME value to your DNS for your custom domain pointing to the reverse proxy server domain name for distribution.

1. After you’ve created the reverse proxy settings on your service, go to Auth0 Dashboard > Branding > Custom Domains tab.
2. Add a new CNAME record to your DNS for your custom domain pointing to the service domain name for your distribution. You can find this by looking for the Distribution ID on your reverse proxy server configuration. Once added, the CNAME record must be present at all times to avoid issues during certificate renewal.
3. The way you configure the proxy server will vary depending on the service you use. You will likely need to configure the following types of settings:

• Distribution
• Origin custom headers
• Origin hostname
• Default cache behavior

Distribution settings

Setting	Value
Origin Domain Name	Set this to the Origin Domain Name value obtained from the Auth0 Dashboard during the Custom Domains setup process.
Origin ID	A description for the origin. This value lets you distinguish between multiple origins in the same distribution and therefore must be unique.
Origin Protocol Policy	Set to HTTPS Only.
Alternate Domain Names (CNAMEs)	Set to your custom domain name (the same one your configured in the Auth0 Dashboard).

Origin custom header settings

Setting	Value
Header Name	Set to cname-api-key.
Value	Set to the CNAME API Key value that you were given immediately after you verified ownership of your domain name with Auth0.

Origin hostname settings

Setting	Value
Origin hostname	Enter {yourTenant}-<CUSTOM_DOMAIN_ID>.edge.tenants.us.auth0.com, making sure to replace <CUSTOM_DOMAIN_ID> with the value of the Origin Domain Name (custom domain ID) you received from Auth0 when setting up the new custom domain. If your tenants are not in the US region, use one of the following: EU: {yourTenant}-<CUSTOM_DOMAIN_ID>.edge.tenants.eu.auth0.com AU: {yourTenant}-<CUSTOM_DOMAIN_ID>.edge.tenants.au.auth0.com JP: {yourTenant}-<CUSTOM_DOMAIN_ID>.edge.tenants.jp.auth0.com For example, if your CUSTOM_DOMAIN_ID is: cd_TXIdNgQ07HrAFVmz For a US tenant, then the Origin hostname should be: US: -cd-txIdngq07hrafvmz.edge.tenants.us.auth0.com
Host header	Use the name you provided for the Origin hostname.

For more information on retrieving the details of your custom domain, see Get custom domain configurations.

Default cache behavior settings

Setting	Value
Viewer Protocol Policy	Select Redirect HTTP to HTTPS.
Allowed HTTP Methods	Select GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
Cache Based on Selected Request Headers	Select Allow list.
Allow List Headers	The following headers should be allowed: User-Agent, Origin, Referer, Authorization, Accept, and Accept-Language.
Forward Cookies	Select All.
Query String Forwarding and Caching	Select Forward all, cache based on all.

Additional steps for specific Auth0 features

There are additional configuration steps you must complete depending on which Auth0 features you are using. To learn more, read Configure Features to Use Custom Domains.

Cloudflare uses a feature called CNAME Flattening, which affects Auth0 verification and certificate renewal in the way that it handles DNS records. We recommend that you turn off CNAME Flattening unless it’s absolutely necessary. To learn more, read Cloudflare documentation.

Because this feature puts you in control of your own certificates, you need to design mitigation strategies (like a web application firewall) for blocking requests in case of attacks. For more information, read our blog about the future of bot protection.

Learn more

• Configure Features to Use Custom Domains
• Configure Google Cloud Platform with Load Balancing as Reverse Proxy
• Configure Cloudflare as Reverse Proxy
• Configure AWS CloudFront as Reverse Proxy
• Configure Azure CDN as Reverse Proxy
• Configure Akamai as Reverse Proxy