Harden SNI mTLS PoP E2E: prove real resource usability, skip off-CI, name the X509 matrix

Ports the rigor from the merged MSAL.NET reference (PR #6100) to the SNI mTLS PoP
integration tests and docs:

- Add reusable MtlsResourceCaller.callResourceWithMtlsToken(url, token, cert): presents
  the binding certificate on the TLS handshake (reusing createMtlsSocketFactory), sends
  Authorization: mtls_pop <token>, GETs the resource, returns the status; drains and never
  logs the external body. The headline PoP test now calls mtlstb.graph.microsoft.com and
  requires HTTP 200, proving the bound token is genuinely usable (not just well-formed).
- Fix the @BeforeAll escape hatch: assertNotNull on the lab cert hard-failed the whole
  class off-CI; use Assumptions.assumeTrue so it skips instead (missing lab cert is an
  environment condition, not a defect).
- Establish the Credential_X509_Output_<Pop|Bearer> naming: rename the PoP tests into the
  family and add a standalone Credential_X509_Output_Bearer (asserts BEARER + null binding
  cert) instead of relying only on the cache-isolation side effect.
- Remove a redundant assertNotNull(thumbprint) immediately before assertEquals.
- Add docs/mtls-pop.md documenting the correct public API (mtlsProofOfPossession(),
  result.metadata().tokenType()/bindingCertificate(), region optional/global fallback,
  tenanted authority, Bearer omission is mTLS-specific). Written fresh; not copied from the
  stale #1021 branch.
- Fix the sample's missing ClientCredentialFactory import.

The Fic E2E resource call reuses MtlsResourceCaller in the FIC follow-up (#1041).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: Robbie-Microsoft

msal4j-sdk/docs/mtls-pop.md

@@ -0,0 +1,74 @@
+# SN/I certificate over mTLS Proof-of-Possession (PoP)
+
+MSAL4J lets a confidential-client application present its **Subject-Name/Issuer (SN/I) certificate as
+the client TLS certificate** during the mutual-TLS handshake to the token endpoint. Entra ID (ESTS)
+then returns an access token that is **cryptographically bound to that certificate**
+(`token_type=mtls_pop`, bound via `cnf` / `x5t#S256`), instead of a plain Bearer token.
+
+The credential is exactly the same certificate you already use for SN/I authentication — only the
+mechanism changes: instead of signing a `private_key_jwt` (x5c) client assertion, the certificate is
+presented on the TLS handshake.
+
+> mTLS PoP is a **confidential-client** feature. It is distinct from the broker-based Signed-HTTP-Request
+> (SHR) PoP used by public clients (`token_type=pop`), which is unaffected.
+
+## Enabling it
+
+Opt in per request with `ClientCredentialParameters.Builder.mtlsProofOfPossession()`:
+
+```java
+ConfidentialClientApplication cca =
+        ConfidentialClientApplication.builder(CLIENT_ID, sniCertificate)
+                .authority("https://login.microsoftonline.com/<tenant>/") // tenanted authority required
+                // .azureRegion("westus")   // OPTIONAL — omit for the global mtlsauth.microsoft.com endpoint
+                .build();
+
+ClientCredentialParameters parameters =
+        ClientCredentialParameters
+                .builder(Collections.singleton("https://graph.microsoft.com/.default"))
+                .mtlsProofOfPossession()     // request an mTLS-bound PoP token
+                .build();
+
+IAuthenticationResult result = cca.acquireToken(parameters).join();
+
+result.metadata().tokenType();            // TokenType.MTLS_POP
+result.metadata().bindingCertificate();   // public material only: x5c chain + x5t#S256 thumbprint
+```
+
+The resulting token is bound to the certificate. To call a protected resource, present the **same
+certificate** on the TLS handshake and send the token with the `mtls_pop` authorization scheme:
+
+```
+Authorization: mtls_pop <access_token>
+```
+
+`BindingCertificate` exposes public material only (the `x5c` chain and the SHA-256 thumbprint); the
+private key is never exported — it is used in place through its own provider.
+
+## Bearer vs. mTLS PoP
+
+Without `mtlsProofOfPossession()`, the SN/I certificate behaves exactly as before: it **signs and sends
+a `private_key_jwt` client assertion**, and the result is a `TokenType.BEARER` token with no binding
+certificate. Omitting the client assertion (and presenting the certificate on the TLS handshake
+instead) is **specific to the mTLS PoP path**; the legacy SNI + Bearer flow is unchanged.
+
+Bearer and mTLS-PoP tokens for the same scope are cached separately (keyed on
+`{token_type + certificate key id}`), so enabling PoP never aliases an existing Bearer entry.
+
+## Requirements and notes
+
+- **Tenanted authority is required.** `/common` and `/organizations` are rejected on the mTLS PoP path.
+- **Region is optional.** Omit `azureRegion(...)` to use the global `mtlsauth.microsoft.com` endpoint
+  (production-ready via ESTS-R regional failover), or set a region to target
+  `<region>.mtlsauth.microsoft.com` (recommended when you know your region).
+- **Resource audience must be allow-listed.** ESTS gates mTLS PoP on the **final resource audience**,
+  which must be an ESTS mTLS-PoP allow-listed resource (for example Azure Key Vault or Microsoft Graph),
+  not the client app itself.
+- **Cloud support.** Azure Public, Azure Government, and the current national clouds are supported (the
+  `login.*` authority host is rewritten to the matching `mtlsauth.*` host). Two legacy sovereign hosts
+  that have no `mtlsauth.*` endpoint — `login.usgovcloudapi.net` and `login.chinacloudapi.cn` — are not
+  supported and fail fast.
+
+See also the runnable sample:
+[`src/samples/confidential-client/ClientCredentialMtlsProofOfPossession.java`](../src/samples/confidential-client/ClientCredentialMtlsProofOfPossession.java),
+and https://aka.ms/msal4j-pop.

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

@@ -21,11 +21,13 @@
 import java.util.Collections;
 import java.util.concurrent.ExecutionException;
 
+import static com.microsoft.aad.msal4j.TestConstants.AGENTIC_GRAPH_SCOPE;
 import static com.microsoft.aad.msal4j.TestConstants.KEYVAULT_DEFAULT_SCOPE;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
 
 /**
  * End-to-end integration tests for SN/I certificate over mTLS Proof-of-Possession (PoP).
@@ -66,6 +68,11 @@ class MtlsPopIT {
             "https://login.microsoftonline.com/bea21ebe-8b64-4d06-9f6d-6a889b120a7c";
     private static final String TEST_SLICE_REGION = "westus3";
 
+    // mTLS-enabled MS Graph host (NOT plain graph.microsoft.com, which does not perform the client-cert
+    // handshake). A token bound to the presented certificate is accepted here with HTTP 200.
+    private static final String MTLS_GRAPH_RESOURCE =
+            "https://mtlstb.graph.microsoft.com/v1.0/applications?$top=1";
+
     private PrivateKey privateKey;
     private X509Certificate publicCertificate;
     private IClientCertificate certificate;
@@ -79,39 +86,79 @@ void init() throws KeyStoreException, NoSuchProviderException, IOException,
         privateKey = (PrivateKey) keystore.getKey(KeyVaultSecretsProvider.CERTIFICATE_ALIAS, null);
         publicCertificate = (X509Certificate) keystore.getCertificate(KeyVaultSecretsProvider.CERTIFICATE_ALIAS);
 
-        assertNotNull(privateKey, "Lab private key not found. Ensure the lab cert is installed.");
-        assertNotNull(publicCertificate, "Lab certificate not found. Ensure the lab cert is installed.");
+        // These are live-lab E2E tests (like the other *IT classes). Off-CI the lab SN/I cert is absent
+        // from the OS keystore, so SKIP the whole class rather than hard-failing it: a missing lab cert
+        // is an environment condition, not a product defect.
+        Assumptions.assumeTrue(privateKey != null && publicCertificate != null,
+                "Lab SN/I certificate not available (alias '" + KeyVaultSecretsProvider.CERTIFICATE_ALIAS
+                        + "'); skipping mTLS PoP E2E. Expected off-CI.");
 
         certificate = ClientCredentialFactory.createFromCertificate(privateKey, publicCertificate);
     }
 
     /**
-     * Direct SNI cert &rarr; mTLS PoP with <b>no region</b> (exercises the global
-     * {@code mtlsauth.microsoft.com} endpoint). The lab cert is presented as the client TLS certificate;
-     * the request carries {@code token_type=mtls_pop} and <b>no</b> client assertion. Requests an
-     * allow-listed resource (Key Vault) so ESTS issues the bound token.
+     * <b>X509 SNI cert &rarr; mTLS PoP, proven end to end.</b> Canonical matrix cell
+     * {@code Credential_X509_Output_Pop}: with <b>no region</b> configured (global
+     * {@code mtlsauth.microsoft.com} endpoint), the lab cert is presented as the client TLS certificate
+     * and the request carries {@code token_type=mtls_pop} with <b>no</b> client assertion.
+     *
+     * <p>Beyond asserting the token is issued and bound to the cert, this proves the bound token is
+     * <b>actually usable</b>: it is presented (with the binding cert on the TLS handshake) to an
+     * mTLS-enabled resource, which must return HTTP 200. A 401/403 would mean the certificate was not
+     * presented or the {@code mtls_pop} scheme was wrong. The MS Graph scope is used because Graph is an
+     * ESTS mTLS-PoP allow-listed resource whose {@code mtlstb.graph.microsoft.com} host performs the
+     * client-cert handshake (the app must be granted Graph {@code Application.Read.All}).
      */
     @Test
-    void acquireTokenClientCredentials_Certificate_MtlsPop() throws Exception {
+    void Credential_X509_Output_Pop() throws Exception {
         ConfidentialClientApplication cca = ConfidentialClientApplication.builder(SNI_ALLOWLISTED_APP_ID, certificate)
                 .authority(SNI_ALLOWLISTED_AUTHORITY)   // tenanted authority (required for mTLS PoP)
                 .build();
 
         IAuthenticationResult result = acquireMtlsPopOrSkipOnDowngrade(cca, ClientCredentialParameters
-                        .builder(Collections.singleton(KEYVAULT_DEFAULT_SCOPE))
+                        .builder(Collections.singleton(AGENTIC_GRAPH_SCOPE))
                         .mtlsProofOfPossession()
                         .build());
 
         assertMtlsPopResult(result, expectedLabThumbprint());
+
+        int status = MtlsResourceCaller.callResourceWithMtlsToken(
+                MTLS_GRAPH_RESOURCE, result.accessToken(), certificate);
+        assertEquals(200, status,
+                "mTLS-enabled resource must accept the bound PoP token (HTTP 200); 401/403 means the "
+                        + "binding certificate was not presented on the handshake or the mtls_pop scheme was wrong");
+    }
+
+    /**
+     * Canonical matrix cell {@code Credential_X509_Output_Bearer}: the same SN/I cert <b>without</b>
+     * {@code mtlsProofOfPossession()} yields the existing {@code Bearer} token (the cert signs a
+     * {@code private_key_jwt} client assertion) and exposes <b>no</b> binding certificate. This anchors
+     * that opting out of mTLS PoP leaves the legacy SNI+Bearer behaviour intact.
+     */
+    @Test
+    void Credential_X509_Output_Bearer() throws Exception {
+        ConfidentialClientApplication cca = ConfidentialClientApplication.builder(SNI_ALLOWLISTED_APP_ID, certificate)
+                .authority(SNI_ALLOWLISTED_AUTHORITY)
+                .build();
+
+        IAuthenticationResult result = cca.acquireToken(ClientCredentialParameters
+                        .builder(Collections.singleton(KEYVAULT_DEFAULT_SCOPE))
+                        .build())   // no mtlsProofOfPossession() -> Bearer
+                .get();
+
+        assertNotNull(result.accessToken(), "Access token should not be null");
+        assertEquals(TokenType.BEARER, result.metadata().tokenType(), "Result token type should be BEARER");
+        assertNull(result.metadata().bindingCertificate(),
+                "Bearer result must not expose a binding certificate");
     }
 
     /**
-     * Direct SNI cert &rarr; mTLS PoP with a region configured (exercises the regional
-     * {@code <region>.mtlsauth.microsoft.com} endpoint), and verifies the bound token is cached and
-     * retrieved on a second call.
+     * {@code Credential_X509_Output_Pop} over the regional endpoint: with a region configured the
+     * request targets {@code <region>.mtlsauth.microsoft.com}, and the bound token is cached under
+     * {@code {token_type + cert KeyId}} and returned on a second call.
      */
     @Test
-    void acquireTokenClientCredentials_Certificate_MtlsPop_Regional() throws Exception {
+    void Credential_X509_Output_Pop_Regional() throws Exception {
         ConfidentialClientApplication cca = ConfidentialClientApplication.builder(SNI_ALLOWLISTED_APP_ID, certificate)
                 .authority(SNI_ALLOWLISTED_AUTHORITY)
                 .azureRegion(TEST_SLICE_REGION)
@@ -140,7 +187,7 @@ void acquireTokenClientCredentials_Certificate_MtlsPop_Regional() throws Excepti
      * aliases the existing SNI+Bearer path.
      */
     @Test
-    void acquireTokenClientCredentials_BearerAndMtlsPop_AreCacheIsolated() throws Exception {
+    void Credential_X509_Output_Pop_And_Bearer_CacheIsolated() throws Exception {
         ConfidentialClientApplication cca = ConfidentialClientApplication.builder(SNI_ALLOWLISTED_APP_ID, certificate)
                 .authority(SNI_ALLOWLISTED_AUTHORITY)
                 .build();
@@ -193,7 +240,6 @@ private void assertMtlsPopResult(IAuthenticationResult result, String expectedTh
 
         BindingCertificate binding = result.metadata().bindingCertificate();
         assertNotNull(binding, "mTLS-PoP result must expose a binding certificate");
-        assertNotNull(binding.thumbprintSha256(), "Binding certificate must expose its SHA-256 thumbprint");
         assertFalse(binding.certificateChain().isEmpty(), "Binding certificate must expose its x5c chain");
         assertEquals(expectedThumbprint, binding.thumbprintSha256(),
                 "Binding certificate thumbprint must match the lab SNI cert (x5t#S256)");

msal4j-sdk/src/integrationtest/java/com/microsoft/aad/msal4j/MtlsResourceCaller.java

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.aad.msal4j;
+
+import javax.net.ssl.HttpsURLConnection;
+import javax.net.ssl.SSLSocketFactory;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.HttpURLConnection;
+import java.net.URL;
+
+/**
+ * Test-only helper that calls a protected resource with an mTLS Proof-of-Possession (PoP) token,
+ * presenting the token's binding certificate as the client certificate on the TLS handshake.
+ *
+ * <p>Mirrors the resource-call contract validated by MSAL .NET (its {@code ResourceCaller}): the
+ * binding certificate is the client TLS certificate, the token is sent as
+ * {@code Authorization: mtls_pop <token>}, and a correctly bound token is accepted with HTTP 200. A
+ * 401/403 means the certificate was not presented on the handshake or the {@code mtls_pop} scheme was
+ * wrong. Reused by both the SNI and (later) FIC mTLS-PoP end-to-end tests, so acquiring a token is
+ * proven to be genuinely usable rather than only well-formed.
+ */
+final class MtlsResourceCaller {
+
+    private MtlsResourceCaller() {
+    }
+
+    /**
+     * GETs {@code resourceUrl}, presenting {@code bindingCert} as the client TLS certificate and the
+     * {@code mtls_pop} access token, and returns the HTTP status code.
+     *
+     * <p>The response body is drained and discarded — it must never be logged in (public) CI. Only the
+     * status code is needed for the caller's assertion.
+     *
+     * @param resourceUrl the mTLS-enabled resource endpoint (e.g. {@code https://mtlstb.graph.microsoft.com/...})
+     * @param accessToken the mTLS-bound PoP access token
+     * @param bindingCert the certificate the token is bound to; must expose its private key for the handshake
+     * @return the HTTP status code returned by the resource
+     */
+    static int callResourceWithMtlsToken(String resourceUrl, String accessToken, IClientCertificate bindingCert)
+            throws IOException {
+        SSLSocketFactory socketFactory = MtlsClientCertificateHelper.createMtlsSocketFactory(bindingCert);
+
+        HttpsURLConnection connection = (HttpsURLConnection) new URL(resourceUrl).openConnection();
+        try {
+            connection.setSSLSocketFactory(socketFactory);
+            connection.setRequestMethod("GET");
+            connection.setRequestProperty("Authorization", "mtls_pop " + accessToken);
+            connection.setConnectTimeout(30_000);
+            connection.setReadTimeout(30_000);
+
+            int status = connection.getResponseCode();
+            drainAndClose(status < HttpURLConnection.HTTP_BAD_REQUEST
+                    ? connection.getInputStream() : connection.getErrorStream());
+            return status;
+        } finally {
+            connection.disconnect();
+        }
+    }
+
+    // Reads and discards the response body so the connection can be released cleanly. The external body
+    // is intentionally never logged (it can be large and is not needed for the status-code assertion).
+    private static void drainAndClose(InputStream stream) throws IOException {
+        if (stream == null) {
+            return;
+        }
+        try (InputStream in = stream) {
+            byte[] buffer = new byte[4096];
+            while (in.read(buffer) != -1) {
+                // discard
+            }
+        }
+    }
+}

msal4j-sdk/src/samples/confidential-client/ClientCredentialMtlsProofOfPossession.java

@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 
 import com.microsoft.aad.msal4j.BindingCertificate;
+import com.microsoft.aad.msal4j.ClientCredentialFactory;
 import com.microsoft.aad.msal4j.ClientCredentialParameters;
 import com.microsoft.aad.msal4j.ConfidentialClientApplication;
 import com.microsoft.aad.msal4j.IAuthenticationResult;