Update mTLS docs: JNA implementation, correct resource, fix links

Robbie-Microsoft · Copilot · Robbie-Microsoft · commit a7cb5bd78a89 · 2026-04-10T16:08:27.000Z
- msal4j-sdk/docs/mtls-pop.md:
  - Path 2: replace subprocess/.NET description with JNA/CNG description
  - Remove 'Why Java Cannot Use CNG' section (no longer true)
  - Remove .NET 8 runtime from requirements
  - Update ManagedIdentityParameters API table description

- msal4j-sdk/docs/mtls-pop-manual-testing.md:
  - Path 2: remove .NET helper exe smoke-test, .NET runtime prereq
  - Replace with fat JAR e2e runner (path2 --attest)
  - Show expected output including JWT claims and downstream 401
  - Change resource from management.azure.com to graph.microsoft.com
  - Add resource enrollment note (AADSTS392196)
  - Update troubleshooting table

- msal4j-mtls-extensions/README.md:
  - Fix broken quick links (docs are in msal4j-sdk/docs/, not here)
  - Change resource examples from management.azure.com to graph.microsoft.com
  - Add resource enrollment note
  - Add Path 1 (Confidential Client) quick start section
  - Add e2e test driver section with path1/path2 commands

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/msal4j-mtls-extensions/README.md b/msal4j-mtls-extensions/README.md
@@ -6,8 +6,8 @@ The latest code resides in the `dev` branch.
 
 Quick links:
 
