Configure mTLS for a Tenant

Configure mTLS with Management API

Use the Auth0 Management API to configure mTLS for a tenant:

Create a custom domain

At the tenant level, you must configure a custom domain to accept mTLS headers. Because the customer edge is responsible for validating the client certificates, set the type as self_managed_certs in the POST request:

curl --location --request POST 'https://$tenant/api/v2/custom-domains' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "domain":"string",
  "type":"self_managed_certs",
  "verification_method":"txt", 
  "tls_policy":"recommended",
  "custom_client_ip_header":"true-client-ip"
}'

Was this helpful?

/

A successful request returns an identifier that is used to verify the custom domain. For more information, see the Configure a new custom domain API documentation.

Patch an existing custom domain

You can configure an existing custom domain to accept mTLS headers. However, you cannot update the type for an already existing custom domain.

The following POST request that configures an existing custom domain to accept mTLS headers:

curl --location --request POST 'https://$tenant/api/v2/custom-domains/:id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "tls_policy":"recommended",
  "custom_client_ip_header":"true-client-ip"
}'

Was this helpful?

/

For more information, see the Update custom domain configuration API documentation.

Verify the custom domain

Before Auth0 accepts requests to create and update the custom domain, it must first verify the domain. The following POST request verifies the custom domain:

curl --location --request POST 'https://$tenant/api/v2/custom-domains/:id/verify'

Was this helpful?

/

Check the status field to see its verification status. Once verification is complete, it may take up to 10 minutes before the custom domain can start accepting requests.

When Auth0 verifies the custom domain for the first time, the response includes the cname_api_key, which you need to configure your edge/reverse proxy. This key must be kept secret and is used to validate the forwarded requests.

For more information, see the Verify a custom domain API documentation.

Enable mTLS endpoint aliases

When the mTLS handshake requests a client certificate from the client, the web browser presents users with a modal dialog to select a certificate. This introduces friction in the user experience and should be avoided for endpoints where mTLS is unnecessary such as the /authorize endpoint. As a result, customers that support mTLS and non-mTLS traffic on different domains should enable mTLS endpoint aliases.

mTLS endpoint aliases indicate that clients should send mTLS traffic to the endpoints specified in the mtls_endpoint_aliases property of the OIDC discovery document. Clients will send non-mTLS traffic to the normal endpoints. For more information about the mtls_endpoint_aliases property, see Call the resource server.

Management API

To enable mTLS endpoint aliases using the Management API, set the enable_endpoint_aliases property to true for your tenant:

curl --location --request PATCH 'https://$tenant/api/v2/tenants/settings' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "mtls": {
    "enable_endpoint_aliases": true
  }
}'

Was this helpful?

/

mTLS endpoint aliases add the mtls. prefix to the configured custom domain. For example, if the configured custom domain is auth.saasapp.com, the mTLS endpoint aliases will use the domain mtls.auth.saasapp.com. Depending on feedback, customers may be able to configure the mTLS endpoint aliases in the future.

To disable mTLS endpoint aliases, set the enable_endpoint_aliases value to false. For more information, see the Update tenant settings API documentation.

Auth0 Dashboard

To enable mTLS endpoint aliases using the Auth0 Dashboard:

  1. Navigate to Auth0 Dashboard and select Settings from the side menu.

  2. Under Tenant Settings, select the Advanced tab.

  3. Find Allow mTLS Endpoint Aliases and toggle it on. This will route mTLS traffic to an endpoint called mtls.<your custom domain>.

Auth0 Dashboard > Settings > Advanced > Allow mTLS endpoint aliases

Learn more