Add FIC Leg 2 over mTLS Proof-of-Possession (stacked on #1040)

[Robbie-Microsoft]

Summary

Follow-up to #1040. Adds 2-leg Federated Identity Credential (FIC) over mTLS Proof-of-Possession (PoP): an app that authenticates with a federated client assertion can still bind the resulting token to a certificate. The assertion is sent with client_assertion_type=...:jwt-pop and the binding certificate is presented on the mTLS handshake, so the final token is bound to the Leg-1 certificate thumbprint.

Stacked on #1040 (base rginsburg/sni-mtls-pop), so the diff is exactly the Leg-2 additions on top of the core work. Retarget the base to dev after #1040 merges.

Public API

ConfidentialClientApplication.builder(clientId, ClientCredentialFactory.createFromClientAssertion(t1))
        .mtlsBindingCertificate(sniCert)   // binding cert presented on the TLS handshake
        .build();

• ConfidentialClientApplication.Builder.mtlsBindingCertificate(IClientCertificate)

Internal changes

• Request building (TokenRequestExecutor): under mTLS PoP with an assertion credential, the assertion is sent with client_assertion_type=...:jwt-pop and the binding cert is presented on the mutual-TLS handshake.
• MtlsClientCertificateHelper.resolveBindingCertificate falls back to the configured mtlsBindingCertificate(...) only when the credential is an IClientAssertion (FIC Leg 2); a non-assertion credential (e.g. a client secret) with a stray binding cert fails with MTLS_POP_ERROR.
• AssertionRequestOptions carries the PoP flag through to assertion construction; adds the ClientAssertion.ASSERTION_TYPE_JWT_POP constant.

Testing

• Unit: ficLeg2_assertionWithBindingCert_usesJwtPopAssertionType (MtlsProofOfPossessionTest); resolveBindingCertificate positive (assertion+cert) and negative (secret+cert → MTLS_POP_ERROR) tests (MtlsClientCertificateHelperTest). Suite green (385 tests).
• E2E: acquireTokenFic_TwoLeg_MtlsPop_BothLegsBound (MtlsPopIT, CI-only — needs the lab SN/I cert + an ESTS allow-listed resource).

Out of scope

Unchanged from #1040: user-scoped (user_fic) FIC over mTLS PoP, managed-identity first-leg mTLS, and the two legacy sovereign hosts.

[Copilot]

Pull request overview

This PR extends MSAL4J’s confidential-client mTLS Proof-of-Possession (PoP) support to cover 2-leg Federated Identity Credential (FIC) “Leg 2” scenarios, where the app authenticates using a client assertion while still binding the resulting token to a certificate presented on the mTLS handshake.

Changes:

• Add ConfidentialClientApplication.Builder.mtlsBindingCertificate(IClientCertificate) to supply a binding certificate for assertion-authenticated mTLS PoP requests.
• Update token request construction to use client_assertion_type=...:jwt-pop when mtlsProofOfPossession() is set with a client assertion credential.
• Re-introduce unit/integration tests and expand the sample/docs to demonstrate the 2-leg FIC over mTLS PoP flow.

Reviewed changes

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

Show a summary per file

File	Description
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ConfidentialClientApplication.java	Adds builder option + getter for mtlsBindingCertificate used to present a cert on the mTLS handshake for assertion-authenticated apps.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenRequestExecutor.java	Switches client-assertion requests to jwt-pop assertion type under mTLS PoP and threads PoP context to assertion construction.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MtlsClientCertificateHelper.java	Extends binding-certificate resolution to fall back to mtlsBindingCertificate for assertion-authenticated scenarios.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ClientCredentialParameters.java	Updates mTLS PoP Javadoc to mention mtlsBindingCertificate(...) for assertion-authenticated apps.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ClientAssertion.java	Introduces ASSERTION_TYPE_JWT_POP constant for client_assertion_type.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AssertionRequestOptions.java	Adds a PoP flag to the context passed to context-aware assertion providers.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/MtlsProofOfPossessionTest.java	Re-adds unit coverage for “FIC Leg 2” behavior (jwt-pop + binding cert).
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/MtlsClientCertificateHelperTest.java	Adds unit test to ensure binding cert resolves correctly for assertion-authenticated apps.
msal4j-sdk/src/integrationtest/java/com/microsoft/aad/msal4j/MtlsPopIT.java	Re-adds CI-only E2E test covering the 2-leg FIC mTLS PoP flow.
msal4j-sdk/src/samples/confidential-client/ClientCredentialMtlsProofOfPossession.java	Adds an end-to-end sample scenario showing developer-orchestrated 2-leg FIC over mTLS PoP.
changelog.txt	Notes the new 2-leg FIC over mTLS PoP capability.
.github/copilot-instructions.md	Updates internal repo guidance to mention mtlsBindingCertificate(...) for 2-leg FIC over mTLS PoP.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

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

[Gladwin Johnson (gladjohn)]

[Blocker/API] The assertion and binding certificate are configured through unrelated channels, so they can rotate independently and MSAL cannot prove they represent the same generation. This API also cannot consume #1059’s IMtlsBindingContext because it requires an exposed PrivateKey. Please replace it with an atomic callback result containing the assertion and exact reusable binding context.

[Gladwin Johnson (gladjohn)]

[Blocker] This derives both client_assertion_type=jwt-pop and output token_type=mtls_pop from one flag. These are independent dimensions: a binding-context-backed jwt-pop assertion can authenticate the client while the requested output token remains Bearer. Derive assertion type from the assertion’s binding material and output token type from the requested authentication scheme.

[Gladwin Johnson (gladjohn)]

[Blocker] The request is sent to the resolved global or regional mtlsauth endpoint, but the assertion callback receives the normal login.* token endpoint. A provider using this value as aud will mint an assertion for a different endpoint than the one receiving it. Please pass the exact final endpoint used by OAuthHttpRequest.

[Gladwin Johnson (gladjohn)]

[P1/API] A proofOfPossession boolean does not identify the certificate generation MSAL will put on the wire. The provider should atomically return a ClientSignedAssertion containing the assertion and IMtlsBindingContext, rather than returning only a string while relying on separately configured mutable application state.

[Gladwin Johnson (gladjohn)]

[Blocker] Binding resolution accepts any public IClientAssertion, but request serialization handles only the package-private concrete ClientAssertion. A valid custom implementation can therefore resolve a binding and reach the endpoint without any client_assertion parameters. Please process the public interface consistently or introduce a separate public capability interface.

[Gladwin Johnson (gladjohn)]

[Acceptance blocker] This is the only two-leg FIC E2E, but TOKEN_TYPE_MISMATCH aborts it as inconclusive. CI can therefore pass without proving that the service honored the requested binding. Run this against a deterministic supported cell and fail on every downgrade.

[Gladwin Johnson (gladjohn)]

[Acceptance blocker] Comparing locally generated metadata to the configured lab certificate does not prove protocol continuity. Decode T1 and T2 and require both cnf.x5t#S256 values to match the exact returned binding context’s key ID, then call the resource with T2 and that context. Add no-cert, wrong-scheme, wrong-cert, A→B→A and persistent-cache cases.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Suppressed comments (4)

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ConfidentialClientApplication.java:165

• The API documentation currently implies that this option works with any non-certificate credential, but resolveBindingCertificate deliberately accepts it only when the effective credential is an IClientAssertion; a client secret with this option fails with MTLS_POP_ERROR. Document the assertion-only constraint so callers are not led toward a configuration the implementation rejects.

         * This is required only when the application authenticates with a credential that is <b>not</b>
         * itself a certificate — for example, FIC Leg 2, where the application authenticates with a
         * federated assertion ({@link ClientCredentialFactory#createFromClientAssertion(String)}) but must
         * still bind the resulting token to a certificate. When the application's authentication credential

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenRequestExecutor.java:204

• The new mtlsPoP value passed to context-aware assertion callbacks is not covered: the added FIC test uses a static assertion, while the existing callback tests only exercise bearer requests. Add an mTLS assertion-callback test that verifies options.proofOfPossession() is true and that the resulting request uses client_assertion_type=jwt-pop; otherwise this public callback contract could regress unnoticed.

                AssertionRequestOptions options = new AssertionRequestOptions(
                        application.clientId(),
                        tokenEndpoint,
                        clientAssertionFmiPath,
                        mtlsPoP);

msal4j-sdk/src/integrationtest/java/com/microsoft/aad/msal4j/MtlsPopIT.java:45

• Adding the FIC scenario makes the later class-level “App/tenant requirement” paragraph inaccurate: it still says only the MSI-team allow-listed app/tenant can obtain mTLS PoP tokens and that any other app is rejected, while this new test uses the agentic blueprint in a different tenant. Qualify that requirement as applying to the direct-SNI cells so the test prerequisites do not contradict the new scenario.

 *   <li><b>2-leg FIC over mTLS PoP</b> &mdash; both legs are mTLS-PoP requests and the final token is
 *       bound to the Leg-1 certificate thumbprint.</li>

msal4j-sdk/src/integrationtest/java/com/microsoft/aad/msal4j/MtlsPopIT.java:289

• These assertions do not verify that T2 is actually bound to this certificate: bindingCertificate() is populated locally from resolvedBindingCertificate after checking only the response's token_type, so the thumbprint comparison will pass without inspecting or exercising the token's cnf. The direct-SNI E2E test proves binding by calling the mTLS-enabled resource with the token and certificate; add an equivalent validation for Leg 2 (or otherwise validate T2's cnf) so this test can detect an incorrectly bound server response.

        assertEquals(TokenType.MTLS_POP, leg2.metadata().tokenType(),
                "Leg 2 must also be an mTLS-PoP (cert-bound) token");
        assertNotNull(leg2.metadata().bindingCertificate(), "Leg 2 must expose its binding certificate");
        assertEquals(expectedLabThumbprint(), leg2.metadata().bindingCertificate().thumbprintSha256(),
                "Final token (T2) must be bound to the Leg-1 certificate thumbprint");