Add Managed Identity v2 KeyGuard mTLS PoP support

.github/copilot-instructions.md

@@ -28,10 +28,12 @@
 - Multi-cloud and B2C support
 
 ### Repository Structure
-This repository contains three Maven modules:
+This repository contains four default Maven modules plus one profile-only E2E module:
 - **`msal4j-sdk/`** - The main MSAL Java library (focus of development)
 - **`msal4j-brokers/`** - Broker integration for native authentication (Windows WAM)
 - **`msal4j-persistence-extension/`** - Cross-platform token cache persistence helpers
+- **`msal4j-mtls-extensions/`** - Optional Windows KeyGuard/attestation bridge for Managed Identity v2 mTLS PoP; bundles Microsoft.Azure.Security.KeyGuardAttestation 1.1.5 while Java JCA/JSSE performs TLS
+- **`msal4j-mtls-extensions-e2e/`** - Manual validation app, included only by the Maven `e2e` profile
 
 For most work, focus on **`msal4j-sdk/`**.
 
@@ -151,6 +153,8 @@ MSAL4J supports multiple authentication flows, each with a public `*Parameters`
 - **Parameters**: `ManagedIdentityParameters` - For Azure resources (VMs, App Service, Functions)
 - **Internal**: `ManagedIdentityRequest` → `AcquireTokenByManagedIdentitySupplier`
 - **Key Classes**: `ManagedIdentitySource` implementations (`IMDSManagedIdentitySource`, `AppServiceManagedIdentitySource`, etc.)
+- **Optional mTLS**: `withMtlsProofOfPossession()` requests a certificate-bound token; `withRequestOverMtls()` requests an ordinary bearer token over the same KeyGuard-authenticated ESTS channel. The optional `msal4j-key-attestation` artifact supplies `ManagedIdentityAttestationExtensions.withAttestationSupport(builder)` to require MAA attestation and fail closed. Core owns OAuth/HTTP/cache behavior; the optional artifact owns the public attestation opt-in plus KeyGuard/CNG/attestation and returns a reusable process-local `IMtlsBindingContext` for PoP results. Custom HTTP clients must implement `IMtlsCapableHttpClient` and consume the request-specific context or socket factory.
+- **mTLS capability discovery**: `getManagedIdentityCapabilities()` reports the detected source and maximum `MtlsBindingStrength`; `MtlsPopOptions` lets credential chains require a minimum strength before token acquisition succeeds.
 
 ### Common Flows (All Application Types)
 

README.md

@@ -43,6 +43,20 @@ MSAL4J supports multiple [application types and authentication scenarios](https:
 
 Refer the [Wiki](https://github.com/AzureAD/microsoft-authentication-library-for-java/wiki) pages for more details on the usage of MSAL Java and the supported scenarios.
 
+### Managed Identity v2 attested mTLS PoP
+
+The optional `com.microsoft.azure:msal4j-key-attestation` artifact provides a
+Windows KeyGuard-backed, attested Managed Identity v2 flow while preserving
+Java 8 compatibility. MSAL returns an `IMtlsBindingContext` whose standard JSSE
+`SSLContext` can be used by the application for independent downstream mTLS
+calls.
+
+See [the extension guide](msal4j-mtls-extensions/README.md). Reviewers can use
+the [detailed review guide](msal4j-sdk/docs/managed-identity-v2-mtls-pop-review-guide.md)
+for architecture diagrams, security checklists, file order, and manual validation.
+The [DevEx guide](msal4j-sdk/docs/managed-identity-v2-devex.md) shows the
+before/after API and the two supported mTLS request modes.
+
 ## Migrating from ADAL
 If your application is using ADAL for Java (ADAL4J), we recommend you to update to use MSAL4J. No new feature work will be done in ADAL4J.
 

changelog.txt

@@ -1,3 +1,17 @@
+Unreleased
+==========
+- Add Managed Identity v2 KeyGuard mTLS PoP support.
+  - Custom `IHttpClient` implementations must explicitly implement
+    `IMtlsCapableHttpClient`, consume the request-specific `SSLContext` or
+    `SSLSocketFactory`, and disable redirects for credential-bound requests.
+  - Existing custom HTTP clients fail closed until they opt into this contract.
+  - The initial native KeyGuard attestation package supports Windows x64 only.
+  - Credential chains can discover IMDS v2/KeyGuard capability and require a
+    minimum `MtlsBindingStrength` before token acquisition succeeds.
+  - Results expose the actual binding strength with the reusable context.
+  - The native attestation DLL is verified with SHA-256 and Windows
+    Authenticode before it is loaded.
+
 Version 1.26.0
 =============
 - Add Azure Arc user-assigned managed identity support with validation that the requested identity was honored (#1057)

msal4j-mtls-extensions-e2e/.gitignore

@@ -0,0 +1 @@
+target/

msal4j-mtls-extensions-e2e/pom.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.microsoft.azure</groupId>
+    <artifactId>msal4j-mtls-extensions-e2e</artifactId>
+    <version>1.0.0</version>
+    <packaging>jar</packaging>
+
+    <properties>
+        <maven.compiler.source>8</maven.compiler.source>
+        <maven.compiler.target>8</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.microsoft.azure</groupId>
+            <artifactId>msal4j</artifactId>
+            <version>1.26.0</version>
+        </dependency>
+        <dependency>
+            <groupId>com.microsoft.azure</groupId>
+            <artifactId>msal4j-key-attestation</artifactId>
+            <version>1.0.0</version>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.5.1</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals><goal>shade</goal></goals>
+                        <configuration>
+                            <createDependencyReducedPom>false</createDependencyReducedPom>
+                            <shadedArtifactAttached>true</shadedArtifactAttached>
+                            <shadedClassifierName>e2e</shadedClassifierName>
+                            <filters>
+                                <filter>
+                                    <artifact>*:*</artifact>
+                                    <excludes>
+                                        <exclude>META-INF/*.SF</exclude>
+                                        <exclude>META-INF/*.DSA</exclude>
+                                        <exclude>META-INF/*.RSA</exclude>
+                                        <exclude>META-INF/*.EC</exclude>
+                                    </excludes>
+                                </filter>
+                            </filters>
+                            <transformers>
+                                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
+                                    <mainClass>com.microsoft.aad.msal4j.mtls.e2e.ManagedIdentityMtlsPopKeyVaultDevApp</mainClass>
+                                </transformer>
+                            </transformers>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>