[API Proposal] Add WithMtlsPopFallback() and MtlsPopOptions for managed identity mTLS PoP with automatic attested-to-non-attested fallback

[gladjohn]

Summary

Proposes a new public API on AcquireTokenForManagedIdentityParameterBuilder that enables mTLS Proof-of-Possession token acquisition with automatic fallback from attested to non-attested binding when attestation fails.

Higher-level SDKs (e.g., Microsoft.Identity.Web) should not need to understand or orchestrate attestation internals. They need a bound token — MSAL should handle the "how."

Problem

Today, IdWeb must explicitly call:

miBuilder.WithMtlsProofOfPossession()
         .WithAttestationSupport();

This has three issues:

1. IdWeb is coupled to attestation — a low-level binding mechanism detail.
2. No fallback — if attestation fails (provider exception, KeyGuard unavailable), MSAL throws instead of falling back to non-attested mTLS PoP.
3. Rigid strategy — IdWeb hard-codes the binding approach rather than declaring intent.

Proposed API

Two equivalent ways to opt in (Option 1 is sugar for Option 2):

Option 1: WithMtlsPopFallback() (Recommended)

miBuilder.WithMtlsPopFallback()
         .WithAttestationSupport();   // still needed — brings in native DLL

Option 2: WithMtlsProofOfPossession(MtlsPopOptions)

miBuilder.WithMtlsProofOfPossession(new MtlsPopOptions { EnableFallback = true })
         .WithAttestationSupport();   // still needed — brings in native DLL

New Options Class

public class MtlsPopOptions
{
    /// <summary>
    /// When true, MSAL attempts attested binding first and silently
    /// falls back to non-attested mTLS PoP if attestation fails.
    /// When false (default), attestation failures throw exceptions.
    /// </summary>
    public bool EnableFallback { get; set; }
}

Fallback Behavior

When EnableFallback = true:

Scenario	Current Behavior	New Behavior
KeyGuard + attestation succeeds	✅ Works	✅ Same
KeyGuard + attestation fails	❌ Throws attestation_failed	🔄 Falls back to non-attested flow
Non-KeyGuard key (Hardware/InMemory)	❌ Throws mtls_pop_requires_keyguard	🔄 Proceeds with non-attested mTLS PoP
Attestation provider not configured	✅ Non-attested flow	✅ Same
IMDSv1 host (no mTLS support)	❌ Throws	❌ Throws (correct — bound token required)

How IdWeb Changes

// Before — IdWeb knows about attestation
- miBuilder.WithMtlsProofOfPossession()
-          .WithAttestationSupport();

// After — IdWeb declares intent, MSAL handles fallback
+ miBuilder.WithMtlsPopFallback()
+          .WithAttestationSupport();

• WithAttestationSupport() becomes a capability registration (brings in native DLL), not a strategy directive.
• WithMtlsProofOfPossession() (no args) remains as the strict, no-fallback API for advanced callers.

Breaking Changes

None. Purely additive:

• WithMtlsProofOfPossession() — unchanged
• WithAttestationSupport() — unchanged
• WithMtlsPopFallback() — new
• WithMtlsProofOfPossession(MtlsPopOptions) — new overload
• MtlsPopOptions — new class

Related

• IdWeb PR: [Draft] - Add mTLS Proof-of-Possession support for Managed Identity (Pure MSI + FIC) microsoft-identity-web#3773
• Full spec: msal-bound-token-api-spec.md

[Copilot]

Pull request overview

Adds a draft API specification document for a new managed identity mTLS PoP “fallback” experience, aiming to let higher-level SDKs request a bound token without having to orchestrate attestation behavior directly.

Changes:

• Adds a new markdown spec describing WithMtlsPopFallback() and WithMtlsProofOfPossession(MtlsPopOptions) (with EnableFallback) for managed identity.
• Documents proposed internal plumbing (IsBoundTokenFallbackEnabled) and the intended fallback behavior in ImdsV2ManagedIdentitySource.
• Describes intended logging/telemetry and discusses cache key partitioning implications.