Add SNI certificate support over mTLS Proof-of-Possession

[Robbie-Microsoft]

Summary

Adds support for using an SN/I (Subject Name + Issuer) certificate as the client credential over mTLS Proof-of-Possession. A confidential client configured with an SN/I cert can obtain an mTLS-bound mtls_pop access token from Entra (ESTS), using that same certificate as the client TLS cert in the handshake to the token endpoint. The credential is identical to the existing SN/I + Bearer flow — only the mechanism changes (assertion-signer → TLS client cert). Wire behavior mirrors MSAL.NET.

The optional two-leg FIC exchange over mTLS PoP is a stacked follow-up: #939.

Usage

app = msal.ConfidentialClientApplication(
    client_id,
    authority="https://login.microsoftonline.com/<tenant-id>",   # must be tenanted
    client_credential={"private_key_pfx_path": "sni.pfx", "public_certificate": True},
    # azure_region="westus3",   # optional; omit for the global mtls endpoint
)
result = app.acquire_token_for_client(
    ["https://graph.microsoft.com/.default"], mtls_proof_of_possession=True)
# result["token_type"] == "mtls_pop"
# result["binding_certificate"] == {"x5c": [...], "thumbprint_sha256": "..."}  # public only

What changed

• msal/mtls.py (new) — mTLS transport: token-endpoint host transform, SSLContext from the cert material, requests-adapter injection, sovereign/known-host guardrails.
• msal/application.py — mtls_proof_of_possession kwarg on acquire_token_for_client; cert-material plumbing; _MtlsClient; binding_certificate in the result; fail-fast guards (tenanted authority, custom http_client, missing cert).
• msal/token_cache.py — mtls_pop tokens isolated by key_id (x5t#S256); Bearer keys stay byte-for-byte unchanged and a Bearer lookup never returns a key-bound token; sign-out/removal still purge key-bound ATs.
• msal/{region,telemetry,sku}.py — regional mtls-endpoint plumbing; token-type telemetry (mtls_pop→6); version → 1.38.0.
• Backward compatible — the existing SN/I + Bearer (private_key_jwt) flow is untouched; the same cert works either way.

Tests & docs

• tests/test_mtls_transport.py (new, 17) plus additions to test_application.py, test_token_cache.py, test_region.py, and two self-skipping E2E cases in test_e2e.py. Full unit suite passes; no regressions.
• docs/index.rst gains an "mTLS Proof-of-Possession (SN/I certificate)" section; new sample/confidential_client_mtls_pop_sample.py.

Notes

• mTLS PoP requires a tenanted authority and MSAL's built-in transport (no custom http_client) — both enforced with clear ValueErrors.
• Targets public + Azure Government (Arlington); other sovereign clouds are fenced off in msal/mtls.py for easy lifting later.

[Copilot]

Pull request overview

Adds mTLS Proof-of-Possession support for confidential clients using SN/I certificates, including mTLS-bound token acquisition, transport handling, telemetry updates, and cache isolation so Bearer and key-bound tokens can safely coexist.

Changes:

• Introduces mTLS transport + endpoint transformation/guardrails for mTLS PoP token requests.
• Adds mtls_proof_of_possession support to acquire_token_for_client(), including FIC leg-2 over mTLS behavior and public binding material in results.
• Updates token cache + telemetry to properly isolate and classify mtls_pop tokens; adds unit/E2E tests, docs, and a sample.

Reviewed changes

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

Show a summary per file

File	Description
tests/test_token_cache.py	Adds coverage ensuring Bearer and mtls_pop ATs coexist and don’t cross-match.
tests/test_optional_thumbprint.py	Updates certificate mock shape to include PEM material.
tests/test_mtls_transport.py	New tests for host transform/guardrails, SSLContext creation, adapter injection, and lazy session creation.
tests/test_e2e.py	Adds E2E scenarios for SN/I over mTLS PoP and FIC two-leg over mTLS.
tests/test_application.py	Adds unit tests validating request wiring, cache hits, backward compat, regional routing, FIC leg-2, and guardrails.
sample/confidential_client_mtls_pop_sample.py	New sample demonstrating vanilla mTLS PoP and optional FIC two-leg flow.
msal/token_cache.py	Adds key_id support to AT cache keys and prevents unkeyed queries from matching keyed entries.
msal/telemetry.py	Adds token-type mapping for mtls_pop and emits the platform config field when needed.
msal/sku.py	Bumps version to 1.38.0.
msal/oauth2cli/oauth2.py	Adds jwt-pop client assertion type constant.
msal/mtls.py	New module implementing mtlsauth host mapping/guardrails and a requests transport that presents a client cert.
msal/application.py	Adds cert-material plumbing, _MtlsClient, mTLS client selection, cache binding via key_id, and public binding result.
docs/index.rst	Documents new mTLS PoP feature, requirements, and usage patterns.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

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

[4gust]

Go's PR might not accept sts.windows.net, I think there is a gate for "login.*". can you verify if this is intended or not?

[VinodAnandan]

@Robbie-Microsoft Thank you for this important PR. It will significantly improve security, and we're looking forward to seeing it merged and included in an upcoming release.

@Robbie-Microsoft, @4gust Would you happen to have an estimated timeline for when this PR might be merged?

[gladjohn]

Thanks for putting this together. Before this moves forward, I have some concerns that make the feature feel incomplete from my perspective.

1. Missing the flow I actually need: Bearer over mTLS

This PR delivers mtls_pop (proof-of-possession) tokens, but it does not cover Bearer tokens obtained over an mTLS connection using bound credentials.

Presenting the certificate as the TLS client certificate should be usable to obtain a Bearer access token, not only a PoP-bound one. As currently designed, the moment the certificate is used as the TLS binding, the result is forced to mtls_pop, and the cache explicitly prevents a Bearer lookup from ever returning a key-bound token.

That closes off the exact scenario I'm after.

Can we clarify whether Bearer-over-mTLS is in scope, and if not, why it was excluded?

2. No spec, design, or task to anchor the work

I can't find a linked spec, design doc, or tracking issue for this change. Without that, it's hard to review the intended scope, the token-type decision matrix (Bearer vs. mtls_pop vs. SN/I+Bearer), the caching/isolation model, and the sovereign cloud fencing.

Could you link the design and the work item(s) this implements? That would also make it clear which scenarios are intentionally deferred versus simply missing.

3. This isn't a 1:1 port of the MSAL.NET feature

The description says the wire behavior "mirrors MSAL.NET," but the surfaced capabilities don't appear to be a 1:1 parity port. MSAL.NET's mTLS support covers more than just the mtls_pop path implemented here.

If we're claiming parity, I'd like to see a comparison of what MSAL.NET exposes versus what this PR exposes, with any intentional gaps called out explicitly. Otherwise, we risk shipping a partial subset under the impression it matches .NET.

Ask

Could you:

• Link the spec, design, and tracking issue.
• Confirm whether Bearer-over-mTLS is planned (in this PR, a follow-up, or intentionally out of scope).
• Provide a feature parity matrix against MSAL.NET.

As it stands, I don't think this is complete enough to merge for my use case.