-| [Docs](docs/mtls-pop.md) | [Manual Testing](docs/mtls-pop-manual-testing.md) | [Architecture](docs/mtls-pop-architecture.md) | [Support](README.md#community-help-and-support) |
-| --- | --- | --- | --- |
+| [Docs](../../msal4j-sdk/docs/mtls-pop.md) | [Manual Testing](../../msal4j-sdk/docs/mtls-pop-manual-testing.md) | [Support](README.md#community-help-and-support) |
+| --- | --- | --- |
 
 ## Installation
 
@@ -50,7 +50,7 @@ Unlike msal-dotnet, which receives this DLL automatically via NuGet, Java applic
 
 Before using this extension, ensure Managed Identity is enabled on your Azure VM.
 
-### Acquiring an mTLS PoP Token
+### Path 2 — Managed Identity: Acquiring an mTLS PoP Token
 
 Acquiring a token follows this general pattern:
 
@@ -63,7 +63,7 @@ Acquiring a token follows this general pattern:
 
      MtlsMsiClient client = new MtlsMsiClient();
      MtlsMsiHelperResult result = client.acquireToken(
-         "https://management.azure.com",   // resource
+         "https://graph.microsoft.com",    // resource (confirmed enrolled for mTLS PoP)
          "SystemAssigned",                  // identity type
          null,                              // identity id (null for system-assigned)
          false,                             // withAttestation — set true on Trusted Launch VMs
@@ -76,7 +76,7 @@ Acquiring a token follows this general pattern:
 
      ```java
      MtlsMsiHelperResult result = client.acquireToken(
-         "https://management.azure.com",
+         "https://graph.microsoft.com",
          "UserAssigned",
          "your-client-id",
          false,
@@ -85,9 +85,11 @@ Acquiring a token follows this general pattern:
      String accessToken = result.getAccessToken();
      ```
 
+   > **Resource note:** Use `https://graph.microsoft.com` or `https://storage.azure.com`. `https://management.azure.com` may return `AADSTS392196` if that resource is not enrolled for mTLS PoP in your tenant.
+
 2. The binding certificate is cached in-process for the lifetime of the IMDS-issued certificate (minus a 5-minute safety margin). Subsequent calls return the cached token until it nears expiry.
 
-### Making Downstream mTLS Calls
+### Path 2 — Making Downstream mTLS Calls
 
 Once you have a token, use `httpRequest()` to make downstream calls over the same KeyGuard-backed mTLS channel:
 
@@ -99,7 +101,7 @@ MtlsMsiHttpResponse response = client.httpRequest(
     null,                                  // body
     null,                                  // contentType
     null,                                  // extra headers
-    "https://management.azure.com",        // resource (for cert refresh)
+    "https://graph.microsoft.com",         // resource (for cert refresh)
     "SystemAssigned", null,                // identity type, identity id
     false,                                 // withAttestation
     null,                                  // correlationId
@@ -109,7 +111,65 @@ System.out.println(response.getStatus()); // e.g. 200
 System.out.println(response.getBody());
 ```
 
-The downstream server must be configured to *require* mutual TLS — it must send a TLS `CertificateRequest` during the handshake. Public Azure APIs (Graph, Key Vault, etc.) do not require a client certificate.
+The downstream server must be configured to *require* mutual TLS — it must send a TLS `CertificateRequest` during the handshake.
+
+### Path 1 — Confidential Client (SNI Certificate)
+
+For applications with an SNI certificate (e.g., from OneCert/DSMS), use `ConfidentialClientApplication` from the core `msal4j` library:
+
+```java
+import com.microsoft.aad.msal4j.*;
+import java.io.FileInputStream;
+
+// 1. Load your certificate (PKCS12)
+IClientCertificate cert = ClientCredentialFactory.createFromCertificate(
+    new FileInputStream("cert.p12"), "password");
+
+// 2. Build the app — tenanted authority and region required
+ConfidentialClientApplication app = ConfidentialClientApplication
+    .builder("your-client-id", cert)
+    .authority("https://login.microsoftonline.com/your-tenant-id")
+    .azureRegion("centraluseuap")
+    .build();
+
+// 3. Acquire an mTLS PoP token
+IAuthenticationResult result = app.acquireToken(
+    ClientCredentialParameters
+        .builder(Collections.singleton("https://graph.microsoft.com/.default"))
+        .withMtlsProofOfPossession()
+        .build()
+).get();
+
+System.out.println("Token type:    " + result.tokenType());       // "mtls_pop"
+System.out.println("Binding cert:  " + result.bindingCertificate().getSubjectX500Principal());
+System.out.println("Access token:  " + result.accessToken());
+```
+
+**Requirements:** Certificate credential, tenanted authority (not `/common` or `/organizations`), Azure region.
+
+---
+
+## End-to-End Test Driver
+
+The `msal4j-mtls-extensions` module ships an e2e fat JAR for manual testing:
+
+```powershell
+# Build
+mvn package -DskipTests
+
+# Path 1 — error-case validation (no Azure credentials required)
+java -jar target\msal4j-mtls-extensions-1.0.0-e2e.jar path1 --errors-only
+
+# Path 1 — full happy path
+java -jar target\msal4j-mtls-extensions-1.0.0-e2e.jar path1 `
+    --tenant <tenantID> --client <clientID> --region centraluseuap
+
+# Path 2 — Managed Identity (with attestation)
+java -Djava.library.path=C:\msiv2 `
+    -jar target\msal4j-mtls-extensions-1.0.0-e2e.jar path2 --attest
+```
+
+See [Manual Testing Guide](../../msal4j-sdk/docs/mtls-pop-manual-testing.md) for full instructions.
 
 ## Community Help and Support
 
diff --git a/msal4j-sdk/docs/mtls-pop-manual-testing.md b/msal4j-sdk/docs/mtls-pop-manual-testing.md
@@ -10,8 +10,9 @@ This guide walks through manual verification of both mTLS PoP paths in MSAL4J.
 - For SNI path: a valid test certificate (PKCS12)
 - For Managed Identity path:
   - An Azure VM with managed identity enabled
+  - Windows x64 OS with VBS (Virtualization-Based Security) KeyGuard
   - `msal4j-mtls-extensions` on classpath (add dependency)
-  - .NET 8 runtime installed on the VM
+  - On Trusted Launch VMs: `AttestationClientLib.dll` on `PATH`
 - An AAD tenant with a registered app (client credentials configured)
 
 ---
@@ -145,119 +146,120 @@ Decode the access token (base64url decode the middle JWT segment) and verify:
 ### Prerequisites
 
 - Azure VM with managed identity enabled (System-assigned or User-assigned)
-- `msal4j-mtls-extensions` JAR on classpath
-- .NET 8 runtime: `dotnet --version` should print `8.x.x`
-- IMDS accessible: `curl http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=...`
+- Windows x64 OS with VBS (Virtualization-Based Security) KeyGuard
+- `msal4j-mtls-extensions` JAR on classpath (or use the pre-built fat JAR)
+- On Trusted Launch VMs: `AttestationClientLib.dll` on `PATH` or application directory
+- No .NET runtime required — the extension calls CNG directly via JNA
 
-### 1. Smoke-test the .NET helper binary
-
-Locate the helper (bundled in the `msal4j-mtls-extensions` JAR or at `MSAL_MTLS_HELPER_PATH`):
+### 1. Build the e2e fat JAR
 
 ```bash
-# If using env override:
-export MSAL_MTLS_HELPER_PATH=/path/to/MsalMtlsMsiHelper.exe
-
-# Smoke test - acquire token for ARM resource
-./MsalMtlsMsiHelper.exe \
-  --mode acquire-token \
-  --resource https://management.azure.com/ \
-  --identity-type SystemAssigned
+cd msal4j-mtls-extensions
+mvn package -DskipTests
+# Produces: target/msal4j-mtls-extensions-1.0.0-e2e.jar
 ```
 
-Expected stdout (JSON):
-```json
-{
-  "access_token": "eyJ0...",
-  "token_type": "mtls_pop",
-  "expires_on": 1234567890,
-  "thumbprint": "abc123..."
-}
-```
-
-### 2. Java test program
-
-```java
-import com.microsoft.aad.msal4j.*;
-import java.util.*;
-
-public class TestMtlsMsi {
-    public static void main(String[] args) throws Exception {
-        ManagedIdentityApplication app = ManagedIdentityApplication
-            .builder(ManagedIdentityId.systemAssigned())
-            .build();
+### 2. Run Path 2 (Managed Identity)
 
-        ManagedIdentityParameters params = ManagedIdentityParameters
-            .builder("https://management.azure.com/")
-            .withMtlsProofOfPossession(true)
-            .build();
-
-        IAuthenticationResult result = app.acquireTokenForManagedIdentity(params).get();
+```powershell
+# Basic (no attestation — works on standard VMs)
+java -jar target\msal4j-mtls-extensions-1.0.0-e2e.jar path2
 
-        System.out.println("=== SUCCESS ===");
-        System.out.println("Token type: " + result.tokenType());
-        System.out.println("Expires:    " + result.expiresOnDate());
-        System.out.println("Token:      " + result.accessToken().substring(0, 40) + "...");
-    }
-}
+# With attestation (Trusted Launch VMs with AttestationClientLib.dll)
+java -Djava.library.path=C:\msiv2 -jar target\msal4j-mtls-extensions-1.0.0-e2e.jar path2 --attest
 ```
 
-### 3. With attestation
+### 3. Expected output
 
-```java
-ManagedIdentityParameters params = ManagedIdentityParameters
-    .builder("https://management.azure.com/")
-    .withMtlsProofOfPossession(true)
-    .withAttestation(true)
-    .build();
+```
+=== Path 2: Managed Identity mTLS PoP ===
+
+Acquiring mTLS PoP token via IMDSv2 (full flow)...
+
+[First call (from IMDS)]
+  ✅ BindingCertificate present
+     Subject:   CN=<client-id>,DC=<tenant-id>
+     Issuer:    CN=managedidentitysnissuer.login.microsoft.com
+     NotBefore: ...
+     NotAfter:  ... (14 days)
+  TokenType:  mtls_pop
+  ExpiresIn:  86399s
+  AccessToken cnf: {"x5t#S256":"<thumbprint>"}
+  ✅ AccessToken present
+
+Acquiring again (expect cert cache hit)...
+[Second call (should be cert-cached, ~fast)]
+  ✅ Binding cert cache working: same cert on second call
+  ⏱  Elapsed: ~60ms
+
+Making downstream mTLS call to graph.microsoft.com...
+  Downstream HTTP status: 401
+  ✅ TLS handshake + token delivery succeeded (HTTP < 500)
+  ℹ️  401 — TLS OK, authorization depends on permissions
+
+=== Path 2 Complete ===
 ```
 
-Attestation requires:
-- Azure VM with vTPM or Trusted Launch enabled
-- MAA (Microsoft Azure Attestation) service accessible from the VM
+> **Expected HTTP 401 from graph.microsoft.com:** This is correct behavior. The TLS handshake and token were accepted — the managed identity simply has no Graph role assigned. HTTP 401 confirms the mTLS PoP flow succeeded end-to-end.
 
-### 4. User-assigned managed identity
+### 4. Java API
 
 ```java
-// By client ID
-ManagedIdentityApplication app = ManagedIdentityApplication
-    .builder(ManagedIdentityId.userAssignedClientId("your-client-id"))
-    .build();
-
-// By object ID  
-ManagedIdentityApplication app2 = ManagedIdentityApplication
-    .builder(ManagedIdentityId.userAssignedObjectId("your-object-id"))
-    .build();
+import com.microsoft.aad.msal4j.mtls.*;
 
-// By resource ID
-ManagedIdentityApplication app3 = ManagedIdentityApplication
-    .builder(ManagedIdentityId.userAssignedResourceId("/subscriptions/.../resourceGroups/.../providers/..."))
-    .build();
+MtlsMsiClient client = new MtlsMsiClient();
+MtlsMsiHelperResult result = client.acquireToken(
+    "https://graph.microsoft.com",   // resource (graph.microsoft.com confirmed enrolled)
+    "SystemAssigned",                 // identity type
+    null,                             // identity id (null for system-assigned)
+    false,                            // withAttestation — set true on Trusted Launch VMs
+    null                              // correlationId (optional)
+);
+
+String accessToken = result.getAccessToken();
+String certPem     = result.getBindingCertificate();
 ```
 
-### 5. End-to-end test: making an mTLS-required HTTP request
+> **Resource note:** Use `https://graph.microsoft.com` or `https://storage.azure.com` for testing.
+> `https://management.azure.com` may return `AADSTS392196` if the resource is not enrolled for mTLS PoP in your tenant.
 
-Use the result from step 2 to make a request to a resource server that enforces mTLS:
+### 5. Verify token claims
 
-```java
-// After acquiring the token, use MtlsMsiClient directly for mTLS-authenticated HTTP calls
-// (this requires msal4j-mtls-extensions on classpath)
-import com.microsoft.aad.msal4j.mtls.MtlsMsiClient;
+Decode the JWT payload and confirm:
 
-MtlsMsiClient client = new MtlsMsiClient();
-// Use the token to call a downstream API via mTLS
-// The helper binary handles the mTLS transport
+```powershell
+$token = "<access-token>"
+$parts = $token -split "\."
+[System.Text.Encoding]::UTF8.GetString(
+    [System.Convert]::FromBase64String(
+        $parts[1].PadRight($parts[1].Length + (4 - $parts[1].Length % 4) % 4, '='))) |
+    ConvertFrom-Json
 ```
 
+Expected claims:
+```json
+{
+  "cnf":            { "x5t#S256": "<thumbprint matching binding cert>" },
+  "xms_tbflags":    2,
+  "appidacr":       "2",
+  "aud":            "https://graph.microsoft.com",
+  "idtyp":          "app",
+  "app_displayname": "<your VM's managed identity name>"
+}
+```
+
+The `cnf.x5t#S256` thumbprint must match the binding certificate returned by `result.getBindingCertificate()`.
+
 ### Troubleshooting
 
 | Symptom | Likely Cause | Fix |
 |---------|-------------|-----|
-| `msal4j-mtls-extensions not on classpath` | Missing dependency | Add `msal4j-mtls-extensions` to pom.xml |
-| Helper not found | No exe or env var not set | Set `MSAL_MTLS_HELPER_PATH` or include extensions JAR |
-| `.NET runtime not found` | .NET 8 not installed | `sudo apt install dotnet-runtime-8.0` or Windows installer |
+| `VBS KeyGuard not available` | Credential Guard not enabled | Enable VBS/Credential Guard and reboot |
+| `AttestationClientLib.dll not found` | DLL not on PATH | Copy DLL from NuGet package to application directory |
+| `HTTP 400 from IMDS issuecredential` | Attestation token empty | Check DLL is present; VM must be Trusted Launch |
+| `AADSTS392196` | Resource not enrolled for mTLS PoP | Use `https://graph.microsoft.com` instead |
 | `IMDS not accessible` | Not running on Azure VM | This path only works in Azure managed identity environments |
-| Helper exits with non-zero | See stderr JSON `error_description` | Check IMDS logs, managed identity config, network rules |
-| Attestation failure | VM doesn't support vTPM | Use `withAttestation(false)` or enable Trusted Launch |
+| `NCryptFinalizeKey NTE_BAD_FLAGS` | VBS not running | Check `msinfo32.exe` → Virtualization-based security must show "Running" |
 
 ---
 
diff --git a/msal4j-sdk/docs/mtls-pop.md b/msal4j-sdk/docs/mtls-pop.md
