Implement mTLS Proof-of-Possession (mTLS PoP) token acquisition

[Robbie-Microsoft]

mTLS Proof of Possession (mTLS PoP)

Implements mTLS Proof of Possession token acquisition for two scenarios, matching MSAL.NET's mTLS PoP implementation:

• Path 1 (Confidential Client / SNI) — acquire an mTLS PoP token using a caller-supplied certificate presented during the TLS handshake to a regional mTLS endpoint
• Path 2 (Managed Identity / IMDSv2) — acquire an mTLS PoP token on an Azure VM using an IMDS-issued binding certificate backed by a VBS KeyGuard-protected CNG key, accessed via JNA — no .NET runtime or subprocess required

---

Path 1 — Confidential Client

New option: ClientCredentialParameters.withMtlsProofOfPossession() on acquireToken.

The caller provides a certificate (PKCS12, PEM, or hardware-backed PKCS11) as the client credential. MSAL builds a custom SSLSocketFactory and presents the certificate during the TLS handshake to the regional mTLS endpoint — no
client_assertion JWT is included in the request body. The token is cached and discriminated by the certificate's x5t#S256 thumbprint so different certificates never share cache entries.

IClientCertificate cert = ClientCredentialFactory.createFromCertificate(
    new FileInputStream("cert.p12"), "password");

ConfidentialClientApplication app = ConfidentialClientApplication
    .builder("client-id", cert)
    .authority("https://login.microsoftonline.com/{tenantId}")
    .azureRegion("eastus")
    .build();

IAuthenticationResult result = app.acquireToken(
    ClientCredentialParameters.builder(Collections.singleton("https://graph.microsoft.com/.default"))
        .withMtlsProofOfPossession()
        .build()
).get();
// result.bindingCertificate()        — the cert bound to the token
// result.metadata().tokenSource()    — Cache on repeat calls

---

Path 2 — Managed Identity (IMDSv2)

New class: MtlsMsiClient in the msal4j-mtls-extensions module.

Fully automated — no certificates or keys to manage. MSAL handles the complete flow via JNA (ncrypt.dll) directly from the JVM:

Step	What happens
1. Platform metadata	GET /metadata/identity/getplatformmetadata → clientId, tenantId, cuId, attestationEndpoint
2. CNG key	NCryptCreatePersistedKey — 3-level fallback: KeyGuard (VBS) → Hardware (Software KSP) → InMemory
3. CSR	Pure-Java PKCS#10 ASN.1 matching MSAL.NET's Csr.Generate(): CN={clientId} DC={tenantId}, RSASSA-PSS SHA-256, CuID OID 1.3.6.1.4.1.311.90.2.10 in attributes [0]
4. Attestation	AttestationClientLib.dll → MAA JWT proving KeyGuard key protection (Trusted Launch VMs only)
5. Credential issuance	POST /metadata/identity/issuecredential → binding cert from managedidentitysnissuer.login.microsoft.com
6. Token	POST {mtlsEndpoint}/{tenantId}/oauth2/v2.0/token — TLS handshake via CngSignatureSpi (key never leaves CNG)

MtlsMsiClient client = new MtlsMsiClient();

MtlsMsiHelperResult result = client.acquireToken(
    "https://graph.microsoft.com",  // resource
    "SystemAssigned",               // identityType
    null,                           // identityId (null = system-assigned)
    true,                           // withAttestation
    null                            // correlationId
);
// result.getAccessToken()          — mtls_pop token
// result.getBindingCertificate()   — IMDS-issued cert; thumbprint matches cnf.x5t#S256
// Second call → cert cache hit, then token cache hit

---

Caching

	Path 1	Path 2
Token cache key	token_type=mtls_pop + cert x5t#S256	token_type=mtls_pop + cert x5t#S256
Cert cache	N/A — caller manages	In-memory, 5-min pre-expiry buffer
CNG key	N/A	Persisted as MSALMtlsKey_{cuId} (Software KSP, USER scope)

---

Requirements

	Path 1	Path 2
Platform	Any	Windows only (CNG + VBS via JNA)
Azure	App registration with cert	Azure VM with Managed Identity
VM	—	Trusted Launch + Credential Guard active
Runtime	Java 8+	Java 8+ — no .NET required

Note

https://management.azure.com may return AADSTS392196 (resource not enrolled for mTLS PoP). Use https://graph.microsoft.com for testing.

---

Verified on

Important

Tested on MSIV2 (CentralUSEUAP, System-Assigned MI, Trusted Launch, Credential Guard active) — VBS KeyGuard-protected RSA-2048 — resource: https://graph.microsoft.com

Call 1 — TokenSource: Network
  cnf.x5t#S256:    URKoHPhqkKqHrMgVv17th-aLTmHaYF2IMaodLpLFnjM
  xms_tbflags:     2
  appidacr:        "2"
  app_displayname: MSIV2
  aud:             https://graph.microsoft.com

Call 2 — TokenSource: Cache ✅

---

Documentation

Doc	Description
📄 msal4j-sdk/docs/mtls-pop.md	API reference, cross-SDK comparison table, caching, error table
📄 msal4j-sdk/docs/mtls-pop-architecture.md	Deep-dive: JNA→CNG interop, CngSignatureSpi design, 3-level key fallback, AttestationClientLib.dll usage, pure-Java PKCS#10 ASN.1, cert cache, cross-SDK architecture comparison
📄 msal4j-sdk/docs/mtls-pop-manual-testing.md	Step-by-step manual testing guide: VM setup, expected output, JWT verification, failure scenarios
🧪 Path1ConfidentialClient.java	Path 1 e2e test driver (4 error cases + happy path; --errors-only works with zero setup)
🧪 Path2ManagedIdentity.java	Path 2 e2e test driver
🧪 E2ETestRunner.java	Fat JAR dispatcher — java -jar mtls-extensions.jar path1|path2 [--errors-only]

[Avery-Dunn]

Minor issue, but 5 minutes seems tight.

Unless this is for something else, .NET seems to have a 24 hour lifetime (but that might be too much) and stores it in the CurrentUser\My keystore (which might not be needed): https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/main/src/client/Microsoft.Identity.Client/ManagedIdentity/V2/WindowsPersistentCertificateCache.cs#L13

[Avery-Dunn]

Is this doc still needed/up-to-date? Here you say that the subprocess process is the only viable approach and some method comments still say that, but newer versions of the docs/code seem to focus on a JNI/JNA approach: https://github.com/AzureAD/microsoft-authentication-library-for-java/pull/1021/changes#diff-b33fca40515fa2d8afea3213b775ae51d79c59a5e5cecd40677934d77478d9daR3