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

.github/copilot-instructions.md

@@ -25,6 +25,7 @@
 - Acquire access tokens for protected APIs (Microsoft Graph, custom APIs)
 - Token caching and automatic refresh
 - Support for various authentication flows (interactive, silent, client credentials, on-behalf-of, device code, managed identity)
+- mTLS Proof-of-Possession (PoP) tokens for confidential clients using an SN/I certificate (see Client Credentials)
 - Multi-cloud and B2C support
 
 ### Repository Structure
@@ -137,6 +138,8 @@ MSAL4J supports multiple authentication flows, each with a public `*Parameters`
 - **Parameters**: `ClientCredentialParameters` - App-only authentication (daemon apps)
 - **Internal**: `ClientCredentialRequest` → `AcquireTokenByClientCredentialSupplier`
 - **Key Classes**: `IClientCredential`, `ClientSecret`, `ClientCertificate`, `ClientAssertion`
+- **mTLS Proof-of-Possession (PoP)**: Opt in with `ClientCredentialParameters.builder(...).mtlsProofOfPossession()` to obtain an mTLS-bound PoP token (`token_type=mtls_pop`). The app's SN/I `IClientCertificate` is presented as the client TLS certificate to a rewritten `mtlsauth.*` endpoint (no `client_assertion` on the direct path) instead of signing an x5c assertion (the existing SNI+Bearer path is unchanged). Requires a tenanted authority and an ESTS allow-listed resource; region is optional (global `mtlsauth.microsoft.com` when absent). The result exposes `metadata().tokenType()` and `metadata().bindingCertificate()` (public material only — x5c chain + `x5t#S256`).
+  - **Key Classes**: `TokenType`, `BindingCertificate`, `MtlsClientCertificateHelper`, `MtlsEndpointHelper`; internal `AuthScheme`. Not supported: US Gov / China clouds, and user-scoped (`user_fic`) FIC over mTLS.
 
 **On-Behalf-Of (OBO)**
 - **Public API**: `acquireToken(OnBehalfOfParameters)`

build/credscan-exclude.json

@@ -1,5 +1,9 @@
 {
   "tool": "Credential Scanner",
   "suppressions": [
+    {
+      "file": "msal4j-sdk/src/test/resources/mtls_test_cert.p12",
+      "_justification": "Self-signed, test-only certificate (CN=msal4j-mtls-test) used by unit tests for mTLS Proof-of-Possession. Contains no production secret."
+    }
   ]
-}
+}

changelog.txt

@@ -1,5 +1,6 @@
 Version 1.25.0
 =============
