[POC] Adds MSI v2 (mTLS PoP) support: mtls_proof_of_possession and with_attestation_support APIs

[Copilot]

POC - MSI v2

• Phase 1 - get an e2e to work with PythonNet (Complete)

• Phase 2 - remove PythonNet (Completed)

• Phase 3 - Cache MAA tokens (in progress)

---

This PR adds a the Managed Identity (MSI) v2 implementation to MSAL Python, mirroring the end-to-end flow and ergonomics of MSAL .NET. It enables mTLS Proof-of-Possession (PoP) tokens via the MSI v2 /issuecredential protocol and (optionally) KeyGuard-backed attestation on Windows, while preserving full backwards compatibility for existing MSI v1 users.

What’s included

New per-call API (opt-in)

Equivalent to MSAL .NET’s .WithMtlsProofOfPossession() / .WithAttestationSupport() builder patterns, exposed as per-call kwargs on acquire_token_for_client():

client = msal.ManagedIdentityClient(
    msal.SystemAssignedManagedIdentity(),
    http_client=requests.Session(),
)

result = client.acquire_token_for_client(
    resource="https://management.azure.com/",
    mtls_proof_of_possession=True,   # triggers /issuecredential + mTLS PoP flow
    with_attestation_support=True,   # opt-in KeyGuard attestation (Windows only)
)

# result["token_type"] == "mtls_pop"

• mtls_proof_of_possession=True — uses MSI v2 /issuecredential flow; otherwise MSI v1 remains unchanged.
• with_attestation_support=True — enables Windows KeyGuard attestation via AttestationClientLib.dll (no-op elsewhere).
• No silent fallback when MSI v2 is explicitly requested per-call: failures surface to the caller.

---

New modules

msal/msi_v2.py — MSI v2 client (end-to-end)

Implements the full MSI v2 flow:

• Key creation
  • Windows: KeyGuard RSA key creation
  • Fallback: standard RSA key (cross-platform)
• PKCS#10 CSR generation
  • CSR signed with the sourced key
  • Includes OID 1.3.6.1.4.1.311.90.2.10 (cuId extension)
• IMDS integration
  • /getplatformmetadata platform metadata retrieval
  • /issuecredential credential retrieval
• mTLS certificate binding
  • Ensures certificate is usable for TLS client authentication
• Token acquisition over mTLS
  • Uses IMDS-returned tenant to compose the ESTS token endpoint
  • Requests token_type=mtls_pop where supported
• Token binding verification
  • verify_cnf_binding() validates cnf.x5t#S256 matches the certificate SHA-256 thumbprint hash

msal/msi_v2_attestation.py — Attestation handling

Attestation integration layer:

• Windows native interop
  • AttestationClientLib.dll interop via ctypes for KeyGuard attestation
• Cross-platform fallback
  • Returns None (CSR-only / non-attested operation) when KeyGuard isn’t available
• MAA endpoint communication
  • Acquires attestation JWT for the key
• Integration surface
  • Clean interface consumed by managed_identity.py

---

Integration with existing managed identity flow

msal/managed_identity.py

• Adds a new MSI v2 backend surfaced via:
  • mtls_proof_of_possession / with_attestation_support kwargs on acquire_token_for_client()
• Adds MsiV2Error(ManagedIdentityError) for MSI v2 failure semantics
• Maintains backwards compatibility:
  • msi_v2_enabled (constructor param) and env var MSAL_ENABLE_MSI_V2 are retained with original silent-fallback behavior (see contract below)

msal/__init__.py

• Exports MsiV2Error

---

Error handling contract

How MSI v2 was requested	On failure
mtls_proof_of_possession=True (per-call)	MsiV2Error raised — no fallback
msi_v2_enabled=True (constructor / env var)	Silent fallback to MSI v1 Bearer (legacy behavior)

---

Deliverables

• sample/msi_v2_sample.py — runnable reference sample aligned to the PowerShell protocol guide (PR #5771), with step-by-step logs
• tests/test_msi_v2.py — comprehensive tests with mocked IMDS for CI suitability
• Type hints (Python 3.7+), extensive debug logging, and robust error handling

---

Why this matters

MSI v2 introduces an orchestrated, multi-hop flow (KeyGuard → attestation → IMDS → mTLS → ESTS) with many failure domains. This PR makes MSI v2 first-class in MSAL Python with:

• Clear, actionable logs per step
• Strong token binding validation (cnf.x5t#S256)
• Explicit opt-in semantics (no surprise downgrades when callers request PoP)

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.