Skip to content

feat: Adds mTLS support - #279

Merged
kailash-b merged 8 commits into
mainfrom
feat/SDK-6831
Aug 19, 2026
Merged

kailash-b merged 8 commits into
mainfrom
feat/SDK-6831

Conversation

@kailash-b

Copy link
Copy Markdown
Contributor

Description

This PR adds support for Mutual TLS (mTLS) to the SDK, following RFC 8705

With mTLS, an application authenticates to Auth0 using a client certificate instead of a client secret or client assertion. Access tokens can additionally be certificate-bound (sender-constrained), so a token that is stolen cannot be replayed without the corresponding private key. This is aimed at highly-regulated scenarios where holder-of-key assurance is required.

Enabling the feature is a single, opt-in call:

builder.Services
    .AddAuth0WebAppAuthentication(options => { /* Domain, ClientId */ })
    .WithMtls(options => { options.HttpClient = mtlsHttpClient; })
    .WithAccessToken(options => { /* Audience, etc. */ });
  • The application owns the certificate. User supplies an HttpClient that presents the client certificate. The SDK never reads, stores, or rotates it. This keeps certificate management like loading, storage and rotation in the hands of the user and out of the SDK.
  • The certificate becomes the sole credential. When mTLS is enabled, all client-authenticated back-channel calls, the code exchange, token refresh, MRRT and Token Vault exchanges, session transfer, MFA challenge, and Pushed Authorization Requests are routed through the tenant's mTLS endpoint aliases and present the certificate rather than a secret. Bearer-token endpoints continue to use the standard host.
  • Fail-fast configuration. Combining mTLS with a client secret, client assertion, or a custom backchannel throws at startup. The SDK validates the required ordering of the builder calls, so misconfiguration surfaces immediately rather than at runtime.
  • Certificate-binding awareness. When a token that should be certificate-bound is not, the SDK emits a one-time warning per client rather than failing silently.

This is a purely additive, opt-in feature. Applications that do not call .WithMtls() are unaffected.

References

Testing

  • The PR adds unit and integration test coverage for the new functionality, including endpoint-alias resolution, certificate-bound token inspection, the token/authentication clients, and the mTLS middleware and configuration behaviour. Existing tests continue to pass.

  • This change adds test coverage for new/changed/fixed functionality

Checklist

  • I have added documentation for new/changed functionality in this PR or in auth0.com/docs
  • All active GitHub checks for tests, formatting, and security are passing
  • The correct base branch is being used, if not main

@kailash-b
kailash-b requested a review from a team as a code owner August 12, 2026 17:19

@Piyush-85 Piyush-85 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work @kailash-b, LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants