Add Managed Identity v2 KeyGuard mTLS PoP support

[Gladwin Johnson (gladjohn)]

Summary

Adds production-shaped Managed Identity v2 mTLS Proof-of-Possession support for Java using Windows VBS KeyGuard and optional Microsoft Azure Attestation.

Java retains native interop only for KeyGuard/CNG signing and attestation. JCA/JSSE owns TLS, and callers receive a reusable IMtlsBindingContext containing the binding certificate and standard Java SSLContext for independent downstream HTTP calls.

Reviewer entry point: managed-identity-v2-mtls-pop-review-guide.md

Architecture

ManagedIdentityApplication
  -> IMDS v2 platform metadata
  -> KeyGuard non-exportable RSA key
  -> optional MAA attestation
  -> IMDS v2 binding certificate
  -> normal MSAL OAuth token pipeline over JSSE mTLS
  -> mtls_pop token + reusable IMtlsBindingContext

Native signing remains limited to:

JSSE
  -> X509ExtendedKeyManager
  -> CngRsaPrivateKey
  -> CngSignatureSpi
  -> NCryptSignHash
  -> VBS KeyGuard

Changes

• Adds managed-identity mTLS PoP and optional fail-closed attestation APIs.
• Adds binding-aware token caching keyed by token type, full leaf-certificate DER SHA-256 identity, and attestation mode.
• Routes the ESTS mTLS exchange through the normal MSAL token pipeline for claims, client capabilities, telemetry, correlation IDs, retries, error handling, and response parsing.
• Adds a ServiceLoader-based optional Windows extension for CNG, KeyGuard, CSR generation, attestation, certificate rotation, and reusable JSSE binding contexts.
• Bundles Microsoft-signed Microsoft.Azure.Security.KeyGuardAttestation 1.1.5 AttestationClientLib.dll in the optional extension, verifies its SHA-256 before loading, and includes its license and notice.
• Requires exact token_type=mtls_pop and HTTPS token endpoints.
• Uses IMDS-specific retry behavior and validates the IMDS response origin.
• Disables redirects for credential-bound mTLS requests and defines IMtlsCapableHttpClient for custom transports.
• Detects and recreates stale per-boot KeyGuard keys after reboot using a private signing liveness probe.
• Keeps the manual Key Vault E2E application in a separate profile-only module.
• Adds a detailed reviewer guide with architecture and sequence diagrams, security invariants, file review order, test inventory, VM instructions, threat-model checklists, and completion criteria.

Validation

• Full msal4j-sdk and msal4j-mtls-extensions test suites pass.
• Production classes remain Java 8 compatible.
• Production extension and shaded E2E JARs contain the verified native DLL; the production extension excludes the manual E2E app.
• Live validation passed on a Windows Server 2025 Trusted Launch Azure VM without an external DLL or JVM TLS flags:
  • acquired an attested mtls_pop token;
  • returned the binding certificate and reusable JSSE SSLContext;
  • verified JWT cnf.x5t#S256 against SHA-256 of the full leaf certificate DER;
  • independently called a token-binding-enforced Azure Key Vault using HttpsURLConnection and received HTTP 200;
  • reused the same valid token without presenting the binding certificate and received exact HTTP 401 with error code Unauthorized;
  • reacquired through MSAL and received TokenSource.CACHE with the matching live binding context.
• The E2E app also supports token-A/binding-B rejection validation when a second managed identity is supplied.

Security properties

• Private-key bytes are never exported into Java memory.
• TLS is performed by Java JCA/JSSE, not WinHTTP or Schannel as the HTTP stack.
• Attestation failures fail closed when attestation is requested.
• Bearer, certificate-bound, attested, and unattested cache entries cannot cross-hit.
• Same-key certificate renewal creates a new token-cache partition because the full certificate DER changes.
• Credential-bound redirects are disabled.
• Custom HTTP clients fail fast unless they explicitly support the request-specific mTLS socket factory.
• Retired native key handles are cleaned after certificate expiry.

[Copilot]

Pull request overview

Adds optional Windows KeyGuard-backed Managed Identity v2 mTLS PoP support, including core SDK integration, native CNG/attestation extensions, caching, tests, documentation, and manual validation.

Changes:

• Extends token acquisition, HTTP, result, and cache pipelines for mTLS-bound tokens.
• Adds the Windows CNG/KeyGuard provider and IMDS v2 credential flow.
• Adds unit tests, documentation, Maven modules, and an e2e validation app.

Reviewed changes

