POC 2: MSI v2 mTLS PoP — WindowsCertificate + SchannelSession

[gladjohn]

Summary

End-to-end mTLS Proof-of-Possession for Managed Identity v2 on Windows Azure VMs with Credential Guard / KeyGuard.

E2E proven on MSIV2 VM (June 2026): Token acquired → cert binding verified → downstream mTLS call to tokenbinding.vault.azure.net returned HTTP 200 with secret value.

What's included

Core (msal package)

• msal/windows_certificate.py — Python equivalent of .NET X509Certificate2. Wraps NCRYPT_KEY_HANDLE, thread-safe CERT_CONTEXT creation, lifecycle management.
• msal/msi_v2.py — Full MSI v2 flow: KeyGuard key mgmt, CSR, MAA attestation, issuecredential, WinHTTP/SChannel mTLS token acquisition. Returns binding_certificate in result.
• msal/managed_identity.py — Public API: acquire_token_for_client(mtls_proof_of_possession=True, with_attestation_support=True)

Separate packages

• msal-schannel-transport/ — WinHTTP/SChannel HTTP client for downstream mTLS (bypasses OpenSSL which cannot use non-exportable keys). Self-contained Win32 bindings.
• msal-key-attestation/ — Python wrapper for MAA attestation. Native DLL sourced from NuGet: Microsoft.Azure.Security.KeyGuardAttestation v1.1.5 (not bundled in this PR).

Dev app + docs

• sample/devapp_msi_v2_mtls/app.py — Uses ONLY public MSAL API
• docs/mTLS-PoP-Architecture-Decision.md — Why WinHTTP/SChannel (OpenSSL CNG provider gap research)

App developer usage

import msal
from msal_schannel_transport import SchannelSession

client = msal.ManagedIdentityClient(msal.SystemAssignedManagedIdentity(), http_client=requests.Session())
result = client.acquire_token_for_client(
    resource="https://vault.azure.net",
    mtls_proof_of_possession=True, with_attestation_support=True)

with SchannelSession(client_certificate=result["binding_certificate"]) as session:
    resp = session.get(url, headers={
        "Authorization": f"{result['token_type']} {result['access_token']}",
        "x-ms-tokenboundauth": "true"})

E2E Results (MSIV2 VM)

Step	Result
Token acquisition	✓ mtls_pop, 86399s
Cert binding (cnf.x5t#S256)	✓ MATCH
Downstream mTLS (tokenbinding vault)	✓ HTTP 200, secret returned

Notes

• AttestationClientLib.dll (5.3MB) not included — sourced from NuGet at build time
• Cert cache threshold: 1h remaining lifetime (IMDS certs are ~8h)
• 52/52 unit tests pass locally

[Copilot]

Pull request overview

This PR introduces a Windows-only end-to-end MSI v2 flow for Managed Identity mTLS Proof-of-Possession (PoP), including a handle-backed certificate wrapper (WindowsCertificate), the MSI v2 implementation (msal.msi_v2), and companion packages for KeyGuard attestation and WinHTTP/SChannel downstream mTLS calls.

Changes:

• Add MSI v2 (IMDSv2) token acquisition over WinHTTP/SChannel with KeyGuard key management, CSR issuance, optional MAA attestation, and in-memory certificate caching.
• Add WindowsCertificate (platform key-handle backed) and expose new ManagedIdentityClient.acquire_token_for_client() opt-in flags for MSI v2 gating.
• Add new tests/docs/samples and two new sub-packages: msal-key-attestation and msal-schannel-transport.

Reviewed changes

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

Show a summary per file

File	Description
tests/test_msi_v2.py	Unit coverage for cnf binding, cache behavior, and MI client gating.
tests/test_e2e_mtls_pop.py	Windows-only E2E test wiring MSAL MSI v2 token + downstream Schannel mTLS call.
sample/msi_v2_sample.py	Sample script demonstrating MSI v2 token acquisition and (non-mTLS) request header usage.
sample/MSI_V2_GUIDE.md	Setup/usage guide for MSI v2 + attestation.
sample/devapp_msi_v2_mtls/app.py	Dev app showing public-API-only flow + downstream SchannelSession call.
msal/windows_certificate.py	New handle-backed certificate wrapper with store lookup and CERT_CONTEXT creation.
msal/msi_v2.py	New MSI v2 implementation: KeyGuard key, CSR, IMDS calls, cert binding, WinHTTP mTLS token acquisition, cert cache.
msal/managed_identity.py	Adds MsiV2Error and new opt-in flags to route MSI v2 flow from public API.
msal/__init__.py	Exposes WindowsCertificate at package root (public API surface).
msal-schannel-transport/pyproject.toml	Defines new transport package metadata/build config.
msal-schannel-transport/msal_schannel_transport/session.py	Implements WinHTTP/SChannel session for downstream mTLS calls.
msal-schannel-transport/msal_schannel_transport/__init__.py	Transport package exports + usage docstring.
msal-key-attestation/pyproject.toml	Defines new attestation package metadata/build config and dependency on msal.
msal-key-attestation/msal_key_attestation/attestation.py	Implements AttestationClientLib.dll bindings + JWT caching and provider factory.
msal-key-attestation/MANIFEST.in	Packaging include/exclude rules for the attestation package.
msal-key-attestation/LICENSE	License file for the attestation package.
docs/mTLS-PoP-Architecture-Decision.md	Architecture decision record explaining WinHTTP/SChannel approach and separation of packages.
docs/MSI_V2_API.md	API reference documentation for MSI v2 public API usage and behavior.

---

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

[Copilot]

Pull request overview

Copilot reviewed 38 out of 40 changed files in this pull request and generated 8 comments.