docs: MSI v2 mTLS PoP — cross-language design, constraints, and SDK guidance

[gladjohn]

Summary

Unified design document covering MSI v2 mTLS PoP across all MSAL languages.
Consolidates findings from .NET (delivered), Python (two POC approaches),
and lays out the open questions for Java, Node, and Go.

What's covered

X.509 certificate and key constraints

• Key hierarchy: KeyGuard → Hardware → In-Memory
• SChannel vs OpenSSL — why non-exportable keys only work on Windows
• Resource call requirements: TLS 1.2, HTTP/1.1, x-ms-tokenboundauth header

Language status

• .NET: delivered — KeyGuard + attestation, full fallback chain
• Python KeyGuard POC (PR KeyGuard POC - Add documentation for MSI v2 mTLS in Python microsoft-authentication-library-for-python#904):
  WinHTTP/SChannel ctypes bridge, mtls_http_request() helper
• Python In-Memory POC (PR Create design document for MSI v2 In-Memory Key Approach microsoft-authentication-library-for-python#905):
  exportable software key, standard requests library, cross-platform
• Java, Node, Go: not started, key considerations noted

HTTP transport customization for higher-level SDKs

• The factory problem: binding cert is internal to MSAL, SDKs don't have it at config time
• .NET: four factory scenarios tested end-to-end on Azure VM
  (PR docs: Guidance for SDKs consuming MSAL — HttpClient factory with mTLS PoP #5935)
• Proposed GetBindingCertificateAsync static API
• Python and other languages: TBD

[Copilot]

Pull request overview

Adds a unified design document for MSI v2 mTLS Proof-of-Possession (PoP) across MSAL languages, capturing platform/key constraints, current language status (.NET delivered, Python POCs), and the shared HTTP transport customization challenge for higher-level SDKs.

Changes:

• Introduces a cross-language overview of X.509/key storage tiers and TLS stack constraints (SChannel vs OpenSSL-like stacks).
• Documents current implementation/POC status for .NET and Python and outlines considerations for Java/Node/Go.
• Describes the .NET IMsalMtlsHttpClientFactory approach and calls out remaining SDK integration gaps.

[Copilot]

Pull request overview

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

[Copilot]

The doc states that exportable/in-memory keys “work everywhere”, but MSAL.NET’s managed identity .WithMtlsProofOfPossession() currently throws on non-Windows platforms. Consider clarifying that MSAL.NET MI mTLS PoP is Windows-only today (even if the in-memory key tier exists), to avoid suggesting a supported cross-platform path in .NET.

Suggested change

	- **Exportable keys (in-memory)** work everywhere — the key bytes can be passed to any TLS stack.
	- **Non-exportable keys (KeyGuard, TPM)** only work with SChannel — which means Windows + a language runtime that uses SChannel.
	- **Exportable keys (in-memory)** are broadly compatible across platforms at the TLS layer — the key bytes can be passed to any TLS stack. However, that does **not** mean every MSAL SDK currently supports end-to-end managed identity mTLS PoP on every platform.
	- **Non-exportable keys (KeyGuard, TPM)** only work with SChannel — which means Windows + a language runtime that uses SChannel.
	- **MSAL.NET managed identity caveat** — today, `.WithMtlsProofOfPossession()` is effectively Windows-only for managed identity scenarios. Even though the in-memory/exportable key tier is cross-platform in principle, MSAL.NET currently throws on non-Windows platforms rather than offering a supported cross-platform MI mTLS PoP path.

[Copilot]

The sample chains .WithAttestationSupport(), which lives in the Microsoft.Identity.Client.KeyAttestation package/namespace. Consider adding a short note (or using statement) indicating the extra package dependency so readers can compile the example without guesswork.