feat: extend mTLS bearer transport (SendCertificateOverMtls) to OBO, refresh_token, and auth_code flows

[Robbie-Microsoft]

Summary

When SendCertificateOverMtls=true, MSAL previously only applied mTLS bearer transport for AcquireTokenForClient. User flows (OBO, refresh_token, auth_code) continued to use the regular login.microsoftonline.com endpoint with a client_assertion JWT in the POST body.

This PR extends mTLS bearer transport to all three user flows so they behave consistently with client_credentials when mTLS transport is configured.

Root Cause

TryInitMtlsPopParametersAsync (which sets MtlsCertificate on the request parameters, triggering mTLS endpoint routing) was only called in ConfidentialClientExecutor.ExecuteAsync for AcquireTokenForClientParameters. The OBO, auth_code, and RT executor paths skipped it entirely.

Changes

Production

File	Change
ConfidentialClientExecutor.cs	Add TryInitMtlsPopParametersAsync to OBO and auth_code executor paths
ClientApplicationBaseExecutor.cs	Add TryInitMtlsPopParametersAsync to the refresh_token (IByRefreshToken) and AcquireTokenSilent paths
RegionAndMtlsDiscoveryProvider.cs	Attempt region discovery for mTLS user flows when WithAzureRegion is configured, so regional endpoints (e.g. eastus.mtlsauth.microsoft.com) are used
TokenCache.ITokenCacheInternal.cs	Use OriginalAuthority for cache alias resolution so mTLS-transformed (mtlsauth.*) endpoints do not crash on second call
MtlsPopParametersInitializer.cs	Case 2 (IClientSignedAssertionProvider.GetAssertionAsync) is not guarded by SendCertificateOverMtls — it is a separate opt-in where the delegate signals mTLS intent by returning a non-null TokenBindingCertificate. This is independent of Case 1 (SendCertificateOverMtls + cert-based credential).
CredentialMaterialResolver.cs	Mode=Mtls only when IsMtlsPopRequested (explicit PoP); Mode=OAuth for all bearer transport cases so client_assertion is included in the body for every flow. Also auto-enables SendX5C=true when SendCertificateOverMtls=true — required for SNI-registered apps to validate the assertion JWT via the x5c chain.
AcquireTokenParameterBuilderExtensions.cs, AcquireTokenCommonParameters.cs, TokenClient.cs, AuthenticationRequestParameters.cs, PublicAPI.Unshipped.txt (×6)	Restored WithCachePartitionKey, WithReservedScopes, and SendOfflineAccessScope lost during a prior merge conflict resolution (from PR #6014 / 022dcde32)

Tests

File	Description
MtlsBearerUserFlowTests.cs (new)	Unit tests: OBO global mTLS, RT global mTLS, regional mTLS routing (full OBO post-data assertions including grant_type and requested_token_use), regression for non-mTLS cert credential, regression for second-call cache crash
MtlsTransportUserFlowTests.cs (new)	Integration tests: OboFlow/RefreshTokenFlow/AuthCodeFlow/ClientCredentials_WithSendCertificateOverMtls_BothMtlsConditionsMet, OboFlow_WithoutSendCertificateOverMtls_UsesRegularEndpointAsync. OboFlow/RefreshTokenFlow_WithSendCertificateOverMtls_AcquiresTokenAsync are [Ignore]'d pending lab config (see Testing section).

Docs

File	Description
docs/mtls-bearer-transport.md (new)	User-facing guide: opt-in API, IMsalMtlsHttpClientFactory implementation example, supported flows, how to verify, AAD allowlisting requirement

Design: Preview Behavior

For this preview drop, all flows send client_assertion in the POST body and present the cert at the TLS layer when SendCertificateOverMtls=true. This matches what ESTS supports today across all grant types.

Flow	Endpoint	client_assertion in body
AcquireTokenForClient (S2S)	mtlsauth.microsoft.com	Yes
OBO	mtlsauth.microsoft.com	Yes
refresh_token	mtlsauth.microsoft.com	Yes
auth_code	mtlsauth.microsoft.com	Yes

"Cert-only" (no client_assertion) is a future ESTS change, deferred post-preview.

Bug Fixes (found during review)

Bug 1 - Cache crash on second mTLS call:
TokenCache.ITokenCacheInternal.cs used requestParams.AuthorityInfo (a live property that returns the mTLS-transformed mtlsauth.* host after ResolveAuthorityAsync) for cache alias resolution. RegionAndMtlsDiscoveryProvider throws MtlsPopNotSupportedForEnvironment for non-login.* hosts. First call was safe (empty cache, early return); second call had cached entries and crashed. Fixed by using requestParams.AuthorityManager.OriginalAuthority.AuthorityInfo.

Bug 2 - AcquireTokenSilent not routing to mTLS endpoint:
ClientApplicationBaseExecutor.ExecuteAsync(AcquireTokenSilentParameters) never called TryInitMtlsPopParametersAsync, so silent refresh-token redemptions always hit login.microsoftonline.com even when SendCertificateOverMtls=true.

Bug 3 - SNI regression: missing x5c in client_assertion:
Changing CredentialMaterialResolver.cs to Mode=OAuth for all non-PoP requests caused CertificateAndClaimsClientCredential to start sending a client_assertion JWT where previously none was sent. For SNI-registered apps, AAD requires the x5c chain in the JWT header to validate the assertion. Without x5c, AADSTS700027 is returned. Fixed by auto-enabling SendX5C=true when SendCertificateOverMtls=true.

Bug 4 - TokenBindingCertificate unit tests broken by overly-broad guard:
An earlier review comment suggested guarding Case 2 in MtlsPopParametersInitializer with SendCertificateOverMtls == true. This broke BearerClientAssertion_WithPoPDelegate_Works and 3 related tests because Case 2 is a separate opt-in mechanism that must fire regardless of SendCertificateOverMtls. The guard was removed.

Testing

Unit Tests (net8.0): 2,063 passed, 0 failed

Integration Tests:

• Sni_Over_Mtls_Gets_Bearer_Token_Successfully_TestAsync — passes (pre-existing test, fixed by Bug 3 fix above)
• ClientCredentials_WithSendCertificateOverMtls_BothMtlsConditionsMet — passes (MSI-allowlisted app, 163ffef9)
• OboFlow_WithSendCertificateOverMtls_BothMtlsConditionsMet — passes (recording factory)
• RefreshTokenFlow_WithSendCertificateOverMtls_BothMtlsConditionsMet — passes (recording factory)
• AuthCodeFlow_WithSendCertificateOverMtls_BothMtlsConditionsMetAsync — passes (fake auth code, recording factory)
• OboFlow_WithoutSendCertificateOverMtls_UsesRegularEndpointAsync — passes
• OboFlow_WithSendCertificateOverMtls_AcquiresTokenAsync — [Ignore] pending lab config: AppWebApi (23c64cd8) mTLS not yet enabled in ID4SLAB1 (AADSTS700027). Remove [Ignore] once Bogdan/Qi enable mTLS client auth.
• RefreshTokenFlow_WithSendCertificateOverMtls_AcquiresTokenAsync — [Ignore] pending lab config: AppS2S mTLS endpoint not yet configured for this scenario (AADSTS392189). Remove [Ignore] once Bogdan/Qi enable mTLS client auth.

Existing MtlsPopTests suite: 69/69 pass.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Extends mTLS bearer transport behavior (SendCertificateOverMtls) beyond client_credentials to OBO, refresh_token, and auth_code flows, ensuring mTLS endpoint routing and suppressing client_assertion where appropriate.

Changes:

• Initialize mTLS/PoP parameters for auth_code, OBO, and refresh_token executor paths.
• Enable region discovery for mTLS-enabled user flows when AzureRegion is configured (regional mtlsauth endpoints).
• Prevent mTLS-transformed authorities from leaking into token cache alias resolution by using OriginalAuthority.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/Microsoft.Identity.Test.Unit/PublicApiTests/MtlsBearerUserFlowTests.cs	Adds unit coverage validating mtlsauth routing + client_assertion suppression for OBO/RT, plus a non-mTLS regression case
tests/Microsoft.Identity.Test.Integration.netcore/HeadlessTests/MtlsTransportUserFlowTests.cs	Adds/updates integration coverage for mTLS transport factory usage and asserts endpoint/body conditions for OBO/RT/client_credentials
src/client/Microsoft.Identity.Client/TokenCache.ITokenCacheInternal.cs	Uses OriginalAuthority for alias resolution to avoid mtlsauth host affecting cache lookups
src/client/Microsoft.Identity.Client/Instance/Discovery/RegionAndMtlsDiscoveryProvider.cs	Attempts region discovery for mTLS user flows when AzureRegion is configured
src/client/Microsoft.Identity.Client/ApiConfig/Executors/ConfidentialClientExecutor.cs	Calls TryInitMtlsPopParametersAsync for auth_code and OBO paths
src/client/Microsoft.Identity.Client/ApiConfig/Executors/ClientApplicationBaseExecutor.cs	Calls TryInitMtlsPopParametersAsync for refresh_token path

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

src/client/Microsoft.Identity.Client/PublicApi/net8.0/PublicAPI.Unshipped.txt:6

• This PR also removes the unshipped public APIs AcquireTokenParameterBuilderExtensions.WithCachePartitionKey(...) and .WithReservedScopes(...), which is a significant surface-area change not mentioned in the PR description (the description focuses on extending mTLS bearer transport). Please either document this removal in the PR description (with rationale) or split it into a separate PR to keep the change set focused.

Microsoft.Identity.Client.AuthScheme.IAuthenticationOperation3
Microsoft.Identity.Client.AuthScheme.IAuthenticationOperation3.AfterCredentialEvaluationAsync(Microsoft.Identity.Client.AuthScheme.CredentialEvaluationContext context, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task
Microsoft.Identity.Client.AuthScheme.CredentialEvaluationContext
Microsoft.Identity.Client.AuthScheme.CredentialEvaluationContext.CredentialEvaluationContext(System.Security.Cryptography.X509Certificates.X509Certificate2 mtlsCertificate) -> void
Microsoft.Identity.Client.AuthScheme.CredentialEvaluationContext.MtlsCertificate.get -> System.Security.Cryptography.X509Certificates.X509Certificate2

[Copilot]

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (3)

tests/Microsoft.Identity.Test.Unit/PublicApiTests/MtlsBearerUserFlowTests.cs:135

• Same issue as above: client_assertion is compared for exact equality by MockHttpMessageHandler. Asserting it equals "placeholder" is brittle/incorrect because MSAL will send a dynamically generated JWT.

                        ExpectedPostData = new Dictionary<string, string>
                        {
                            { OAuth2Parameter.ClientAssertionType, OAuth2AssertionType.JwtBearer },
                            { OAuth2Parameter.ClientAssertion, "placeholder" }
                        }

tests/Microsoft.Identity.Test.Unit/PublicApiTests/MtlsBearerUserFlowTests.cs:194

• Same issue as above for refresh_token redemption: MockHttpMessageHandler will compare client_assertion exactly, so expecting "placeholder" will fail. Assert presence/non-empty instead of an exact value.

                        ExpectedPostData = new Dictionary<string, string>
                        {
                            { OAuth2Parameter.ClientId, TestConstants.ClientId },
                            { OAuth2Parameter.GrantType, OAuth2GrantType.RefreshToken },
                            { OAuth2Parameter.RefreshToken, fakeRefreshToken },
                            { OAuth2Parameter.ClientAssertionType, OAuth2AssertionType.JwtBearer },
                            { OAuth2Parameter.ClientAssertion, "placeholder" }
                        },

tests/Microsoft.Identity.Test.Integration.netcore/HeadlessTests/MtlsTransportUserFlowTests.cs:168

• This comment states "No client_assertion is sent in the body", which contradicts the test intent/other assertions in this file (mTLS transport preview still includes client_assertion in the body). Update the comment to avoid misleading future maintainers.

            // Build CCA with SendCertificateOverMtls=true: the cert authenticates at the TLS layer
            // and the factory provides the mTLS connection. No client_assertion is sent in the body.
            // NOTE: WithHttpClientFactory must come AFTER WithTestLogging to override the sniffer factory.
            var cca = ConfidentialClientApplicationBuilder

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.