Add SN/I certificate support over mTLS Proof-of-Possession (PoP)

[Robbie-Microsoft]

Summary

Adds support for using a Subject-Name/Issuer (SN/I) certificate as the first-leg credential over mTLS Proof-of-Possession (PoP).

Today an SN/I cert is used to sign a private_key_jwt (x5c) client assertion, which yields a Bearer token (SNI + Bearer unchanged). This PR lets a confidential-client app present that same certificate as the client TLS certificate in the mutual-TLS handshake to the token endpoint, so Entra ID (ESTS) returns a token that is cryptographically bound to the cert (token_type=mtls_pop, cnf/x5t#S256). The credential is identical; only the mechanism changes (assertion-signer → TLS client cert).

Follow-up (stacked): the 2-leg Federated Identity Credential (FIC) over mTLS PoP has been split into its own PR — #1041 — per review feedback. This PR is now the core direct SN/I → mTLS PoP path (including FIC Leg 1, which reuses the same certificate code path).

Public API

// Direct SN/I cert -> mTLS-bound PoP token
IAuthenticationResult result = cca.acquireToken(
        ClientCredentialParameters.builder(Set.of("https://vault.azure.net/.default"))
                .mtlsProofOfPossession()          // opt in
                .build())
        .get();

result.metadata().tokenType();            // TokenType.MTLS_POP
result.metadata().bindingCertificate();   // public material only: x5c chain + x5t#S256

• ClientCredentialParameters.Builder.mtlsProofOfPossession()
• New public types: TokenType (BEARER / MTLS_POP), BindingCertificate (public material only), plus AuthenticationResultMetadata.tokenType() / bindingCertificate().

Internal changes

• New: TokenType, BindingCertificate, MtlsClientCertificateHelper (mTLS socket factory, thumbprint, binding-cert resolution), MtlsEndpointHelper (login.* → mtlsauth.* host rewrite; region optional → global mtlsauth.microsoft.com; tenanted-authority validation; sovereign-cloud fail-fast).
• Request building (TokenRequestExecutor): the direct cert path omits client_assertion and presents the certificate on the TLS handshake; the result populates tokenType/bindingCertificate.
• Transport: mTLS socket factory threaded through OAuthHttpRequest / HttpHelper / IHttpHelper via an injected mTLS DefaultHttpClient (MSAL owns the mTLS transport).
• Cache isolation: access-token cache keyed on {token_type + cert KeyId} so Bearer/PoP (and different certs) never alias.
• Telemetry: isolated TokenType.telemetryValue() (BEARER=2, MTLS_POP=6) for cross-SDK parity; the locked v5 wire header is intentionally left unchanged.

Backward compatibility

The existing SNI + Bearer (assertion) and broker SHR-PoP flows are unchanged and remain byte-for-byte identical — validated by the full existing unit suite.

Testing

• Unit: 3 new classes (MtlsEndpointHelperTest, MtlsClientCertificateHelperTest, MtlsProofOfPossessionTest) + a hermetic PKCS12 resource. Unit suite green (367 tests, 0 failures, 0 errors).
• E2E: MtlsPopIT — direct SNI→PoP (global + regional) and Bearer/PoP cache isolation. CI-only: requires the lab SN/I cert (non-CNG) + an ESTS allow-listed resource; ESTS gates mTLS PoP on the final resource audience.

Docs / samples

• New sample confidential-client/ClientCredentialMtlsProofOfPossession.java
• changelog.txt and .github/copilot-instructions.md updated
• Javadoc on all new public API

Out of scope / follow-ups

• 2-leg FIC over mTLS PoP → Add FIC Leg 2 over mTLS Proof-of-Possession (stacked on #1040) #1041 (stacked follow-up).
• Managed-identity first-leg mTLS variant (separate follow-up).
• User-scoped (user_fic) FIC over mTLS PoP.
• US Gov / China clouds (fail-fast today).

Risks / open questions

• The telemetry wire header intentionally does not yet carry token type (would require an ESTS-coordinated schema bump).

[Copilot]

Pull request overview

Adds confidential-client support for acquiring mTLS Proof-of-Possession (PoP) tokens using an SN/I certificate presented on the TLS handshake (instead of signing a private_key_jwt), and surfaces token-binding metadata to callers.

Changes:

• Introduces new public result metadata (TokenType, BindingCertificate, AuthenticationResultMetadata.tokenType() / bindingCertificate()).
• Implements mTLS PoP request execution: login.* → mtlsauth.* endpoint rewrite, mTLS socket factory transport injection, and omission of client_assertion for direct certificate auth.
• Adds cache-isolation dimensions and unit/integration tests, plus docs/sample updates.

Reviewed changes

Copilot reviewed 21 out of 22 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AcquireTokenByClientCredentialSupplier.java	Stamps cert KeyId for cache isolation when mTLS PoP is requested.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AuthenticationErrorCode.java	Adds MTLS_POP_ERROR for mTLS PoP configuration/runtime failures.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AuthenticationResultMetadata.java	Adds token type + binding certificate fields and builder support.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/BindingCertificate.java	New public type exposing x5c chain + x5t#S256 (public material only).
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ClientCredentialParameters.java	Adds mtlsProofOfPossession() opt-in and cache-key component support.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ClientCredentialRequest.java	Adds token_type=mtls_pop parameter when mTLS PoP is requested.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/HttpHelper.java	Exposes request-level HTTP execution overload used by mTLS path.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IHttpHelper.java	Adds overload to execute requests with an explicit HTTP client + telemetry.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MtlsClientCertificateHelper.java	Builds mTLS socket factory and derives binding-certificate public metadata.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MtlsEndpointHelper.java	Rewrites standard token endpoint host to mtlsauth.* and validates tenant/cloud.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/OAuthHttpRequest.java	Routes token requests through an injected mTLS HTTP client when configured.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenRequestExecutor.java	Creates mTLS transport/endpoint and populates result metadata for mTLS PoP.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenResponse.java	Captures token_type from token responses.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenType.java	New public enum for BEARER vs MTLS_POP token types.
msal4j-sdk/src/integrationtest/java/com/microsoft/aad/msal4j/MtlsPopIT.java	CI-only E2E validation for direct SNI→mTLS PoP and cache isolation.
msal4j-sdk/src/samples/confidential-client/ClientCredentialMtlsProofOfPossession.java	New sample showing direct SN/I cert → mTLS PoP token acquisition.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/MtlsClientCertificateHelperTest.java	Unit tests for socket factory, thumbprint computation, and binding cert behavior.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/MtlsEndpointHelperTest.java	Unit tests for endpoint derivation and cloud/tenant validation.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/MtlsProofOfPossessionTest.java	Unit tests verifying mTLS request shaping and cache-key isolation behavior.
changelog.txt	Documents the new mTLS PoP SN/I confidential-client support.
.github/copilot-instructions.md	Updates repo guidance to include the new client-credentials mTLS PoP flow.

[Copilot]

Pull request overview

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