Copilot reviewed 61 out of 61 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
run-java-msi-v2-mtls-devapp.ps1	Builds and runs manual validation.
README.md	Introduces the mTLS extension.
pom.xml	Registers extension and e2e modules.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/TokenRequestExecutorTest.java	Tests mTLS OAuth request construction.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/ManagedIdentityMtlsProviderLoaderTest.java	Tests missing-provider failure.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/ManagedIdentityMtlsParametersTest.java	Tests parameters, cache partitioning, and token validation.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/ManagedIdentityMtlsBindingTest.java	Tests token endpoint validation.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/DefaultHttpClientMtlsTest.java	Tests redirect prevention.
msal4j-sdk/src/test/java/com/microsoft/aad/msal4j/AuthenticationResultMtlsTest.java	Tests binding serialization and equality.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenResponse.java	Parses OAuth token type.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenRequestExecutor.java	Sends request-specific mTLS token requests.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenCache.java	Supports explicit extended cache hashes.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/OAuthHttpRequest.java	Propagates request socket factories.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalRequest.java	Stores extended cache-key hashes.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalError.java	Defines mTLS error codes.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ManagedIdentityResponse.java	Parses relative expiration values.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ManagedIdentityParameters.java	Adds mTLS and attestation options.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ManagedIdentityMtlsRequest.java	Defines the provider request contract.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ManagedIdentityMtlsProviderLoader.java	Discovers optional providers.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ManagedIdentityMtlsHttpResponse.java	Defines callback HTTP responses.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ManagedIdentityMtlsHttpRequest.java	Defines callback HTTP requests.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ManagedIdentityMtlsBinding.java	Represents validated binding generations.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IMtlsCapableHttpClient.java	Marks mTLS-capable custom clients.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IMtlsBindingContext.java	Exposes process-local JSSE bindings.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IManagedIdentityMtlsProvider.java	Defines the optional provider SPI.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IManagedIdentityMtlsHttpClient.java	Defines the MSAL HTTP callback.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/IAuthenticationResult.java	Exposes token and binding metadata.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/HttpRequest.java	Carries request-specific socket factories.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/DefaultHttpClient.java	Applies mTLS factories and disables redirects.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AuthenticationResult.java	Stores token type and live bindings.
msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AcquireTokenByManagedIdentitySupplier.java	Integrates binding, cache, IMDS, and OAuth flows.
msal4j-sdk/docs/managed-identity-v2-mtls-pop.md	Documents architecture and validation.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/Pkcs10BuilderTest.java	Tests CSR DER generation.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/KeyGuardMtlsBindingContextTest.java	Tests binding key IDs and contexts.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/KeyGuardManagedIdentityMtlsProviderTest.java	Tests certificate rotation timing.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/ImdsV2ClientTest.java	Tests IMDS v2 contracts.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/CngX509ExtendedKeyManagerTest.java	Tests RSA alias selection.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/CngSignatureParametersTest.java	Tests PSS parameter validation.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/CngRsaPrivateKeyTest.java	Tests non-exportability and cleanup.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/CngProviderTest.java	Tests provider registration and delegation.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/CngKeyGuardTest.java	Tests stale native-key deletion.
msal4j-mtls-extensions/src/test/java/com/microsoft/aad/msal4j/mtls/AttestationTokenCacheTest.java	Tests attestation caching and concurrency.
msal4j-mtls-extensions/src/main/resources/META-INF/services/com.microsoft.aad.msal4j.IManagedIdentityMtlsProvider	Registers the KeyGuard provider.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/Pkcs10Builder.java	Builds PKCS#10 CSRs.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/NCryptLibrary.java	Defines Windows NCrypt bindings.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/MtlsMsiException.java	Defines extension failures.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/KeyGuardMtlsBindingContext.java	Creates JSSE binding contexts.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/KeyGuardManagedIdentityMtlsProvider.java	Manages binding creation and rotation.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/ImdsV2Client.java	Implements IMDS v2 requests and parsing.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/CngX509ExtendedKeyManager.java	Supplies KeyGuard credentials to JSSE.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/CngSignatureSpi.java	Implements CNG-backed RSA signing.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/CngRsaPrivateKey.java	Wraps non-exportable CNG keys.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/CngProvider.java	Registers CNG signature services.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/CngKeyGuard.java	Implements KeyGuard and attestation interop.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/AttestationTokenCache.java	Caches fresh attestation JWTs.
msal4j-mtls-extensions/src/main/java/com/microsoft/aad/msal4j/mtls/AttestationLibrary.java	Defines attestation DLL bindings.
msal4j-mtls-extensions/README.md	Documents extension usage.
msal4j-mtls-extensions/pom.xml	Configures the extension artifact.
msal4j-mtls-extensions-e2e/src/main/java/com/microsoft/aad/msal4j/mtls/e2e/ManagedIdentityMtlsPopKeyVaultDevApp.java	Implements manual Key Vault validation.
msal4j-mtls-extensions-e2e/pom.xml	Builds the shaded validation app.
.github/copilot-instructions.md	Documents the new architecture and modules.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.