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.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

msal/token_cache.py:328

• The key_id isolation gate has the same issue as ext_cache_key: "key_id" not in (query or {}) only checks presence of the key, so a query that includes key_id=None will bypass isolation and may match key-bound tokens (e.g., mtls_pop) even though the caller effectively did not provide a key_id. This can cause a Bearer-style lookup to “leak” a bound token if callers build query dicts with key_id set to a default None.

                    if (credential_type == self.CredentialType.ACCESS_TOKEN
                        and not for_removal
                        and "key_id" in entry
                        and "key_id" not in (query or {})
                    ):

msal/token_cache.py:316

• In the ext_cache_key isolation gate, the check "ext_cache_key" not in (query or {}) only tests key presence, not whether the caller actually provided a non-empty ext_cache_key. A query that includes ext_cache_key=None (or other falsy value) will bypass this isolation and can unintentionally match ext-bound (FMI) tokens, contradicting the docstring guarantee that queries “without one” must not match ext-bound entries.

                    if (credential_type == self.CredentialType.ACCESS_TOKEN
                        and not for_removal
                        and "ext_cache_key" in entry
                        and "ext_cache_key" not in (query or {})
                    ):

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

msal/token_cache.py:26

• _key_id_to_str() is intended to be defensive (“building the cache key never raises”), but key_id.decode('ascii') can still raise UnicodeDecodeError if a caller provides non-ASCII bytes (e.g., raw digest bytes). That would still crash cache key construction.

Consider catching decode failures and falling back to an ASCII-safe representation (e.g., base64url) so any bytes value stays non-throwing.

def _key_id_to_str(key_id):
    """Coerce a key_id (base64url x5t#S256) into a str for the AT cache key.

    It is normally an ASCII str, but tolerate bytes (decoded as ASCII) or any
    other type so that building the cache key never raises ``TypeError``.
    """
    if isinstance(key_id, bytes):
        return key_id.decode("ascii")
    return key_id if isinstance(key_id, str) else str(key_id)