> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.
> Describes how to configure mTLS Authentication for a tenant.
# Configure mTLS Authentication for a Tenant
Learn how to configure mTLS authentication for a tenant.
The following examples specify **\$management\_access\_token**, or a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens). This must be replaced with an access token that contains at least the following scopes:
* `create:custom_domains`
* `read:custom_domains`
* `create:clients`
* `update:clients`
* `update:client_credentials`
* `update:client_keys`
* `update:tenant_settings`
To learn more about retrieving an access token with the required scopes, read [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens).
To begin, you must configure and verify a [custom domain](/docs/customize/custom-domains).
### Create a custom domain
At the tenant level, you must configure a [custom domain](/docs/customize/custom-domains) to accept mTLS headers with the [Management API](https://auth0.com/docs/api/management/v2). Because the [customer edge](/docs/get-started/applications/configure-mtls/set-up-the-customer-edge) is responsible for validating the client certificates, set the `type` as `self_managed_certs` in the POST request:
```bash lines theme={null}
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"
}'
```
A successful request returns an identifier that is used to verify the custom domain. For more information, see the [Configure a new custom domain](https://auth0.com/docs/api/management/v2/custom-domains/post-custom-domains) API documentation.
### Patch an existing custom domain
You can configure an existing custom domain to accept mTLS headers with the [Management API](https://auth0.com/docs/api/management/v2). However, you cannot update the `type` for an already existing custom domain.
Only custom domains with the `self_managed_certs` type can be used for mTLS. Auth0 currently does not support the `auth0_managed_certs` type for mTLS.
The following POST request configures an existing custom domain to accept mTLS headers:
```bash lines theme={null}
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"
}'
```
For more information, see the [Update custom domain configuration](https://auth0.com/docs/api/management/v2/custom-domains/patch-custom-domains-by-id) API documentation.
### Verify the custom domain
Before Auth0 accepts requests to create and update the custom domain, it must first verify the domain. Use the [Management API](https://auth0.com/docs/api/management/v2) to send the following POST request to verify the custom domain:
```bash wrap lines theme={null}
curl --location --request POST 'https://$tenant/api/v2/custom-domains/:id/verify'
```
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](https://auth0.com/docs/api/management/v2/custom-domains/patch-custom-domains-by-id) 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](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls#call-the-resource-server).
You can enable mTLS endpoint aliases with the Auth0 Dashboard and the Management API.
To enable mTLS endpoint aliases using the Auth0 Dashboard:
1. Navigate to [Auth0 Dashboard](https://manage.auth0.com/#/tenant/general) 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.`**.**
To enable mTLS endpoint aliases using the [Management API](https://auth0.com/docs/api/management/v2), set the `enable_endpoint_aliases` property to `true` for your tenant:
```bash lines theme={null}
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
}
}'
```
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.
The mTLS subdomain is outside of Auth0’s control. Administrators must be aware of the risks of subdomains and act accordingly. This includes, but is not limited to:
* Ensuring the ownership and ability to administer the top-level domain and subdomains used with mTLS. Failure to do so could result in the loss of both the login handler and the mTLS subdomain. This is especially important when using [custom domains](/docs/customize/custom-domains).
* Ensuring that you have a SSL certificate for the mTLS subdomain i.e. `mtls.auth.saasapp.com`. A wildcard certificate for `*.saasapp.com` does not include the mTLS subdomain.
Preventing subdomain takeovers due to dangling DNS entries if an IP is no longer in use. For more information, see the Mozilla Developer Network (MDN) [Subdomain takeovers](https://developer.mozilla.org/en-US/docs/Web/Security/Subdomain_takeovers) documentation.
To disable mTLS endpoint aliases, set the `enable_endpoint_aliases` value to `false`. For more information, see the [Update tenant settings](https://auth0.com/docs/api/management/v2/tenants/patch-settings) API documentation.
## Learn more
* [Authenticate with mTLS](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls)
* [Set up the Customer Edge](/docs/get-started/applications/configure-mtls/set-up-the-customer-edge)
* [Configure mTLS Authentication for a Client](/docs/get-started/applications/configure-mtls/configure-mtls-for-a-client)