feat: add mTLS (RFC 8705) client authentication

README.md

@@ -84,6 +84,29 @@ The key must be a PKCS8 PEM private key. Register its public key on your Auth0 a
 > [!IMPORTANT]
 > Private keys must not be committed to source control. Load them from a secure secret store or an environment-provided file.
 
+#### Authenticating with Mutual TLS (mTLS)
+
+The SDK supports mTLS client authentication (RFC 8705): the client presents a TLS certificate during the handshake instead of a client secret. Pass `use_mtls=True` and a caller-built `ssl.SSLContext` that already has the certificate loaded:
+
+```python
+import ssl
+
+ssl_context = ssl.create_default_context()
+ssl_context.load_cert_chain("client.crt", "client.key")
+
+auth0 = ServerClient(
+    domain="login.example.com",   # self_managed_certs custom domain
+    client_id="<AUTH0_CLIENT_ID>",
+    use_mtls=True,
+    ssl_context=ssl_context,
+    secret="<AUTH0_SECRET>",
+)
+```
+
+`use_mtls=True` requires an Enterprise tenant with the Highly Regulated Identity add-on, a `self_managed_certs` custom domain, and mTLS endpoint aliases enabled. It cannot be combined with `client_secret`, `client_assertion_signing_key`, or a per-call `dpop_key`. Each raises `ConfigurationError`. See the [Auth0 mTLS configuration docs](https://auth0.com/docs/get-started/applications/configure-mtls) for tenant-side setup steps.
+
+See [examples/MutualTLS.md](examples/MutualTLS.md) for the full setup guide, certificate generation, and token sender-constraining details.
+
 ### 3. Add login to your Application (interactive)
 
 Before using redirect-based login, ensure the `redirect_uri` is configured when initializing the SDK:

examples/MutualTLS.md

@@ -0,0 +1,86 @@
+# Mutual TLS (mTLS) Client Authentication
+
+Authenticate to Auth0 with a TLS client certificate instead of a client secret (RFC 8705). The certificate is presented during the TLS handshake. No credential travels in the request body.
+
+## Prerequisites
+
+- Auth0 **Enterprise** tenant with the **Highly Regulated Identity** add-on
+- A `self_managed_certs` **custom domain** configured on the tenant
+- **Allow mTLS Endpoint Aliases** enabled on the tenant (Dashboard → Settings → Advanced)
+- Client application's authentication method set to **mTLS** in Dashboard → Applications → Settings → Credentials
+
+## Generating a client certificate (development)
+
+```bash
+# Self-signed CA + client cert (development only - use your PKI in production)
+openssl req -x509 -newkey rsa:4096 -keyout ca.key -out ca.crt -days 365 -nodes \
+  -subj "/CN=dev-ca"
+openssl req -newkey rsa:2048 -keyout client.key -out client.csr -nodes \
+  -subj "/CN=my-app-client"
+openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
+  -out client.crt -days 365
+```
+
+## Wiring into `ServerClient`
+
+```python
+import ssl
+from auth0_server_python.auth_server.server_client import ServerClient
+
+ssl_context = ssl.create_default_context()          # trusts system/public CAs for the server side
+ssl_context.load_cert_chain("client.crt", "client.key")  # attaches the client identity
+
+auth0 = ServerClient(
+    domain="login.example.com",       # self_managed_certs custom domain
+    client_id="<AUTH0_CLIENT_ID>",
+    use_mtls=True,
+    ssl_context=ssl_context,
+    secret="<AUTH0_SECRET>",
+    authorization_params={
+        "audience": "<API_IDENTIFIER>",
+        "scope": "openid profile email offline_access",
+    },
+)
+```
+
+The SDK passes `ssl_context` as `verify=ssl_context` to every `httpx.AsyncClient` it constructs, including the authlib client used for the authorization-code exchange. You never call `load_cert_chain` inside the SDK - the caller owns the TLS material.
+
+## Mutual exclusion
+
+`use_mtls=True` cannot be combined with:
+
+| Parameter | Reason |
+|-----------|--------|
+| `client_secret` | One client-auth method only - Auth0 rejects requests carrying both. |
+| `client_assertion_signing_key` | Same - one method only. |
+| `dpop_key` (per-call on `signin_with_passkey` / `mfa.verify`) | DPoP binds to its own key (`cnf.jkt`) and suppresses `cnf.x5t#S256`. Combining them silently defeats mTLS token binding. |
+
+All three raise `ConfigurationError` immediately (constructor for the first two, at the call site for DPoP).
+
+## Token sender-constraining
+
+When the target API has **Token Sender-Constraining (mTLS)** enabled, issued access tokens carry a `cnf.x5t#S256` claim binding the token to the certificate thumbprint.
+
+The SDK logs a warning at the `auth0_server_python.auth_server.server_client` logger whenever an access token returned by the authorization-code or refresh-token flow does not contain `cnf.x5t#S256`. If you see that warning, enable **Token Sender-Constraining (mTLS)** on the API resource server in the Auth0 Dashboard.
+
+## MFA under mTLS
+
+The client certificate is presented on all MFA API calls. The token-endpoint call inside `mfa.verify` is routed through the mTLS alias automatically. Challenge and enrollment calls (`/mfa/challenge`, `/mfa/associate`) go to the standard host. The certificate is still included in the TLS handshake, but whether it reaches the Auth0 backend depends on the proxy configuration.
+
+```python
+await auth0.mfa.verify(
+    {"mfa_token": encrypted_token, "otp": "123456"},
+)
+```
+
+## Passkeys under mTLS
+
+The client certificate is presented on all passkey calls. The token-exchange step (`signin_with_passkey`) calls the token endpoint, which is served on the mTLS alias and routed correctly.
+
+Challenge and enrollment calls (`/passkey/challenge`, `/passkey/register`) go to the standard host - they are not listed in `mtls_endpoint_aliases`. The certificate is still included in the TLS handshake, but whether it reaches the Auth0 backend depends on the proxy configuration - the same behaviour as `/mfa/challenge`.
+
+## Passwordless under mTLS
+
+By default, Auth0 does not require client authentication on `/passwordless/start`. If the `enforce_client_authentication_on_passwordless_start` tenant flag is enabled on your tenant, the call will fail because `/passwordless/start` does not support certificate-based client authentication.
+
+The verify step (`passwordless_client.verify`) calls the token endpoint, which is served on the mTLS alias and routed correctly.

references/flow-map.md

@@ -17,6 +17,7 @@ Before working on a flow, read its entry points and supporting modules. Every fl
 | Passkeys | `passkey_signup_challenge`, `passkey_login_challenge`, `signin_with_passkey` | `auth_schemes/dpop_auth.py` — passkey sign-in is the DPoP-bound path | `examples/Passkeys.md` |
 | My Account | `MyAccountClient` (factors, authentication methods, enroll/verify) | `auth_schemes/dpop_auth.py`; stateless — every call takes a user token | `examples/MyAccountAuthenticationMethods.md` |
 | MCD | any flow — `domain` may be an async resolver | `_resolve_current_domain`, pitfall 5 in `references/pitfalls.md` | `examples/MultipleCustomDomains.md` |
+| mTLS client auth | constructor `use_mtls` + `ssl_context` | `_resolve_token_endpoint`, `_apply_client_authentication`, `_warn_if_not_cert_bound`, `mfa_client.py` (`use_mtls`, `ssl_context`, `verify`, `token_endpoint_resolver`) | `examples/MutualTLS.md` |
 
 Two rules cut across every flow above, so check them on any change here: resolve the domain through
 `await self._resolve_current_domain(store_options)` rather than reading `self._domain`, and accept

src/auth0_server_python/auth_server/mfa_client.py

@@ -4,6 +4,7 @@
 """
 
 import json
+import ssl
 import time
 from collections.abc import Awaitable, Callable
 from typing import TYPE_CHECKING, Any, Optional, Union
@@ -74,6 +75,9 @@ def __init__(
         ] = None,
         mfa_token_ttl: int = DEFAULT_MFA_TOKEN_TTL,
         apply_client_authentication: Optional[Callable] = None,
+        use_mtls: bool = False,
+        ssl_context: Optional[ssl.SSLContext] = None,
+        token_endpoint_resolver: Optional[Callable[..., Awaitable[str]]] = None,
     ):
         if callable(domain):
             self._domain = None
@@ -92,10 +96,15 @@ def __init__(
             raise ConfigurationError("mfa_token_ttl must be a positive number of seconds")
         self._mfa_token_ttl = mfa_token_ttl
         self._apply_client_authentication = apply_client_authentication
+        self._use_mtls = use_mtls
+        self._ssl_context = ssl_context
+        self._token_endpoint_resolver = token_endpoint_resolver
 
     def _get_http_client(self, **kwargs) -> httpx.AsyncClient:
         """Return an httpx.AsyncClient with default headers injected."""
         headers = {**kwargs.pop("headers", {}), **self._headers}
+        if self._use_mtls and "verify" not in kwargs:
+            kwargs["verify"] = self._ssl_context
         return httpx.AsyncClient(headers=headers, **kwargs)
 
     def _apply_mfa_client_authentication(self, body: dict, base_url: str) -> None:
@@ -502,8 +511,16 @@ async def verify(
             MfaVerifyError: When verification fails, or when dpop_key was supplied
                 but the server returned an unbound (Bearer) token.
             MfaRequiredError: When chained MFA is required.
+            ConfigurationError: If dpop_key is combined with use_mtls. DPoP and mTLS
+                use incompatible token-binding mechanisms and cannot be used together.
             ConfigurationError: If neither client_secret nor client_assertion_signing_key is configured.
         """
+        if self._use_mtls and dpop_key is not None:
+            raise ConfigurationError(
+                "dpop_key cannot be combined with use_mtls. DPoP and mTLS bind tokens "
+                "differently. DPoP would take precedence and the token would not be "
+                "certificate-bound."
+            )
         mfa_token = options.get("mfa_token")
         if not mfa_token:
             raise MfaTokenInvalidError()
@@ -534,7 +551,10 @@ async def verify(
             )
 
         try:
-            token_endpoint = f"{base_url}/oauth/token"
+            if self._use_mtls and self._token_endpoint_resolver:
+                token_endpoint = await self._token_endpoint_resolver(store_options)
+            else:
+                token_endpoint = f"{base_url}/oauth/token"
 
             async with self._get_http_client() as client:
                 headers = {"Content-Type": "application/x-www-form-urlencoded"}

src/auth0_server_python/auth_server/my_account_client.py

@@ -1,4 +1,5 @@
 import json
+import ssl
 from typing import TYPE_CHECKING, Optional
 from urllib.parse import quote, unquote, urlparse
 
@@ -46,20 +47,31 @@ class MyAccountClient:
     Client for interacting with the Auth0 MyAccount API.
     """
 
-    def __init__(self, domain: str, headers: Optional[dict[str, str]] = None):
+    def __init__(
+        self,
+        domain: str,
+        headers: Optional[dict[str, str]] = None,
+        ssl_context: Optional[ssl.SSLContext] = None,
+    ):
         """
         Initialize the MyAccount API client.
 
         Args:
             domain: Auth0 domain (e.g., '<tenant>.<locality>.auth0.com')
             headers: Optional default headers to include on every request
+            ssl_context: Optional SSL context for mTLS. When provided, the client
+                certificate is presented on every request so the My Account API can
+                verify cnf.x5t#S256 binding on cert-bound access tokens.
         """
         self._domain = domain
         self._headers = headers or {}
+        self._ssl_context = ssl_context
 
     def _get_http_client(self, **kwargs) -> httpx.AsyncClient:
         """Return an httpx.AsyncClient with default headers injected."""
         headers = {**kwargs.pop("headers", {}), **self._headers}
+        if self._ssl_context is not None and "verify" not in kwargs:
+            kwargs["verify"] = self._ssl_context
         return httpx.AsyncClient(headers=headers, **kwargs)
 
     @property

src/auth0_server_python/auth_server/passwordless_client.py

@@ -209,7 +209,12 @@ async def verify(
                 e,
             )
 
-        token_endpoint = metadata["token_endpoint"]
+        token_endpoint = client._resolve_token_endpoint(metadata)
+        if not token_endpoint:
+            raise PasswordlessVerifyError(
+                PasswordlessErrorCode.DISCOVERY_ERROR,
+                "Token endpoint missing in OIDC metadata",
+            )
         origin_issuer = metadata.get("issuer")
 
         default_scope = (
@@ -393,7 +398,7 @@ async def _verify_id_token(
         if not id_token:
             raise PasswordlessVerifyError(
                 PasswordlessErrorCode.VERIFY_FAILED,
-                "Token response did not include an ID token; ensure 'openid' scope is requested",
+                "Token response did not include an ID token. Ensure 'openid' scope is requested.",
             )
 
         jwks = await client._get_jwks_cached(origin_domain, metadata)