Add WithRequestOverMtls() API and E2E test: attested bearer via IMDSv2 mTLS flow

[Copilot]

Adds a new public API WithMtlsBearerToken() that uses the full IMDSv2 attested mTLS flow (Credential Guard–issued certificate, mTLS connection to ESTS) but requests token_type=bearer, returning a standard bearer token with no binding certificate. Also adds the corresponding E2E test.

Changes proposed in this request

• Added WithMtlsBearerToken() extension method to ManagedIdentityPopExtensions.cs (Windows-only, mirrors WithMtlsProofOfPossession() but sends token_type=bearer to ESTS instead of token_type=mtls_pop)
• Plumbed IsMtlsBearerRequested flag through AcquireTokenCommonParameters, AcquireTokenForManagedIdentityParameters, AuthenticationRequestParameters, AcquireTokenForManagedIdentityParameterBuilder, ManagedIdentityAuthRequest, and AbstractManagedIdentity
• Updated routing in ManagedIdentityClient to route IsMtlsBearerRequested to IMDSv2 (same as IsMtlsPopRequested)
• Extended the KeyGuard validation in ImdsV2ManagedIdentitySource.CreateRequestAsync to cover both PoP and ****** under a unified credential_guard_not_available error code
• Added a separate cache partition for mTLS-bearer tokens (mtls_bearer key component) to keep them distinct from PoP tokens and plain IMDSv1 bearer tokens
• Updated PublicAPI.Unshipped.txt for all target frameworks
• Replaced the original AcquireToken_OnImdsV2_WithAttestation_NoMtlsPoP_ReturnsBearer E2E test with AcquireToken_OnImdsV2_WithMtlsBearerToken_ReturnsBearer, which calls .WithMtlsBearerToken().WithAttestationSupport() and asserts TokenType == "Bearer", BindingCertificate == null, absence of the cnf claim in the JWT payload, and TokenSource == IdentityProvider
• Updated unit test error code assertion to credential_guard_not_available

var result = await mi.AcquireTokenForManagedIdentity(GraphResource)
    .WithMtlsBearerToken()      // uses IMDSv2 attested flow, token_type=bearer
    .WithAttestationSupport()   // adds Credential Guard attestation JWT
    .ExecuteAsync()
    .ConfigureAwait(false);

Assert.AreEqual("Bearer", result.TokenType);
Assert.IsNull(result.BindingCertificate);
var jwt = new JwtSecurityToken(result.AccessToken);
Assert.IsFalse(jwt.Payload.ContainsKey("cnf"));
Assert.AreEqual(TokenSource.IdentityProvider, result.AuthenticationResultMetadata.TokenSource);

Testing
Updated E2E test uses .WithMtlsBearerToken() and runs on the MSALMSIV2 pool (Credential Guard / VBS enabled). Gracefully marks inconclusive if Credential Guard is unavailable. Unit test for the KeyGuard-not-available error path updated to match the new unified error code.

Performance impact
None.

Documentation

• All relevant documentation is updated.

[Copilot]

Pull request overview

Adds an end-to-end regression test in the Managed Identity IMDSv2 E2E suite to validate that when .WithMtlsProofOfPossession() is omitted (even if .WithAttestationSupport() is present), MSAL returns a standard Bearer token (no binding certificate) on an IMDSv2-capable host.

Changes:

• Added a new [DataRow]-driven E2E test covering SAMI and UAMI (clientId) scenarios for the “no mTLS PoP requested” path.
• Asserts Bearer token shape (TokenType == "Bearer", BindingCertificate == null) and that the token was acquired from the identity provider.

[Gladwin Johnson (gladjohn)]

We will need a new Bearer API to support this e2e

[Gladwin Johnson (gladjohn)]

Copilot resolve conflicts

[Copilot]

Copilot resolve conflicts

Conflicts resolved in commit d5a3f7c (merge commit). The main branch had introduced MtlsPopMinStrength/PoPOptions and refactored ImdsV2ManagedIdentitySource to delegate the token leg via AcquireMtlsBindingAsync(). Key resolutions:

• All six PublicAPI.Unshipped.txt files now include both our WithMtlsBearerToken entry and main's new PoPOptions/MinStrengthNotMet/WithMtlsProofOfPossession(PoPOptions) entries.
• Both IsMtlsBearerRequested and MtlsPopMinStrength are kept in all parameter/request types.
• AcquireMtlsBindingForDelegationAsync now sets _isMtlsBearerRequested from parameters (instead of hardcoding _isMtlsPopRequested = true), and ManagedIdentityAuthRequest routes both IsMtlsPopRequested and IsMtlsBearerRequested into the delegation path with appropriate auth scheme handling for each.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

[Gladwin Johnson (gladjohn)]