+- Add SN/I certificate support over mTLS Proof-of-Possession (PoP) for confidential clients, presenting the certificate as the client TLS cert to obtain an mTLS-bound token
 - Add Federated Managed Identity (FMI) support for client credentials flow (#1025)
 - Add User Federated Identity Credential (user_fic) grant type support (#1026)
 - Add MSAL client metadata headers to IMDS managed identity requests (#1024)

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

@@ -0,0 +1,188 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.aad.msal4j;
+
+import com.microsoft.aad.msal4j.labapi.KeyVaultSecretsProvider;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestInstance;
+
+import java.io.IOException;
+import java.security.KeyStore;
+import java.security.KeyStoreException;
+import java.security.NoSuchAlgorithmException;
+import java.security.NoSuchProviderException;
+import java.security.PrivateKey;
+import java.security.UnrecoverableKeyException;
+import java.security.cert.CertificateException;
+import java.security.cert.X509Certificate;
+import java.util.Collections;
+
+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;
+
+/**
+ * End-to-end integration tests for SN/I certificate over mTLS Proof-of-Possession (PoP).
+ *
+ * <p>These exercise the primary deliverable of this work: a confidential-client app configured with a
+ * Subject-Name/Issuer (SN/I) certificate obtains an <b>mTLS-bound PoP access token</b> from Entra ID
+ * (ESTS), where that same SNI cert is presented as the client TLS certificate in the mutual-TLS
+ * handshake to the token endpoint (no {@code private_key_jwt} / x5c client assertion on the direct
+ * path).
+ *
+ * <p>The primary scenario is covered:
+ * <ul>
+ *   <li><b>Direct SNI cert &rarr; mTLS PoP</b> (client credentials), global and regional endpoints.</li>
+ * </ul>
+ *
+ * <p><b>Testability gate (SME note A):</b> ESTS gates mTLS PoP on the <i>final resource audience</i>,
+ * which must be an ESTS allow-listed resource (e.g. Azure Key Vault or MS Graph) — not the client app.
+ * Every test below therefore requests a token for an allow-listed resource.
+ *
+ * <p>The lab SN/I certificate is <b>non-CNG</b>, so these tests are E2E-runnable in CI/CD using the same
+ * certificate the pipelines already provision for {@code ClientCredentialsIT} and {@code AgenticIT} (the
+ * OS keystore alias {@link KeyVaultSecretsProvider#CERTIFICATE_ALIAS}). They require lab credentials and
+ * network access and only pass in CI (like the other {@code *IT} tests, they are not run by the unit-test
+ * surefire pass).
+ *
+ * <p><b>App/tenant requirement:</b> ESTS only issues mTLS PoP tokens for the SN/I-allow-listed app in the
+ * MSI team tenant. This mirrors MSAL .NET's {@code ClientCredentialsMtlsPopTests}: any other app (e.g. the
+ * general {@code LabVaultAppID}) is rejected with {@code AADSTS700025: Client is public...}. The lab cert
+ * ({@link KeyVaultSecretsProvider#CERTIFICATE_ALIAS}) is registered for SN/I on this app.
+ */
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+class MtlsPopIT {
+
+    // SN/I-allow-listed app and MSI team tenant. mTLS PoP only works on this app/tenant pair; mirrors
+    // MSAL .NET's ClientCredentialsMtlsPopTests. App and tenant IDs are public identifiers, not secrets.
+    private static final String SNI_ALLOWLISTED_APP_ID = "163ffef9-a313-45b4-ab2f-c7e2f5e0e23e";
+    private static final String SNI_ALLOWLISTED_AUTHORITY =
+            "https://login.microsoftonline.com/bea21ebe-8b64-4d06-9f6d-6a889b120a7c";
+    private static final String TEST_SLICE_REGION = "westus3";
+
+    private PrivateKey privateKey;
+    private X509Certificate publicCertificate;
+    private IClientCertificate certificate;
+
+    @BeforeAll
+    void init() throws KeyStoreException, NoSuchProviderException, IOException,
+            NoSuchAlgorithmException, CertificateException, UnrecoverableKeyException {
+        KeyStore keystore = CertificateHelper.createKeyStore();
+        keystore.load(null, null);
+
+        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.");
+
+        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.
+     */
+    @Test
+    void acquireTokenClientCredentials_Certificate_MtlsPop() throws Exception {
+        ConfidentialClientApplication cca = ConfidentialClientApplication.builder(SNI_ALLOWLISTED_APP_ID, certificate)
+                .authority(SNI_ALLOWLISTED_AUTHORITY)   // tenanted authority (required for mTLS PoP)
+                .build();
+
+        IAuthenticationResult result = cca.acquireToken(ClientCredentialParameters
+                        .builder(Collections.singleton(KEYVAULT_DEFAULT_SCOPE))
+                        .mtlsProofOfPossession()
+                        .build())
+                .get();
+
+        assertMtlsPopResult(result, expectedLabThumbprint());
+    }
+
+    /**
+     * 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.
+     */
+    @Test
+    void acquireTokenClientCredentials_Certificate_MtlsPop_Regional() throws Exception {
+        ConfidentialClientApplication cca = ConfidentialClientApplication.builder(SNI_ALLOWLISTED_APP_ID, certificate)
+                .authority(SNI_ALLOWLISTED_AUTHORITY)
+                .azureRegion(TEST_SLICE_REGION)
+                .build();
+
+        IAuthenticationResult result = cca.acquireToken(ClientCredentialParameters
+                        .builder(Collections.singleton(KEYVAULT_DEFAULT_SCOPE))
+                        .mtlsProofOfPossession()
+                        .build())
+                .get();
+
+        assertMtlsPopResult(result, expectedLabThumbprint());
+
+        // The mTLS-PoP token must be cached under {token_type + cert KeyId} and returned on lookup.
+        IAuthenticationResult cached = cca.acquireToken(ClientCredentialParameters
+                        .builder(Collections.singleton(KEYVAULT_DEFAULT_SCOPE))
+                        .mtlsProofOfPossession()
+                        .build())
+                .get();
+
+        assertEquals(result.accessToken(), cached.accessToken(),
+                "Second mTLS-PoP request should return the cached bound token");
+    }
+
+    /**
+     * Requesting a Bearer token and an mTLS-PoP token for the same scope on the same app must yield two
+     * distinct tokens (cache isolation on {token_type + cert KeyId}), confirming the PoP path never
+     * aliases the existing SNI+Bearer path.
+     */
+    @Test
+    void acquireTokenClientCredentials_BearerAndMtlsPop_AreCacheIsolated() throws Exception {
+        ConfidentialClientApplication cca = ConfidentialClientApplication.builder(SNI_ALLOWLISTED_APP_ID, certificate)
+                .authority(SNI_ALLOWLISTED_AUTHORITY)
+                .build();
+
+        // Existing SNI + Bearer path (unchanged).
+        IAuthenticationResult bearer = cca.acquireToken(ClientCredentialParameters
+                        .builder(Collections.singleton(KEYVAULT_DEFAULT_SCOPE))
+                        .build())
+                .get();
+        assertEquals(TokenType.BEARER, bearer.metadata().tokenType());
+
+        // New SNI + mTLS PoP path.
+        IAuthenticationResult pop = cca.acquireToken(ClientCredentialParameters
+                        .builder(Collections.singleton(KEYVAULT_DEFAULT_SCOPE))
+                        .mtlsProofOfPossession()
+                        .build())
+                .get();
+        assertEquals(TokenType.MTLS_POP, pop.metadata().tokenType());
+
+        assertNotEquals(bearer.accessToken(), pop.accessToken(),
+                "Bearer and mTLS-PoP tokens for the same scope must be distinct cache entries");
+        assertEquals(2, cca.tokenCache.accessTokens.size(),
+                "Bearer and mTLS-PoP tokens must occupy separate cache entries");
+    }
+
+    private void assertMtlsPopResult(IAuthenticationResult result, String expectedThumbprint) {
+        assertNotNull(result, "Auth result should not be null");
+        assertNotNull(result.accessToken(), "Access token should not be null");
+        assertFalse(result.accessToken().isEmpty(), "Access token should not be empty");
+        assertEquals(TokenType.MTLS_POP, result.metadata().tokenType(),
+                "Result token type should be MTLS_POP");
+
+        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)");
+    }
+
+    private String expectedLabThumbprint() {
+        return MtlsClientCertificateHelper.computeThumbprintSha256(publicCertificate);
+    }
+}

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AcquireTokenByClientCredentialSupplier.java

@@ -19,6 +19,16 @@ class AcquireTokenByClientCredentialSupplier extends AuthenticationResultSupplie
 
     @Override
     AuthenticationResult execute() throws Exception {
+        // For mTLS Proof-of-Possession, isolate the access token in the cache by the binding certificate's
+        // KeyId (x5t#S256) in addition to the token_type dimension, so PoP tokens bound to different
+        // certificates never alias. Stamped before the cache lookup so reads and writes hash identically.
+        if (clientCredentialRequest.parameters.mtlsProofOfPossession()) {
+            IClientCertificate bindingCertificate = MtlsClientCertificateHelper.resolveBindingCertificate(
+                    (ConfidentialClientApplication) this.clientApplication, clientCredentialRequest.parameters);
+            clientCredentialRequest.parameters.bindingCertificateKeyId(
+                    MtlsClientCertificateHelper.computeCertificateKeyId(bindingCertificate));
+        }
+
         if (clientCredentialRequest.parameters.skipCache() != null &&
                 !clientCredentialRequest.parameters.skipCache()) {
             LOG.debug("SkipCache set to false. Attempting cache lookup");

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AuthenticationErrorCode.java

@@ -161,6 +161,13 @@ public class AuthenticationErrorCode {
 
     public static final String INVALID_TIMESTAMP_FORMAT = "invalid_timestamp_format";
 
+    /**
+     * Indicates an error while configuring or performing an mTLS Proof-of-Possession request, such as a
+     * missing binding certificate, a non-tenanted authority, or an unsupported cloud. For more details,
+     * see https://aka.ms/msal4j-pop
+     */
+    public static final String MTLS_POP_ERROR = "mtls_pop_error";
+
     /**
      * Indicates that instance discovery failed because the authority is not a valid instance.
      * This is returned by the instance discovery endpoint when the provided authority host is unknown.

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AuthenticationResultMetadata.java

@@ -25,10 +25,28 @@ public class AuthenticationResultMetadata implements Serializable {
      */
     private CacheRefreshReason cacheRefreshReason = CacheRefreshReason.NOT_APPLICABLE;
 
+    /**
+     * The type of the access token in the {@link AuthenticationResult}, see {@link TokenType} for possible
+     * values. Defaults to {@link TokenType#BEARER}.
+     */
+    private TokenType tokenType = TokenType.BEARER;
+
+    /**
+     * For {@link TokenType#MTLS_POP} results, the certificate the token is bound to (public material only).
+     * Null for Bearer results.
+     */
+    private BindingCertificate bindingCertificate;
+
     AuthenticationResultMetadata(TokenSource tokenSource, Long refreshOn, CacheRefreshReason cacheRefreshReason) {
+        this(tokenSource, refreshOn, cacheRefreshReason, TokenType.BEARER, null);
+    }
+
+    AuthenticationResultMetadata(TokenSource tokenSource, Long refreshOn, CacheRefreshReason cacheRefreshReason, TokenType tokenType, BindingCertificate bindingCertificate) {
         this.tokenSource = tokenSource;
         this.refreshOn = refreshOn;
         this.cacheRefreshReason = cacheRefreshReason == null ? CacheRefreshReason.NOT_APPLICABLE : cacheRefreshReason;
+        this.tokenType = tokenType == null ? TokenType.BEARER : tokenType;
+        this.bindingCertificate = bindingCertificate;
     }
 
     public static AuthenticationResultMetadataBuilder builder() {
@@ -47,6 +65,22 @@ public CacheRefreshReason cacheRefreshReason() {
         return this.cacheRefreshReason;
     }
 
+    /**
+     * @return the {@link TokenType} of the access token (e.g. {@link TokenType#BEARER} or
+     * {@link TokenType#MTLS_POP}). Never null.
+     */
+    public TokenType tokenType() {
+        return this.tokenType;
+    }
+
+    /**
+     * @return for {@link TokenType#MTLS_POP} results, the {@link BindingCertificate} (x5c chain +
+     * SHA-256 thumbprint, public material only) the token is bound to; null for Bearer results.
+     */
+    public BindingCertificate bindingCertificate() {
+        return this.bindingCertificate;
+    }
+
     void tokenSource(TokenSource tokenSource) {
         this.tokenSource = tokenSource;
     }
@@ -59,10 +93,20 @@ void cacheRefreshReason(CacheRefreshReason cacheRefreshReason) {
         this.cacheRefreshReason = cacheRefreshReason;
     }
 
+    void tokenType(TokenType tokenType) {
+        this.tokenType = tokenType == null ? TokenType.BEARER : tokenType;
+    }
+
+    void bindingCertificate(BindingCertificate bindingCertificate) {
+        this.bindingCertificate = bindingCertificate;
+    }
+
     public static class AuthenticationResultMetadataBuilder {
         private TokenSource tokenSource;
         private Long refreshOn;
         private CacheRefreshReason cacheRefreshReason;
+        private TokenType tokenType = TokenType.BEARER;
+        private BindingCertificate bindingCertificate;
 
         AuthenticationResultMetadataBuilder() {
         }
@@ -82,12 +126,22 @@ public AuthenticationResultMetadataBuilder cacheRefreshReason(CacheRefreshReason
             return this;
         }
 
+        public AuthenticationResultMetadataBuilder tokenType(TokenType tokenType) {
+            this.tokenType = tokenType;
+            return this;
+        }
+
+        public AuthenticationResultMetadataBuilder bindingCertificate(BindingCertificate bindingCertificate) {
+            this.bindingCertificate = bindingCertificate;
+            return this;
+        }
+
         public AuthenticationResultMetadata build() {
-            return new AuthenticationResultMetadata(this.tokenSource, this.refreshOn, cacheRefreshReason);
+            return new AuthenticationResultMetadata(this.tokenSource, this.refreshOn, cacheRefreshReason, tokenType, bindingCertificate);
         }
 
         public String toString() {
-            return "AuthenticationResultMetadata.AuthenticationResultMetadataBuilder(tokenSource=" + this.tokenSource + ", refreshOn=" + this.refreshOn + ", cacheRefreshReason$value=" + this.cacheRefreshReason + ")";
+            return "AuthenticationResultMetadata.AuthenticationResultMetadataBuilder(tokenSource=" + this.tokenSource + ", refreshOn=" + this.refreshOn + ", cacheRefreshReason$value=" + this.cacheRefreshReason + ", tokenType=" + this.tokenType + ", bindingCertificate=" + this.bindingCertificate + ")";
         }
     }
 }