Updated the branch to current main and addressed the review feedback in the two latest commits:

• Naming (Bogdan Gavril (@bgavrilMS)): renamed the internal flag IsMtlsBearerRequested → PreferMsiV2 (your suggestion) on AcquireTokenCommonParameters and throughout the plumbing. The public API is now WithBearerOverMtls() (renamed from WithMtlsBearerToken()).
• Mutual exclusivity: WithMtlsProofOfPossession() and WithBearerOverMtls() now fail fast if both are set on the same request.
• Null guard: added an ArgumentNullException guard to WithBearerOverMtls() (parity with WithMtlsProofOfPossession()).
• Comment: clarified the "mTLS Bearer" comment in ManagedIdentityAuthRequest.
• Merge with main: dropped the now-removed managed-identity ClientClaims propagation and kept the PreferMsiV2 routing; PublicAPI.Unshipped.txt now lists only WithBearerOverMtls (the rest shipped on main).

MI-focused unit tests pass locally (530 passed / 0 failed / 1 skipped, net8.0) and the E2E project compiles.

[Copilot]

Pull request overview

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

Suppressed comments (2)

src/client/Microsoft.Identity.Client/ManagedIdentity/ManagedIdentityPopExtensions.cs:90

• The PR description and example code refer to a new public API named WithMtlsBearerToken(), but the implementation and PublicAPI entries introduce WithBearerOverMtls(). Please align the final public API name with the PR contract now (either rename the method/tests/PublicAPI to WithMtlsBearerToken, or update the PR description/example accordingly) to avoid confusion and potential follow-up breaking changes.

        public static AcquireTokenForManagedIdentityParameterBuilder WithBearerOverMtls(

src/client/Microsoft.Identity.Client/ManagedIdentity/ManagedIdentityClient.cs:54

• PreferMsiV2 is now routed through the same boolean path as IsMtlsPopRequested (by OR-ing them). This means that if the VM only supports IMDSv1, the code will throw MsalError.MtlsPopTokenNotSupportedinImdsV1 / MsalErrorMessage.MtlsPopTokenNotSupportedinImdsV1, which specifically mentions “mTLS Proof of Possession … private preview” and will be misleading for .WithBearerOverMtls() callers. Consider using a distinct error code/message for the mTLS-bearer-over-IMDSv2 requirement (or a more general mTLS-over-managed-identity not supported message) when PreferMsiV2 is the reason IMDSv2 is required.

            AbstractManagedIdentity msi = await GetOrSelectManagedIdentitySourceAsync(requestContext, parameters.IsMtlsPopRequested || parameters.PreferMsiV2, cancellationToken).ConfigureAwait(false);

[Gladwin Johnson (gladjohn)]

Renamed the public API WithBearerOverMtls() → WithRequestOverMtls() per the naming discussion with Bogdan Gavril (@bgavrilMS) (WithRequestOverMtls chosen over WithMtlsTransport).

Scope of the rename (commit fb8a87b81):

• Public method + both mutual-exclusivity error messages
• IMDSv1-fallback log hint and the XML <see cref>
• All 6 PublicAPI.Unshipped.txt files
• E2E test: call, method name, DataRow display names, comments

Left intentionally unchanged: the internal PreferMsiV2 flag, and the confidential-client SendCertificateOverMtls "bearer over mTLS" concept names (a separate feature).

Product + E2E test projects build clean (0 warn / 0 err).

[Copilot]

Pull request overview

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

Suppressed comments (1)

src/client/Microsoft.Identity.Client/ManagedIdentity/ManagedIdentityPopExtensions.cs:91

• The PR description/sample code refers to a new public API named WithMtlsBearerToken(), but the implementation and PublicAPI entries add WithRequestOverMtls(). Please align the PR description (and any intended naming) with the actual shipped API to avoid confusion for reviewers and consumers.

        /// <summary>
        /// Uses the IMDSv2 attested flow (Credential Guard–issued certificate over mTLS) to acquire
        /// a standard bearer token. The mTLS certificate authenticates the connection to the ESTS
        /// token endpoint, but the returned token carries <c>token_type=bearer</c> and has no
        /// binding certificate in the <see cref="AuthenticationResult"/>.
        /// Requires Windows Credential Guard (VBS) to be enabled on the host.
        /// When attestation is required, call <c>.WithAttestationSupport()</c> (from the
        /// <c>Microsoft.Identity.Client.KeyAttestation</c> package) after this method.
        /// </summary>
        /// <param name="builder">The AcquireTokenForManagedIdentityParameterBuilder instance.</param>
        /// <returns>The builder to chain .With methods.</returns>
        public static AcquireTokenForManagedIdentityParameterBuilder WithRequestOverMtls(
            this AcquireTokenForManagedIdentityParameterBuilder builder)