Document mTLS PoP usage in MSAL (all pop features are on internal preview) #5584

gladjohn · 2025-11-17T23:46:53Z

Added documentation for using managed identities with mTLS proof-of-possession in MSAL.NET, including code examples and installation instructions.

Copilot

Pull Request Overview

This PR adds comprehensive documentation for using mTLS (mutual TLS) proof-of-possession tokens with managed identities in MSAL.NET. The feature is currently in internal preview and extends the existing managed identity experience by binding tokens to X.509 certificates for enhanced security. The documentation provides clear migration paths from Bearer tokens to mTLS PoP tokens, showing developers how to minimally modify their existing code.

Key Changes:

Added complete guide for mTLS PoP with managed identities including installation instructions for the preview NuGet package
Provided side-by-side code examples comparing Bearer token flow vs. mTLS PoP flow for both system-assigned and user-assigned managed identities
Documented how to use binding certificates with HttpClient for mTLS handshakes when calling APIs like Microsoft Graph

docs/msi_v2/how_to_mtls_pop_with_msi.md

gladjohn · 2025-11-18T00:01:35Z

@copilot can you address all open comments

Copilot · 2025-11-18T00:01:45Z

@gladjohn I've opened a new pull request, #5585, to work on those changes. Once the pull request is ready, I'll request review from you.

gladjohn · 2025-11-18T00:02:43Z

@gladjohn I've opened a new pull request, #5585, to work on those changes. Once the pull request is ready, I'll request review from you.

@copilot why can't you update my PR?

Copilot · 2025-11-18T00:02:52Z

@gladjohn I've opened a new pull request, #5586, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.

docs/msi_v2/how_to_mtls_pop_with_msi.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

docs/msi_v2/how_to_mtls_pop_with_msi.md

Refactor mTLS HttpClient creation and usage for better performance and clarity.

docs/msi_v2/how_to_mtls_pop_with_msi.md

neha-bhargava · 2025-11-20T17:27:25Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+    .ConfigureAwait(false);
+
+// result.TokenType == "mtls_pop"
+// result.BindingCertificate is the client cert to use for mTLS


Suggested change

// result.BindingCertificate is the client cert to use for mTLS

// result.BindingCertificate is the client cert to use for mTLS in step 4

neha-bhargava · 2025-11-20T17:33:26Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+    .ExecuteAsync()
+    .ConfigureAwait(false);
+
+// result.TokenType == "mtls_pop"


Why are these lines commented?

just a comment in the code.

docs/msi_v2/how_to_mtls_pop_with_msi.md

neha-bhargava

Approve with comments

Updated the documentation for using managed identities with mTLS proof-of-possession in MSAL.NET, including changes to titles, descriptions, and code examples.

Co-authored-by: Neha Bhargava <61847233+neha-bhargava@users.noreply.github.com>

bgavrilMS · 2025-11-21T14:23:04Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+ms.date: 11/17/2025
+---
+
+# Use mTLS proof-of-possession (mTLS PoP) tokens in MSAL.NET (internal Microsoft only - preview)


Suggested change

# Use mTLS proof-of-possession (mTLS PoP) tokens in MSAL.NET (internal Microsoft only - preview)

# Use mTLS proof-of-possession (mTLS PoP) tokens in MSAL.NET (preview)

bgavrilMS · 2025-11-21T14:23:23Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+
+## Overview
+
+mTLS PoP builds directly on top of existing MSAL experiences:


This doc is too long. Can we skip this intro and head directly to code snippets?

who is the target audience @bgavrilMS ?

Application developers. My point is that you can be more concise, for example by using a diff code snippet.

some old code + some new code

bgavrilMS · 2025-11-21T14:23:57Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+The following example shows how to use either a user-assigned or system-assigned managed identity.
+
+```csharp
+using System.Threading.Tasks;


Don't include boilerplate

bgavrilMS · 2025-11-21T14:24:41Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+- exposes the `WithMtlsProofOfPossession()` extension for managed identity flows, and
+- brings in a native dependency used to attest managed identity keys (for example KeyGuard keys) via Microsoft Azure Attestation (MAA).
+
+### 1.2 Current experience – Bearer (Graph)


Why include Bearer flow? It's not changed.

bgavrilMS · 2025-11-21T14:25:25Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+using System.Threading.Tasks;
+using Microsoft.Identity.Client;
+
+// Choose the appropriate managed identity:


nit: Just give an example with a user assigned managed identity, this is the recommended way

that will lead to questions about is SAMI supported? SAMI is supported.

bgavrilMS · 2025-11-21T14:26:08Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+        .Build();
+
+// Microsoft Graph as the target API
+const string graphResource = "https://graph.microsoft.com/";


I'd use the scope here, i.e. with .default

I'd also not use a constant string, just set it directly.

this is just an extension of what we published in our MSAL usage docs - https://learn.microsoft.com/en-us/entra/msal/dotnet/advanced/managed-identity

Are you suggesting that we change the pattern? and use default everywhere?

bgavrilMS · 2025-11-21T14:26:23Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+
+AuthenticationResult mtlsPopResult = await mi
+    .AcquireTokenForManagedIdentity(graphResource)
+    .WithMtlsProofOfPossession()   // <-- new API


Suggested change

.WithMtlsProofOfPossession() // <-- new API

.WithMtlsProofOfPossession() // <-- new API from Microsoft.Identity.Client.MtlsPoP package

we started off,

This package: - exposes the `WithMtlsProofOfPossession()` extension for managed identity flows, and - brings in a native dependency used to attest managed identity keys (for example KeyGuard keys) via Microsoft Azure Attestation (MAA).

wouldn't this be redundant?

bgavrilMS · 2025-11-21T14:27:39Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+> For SNI-based confidential clients, mTLS PoP is provided by the MSAL.NET preview package itself.
+> You do **not** need the `Microsoft.Identity.Client.MtlsPop` package for this scenario.
+
+### 2.1 Current experience – Bearer with SN/I certificate


Don't include this

Should we remove ### 2.1 Current experience – Bearer with SN/I certificate

bgavrilMS · 2025-11-21T14:28:00Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+    ConfidentialClientApplicationBuilder
+        .Create(clientId)
+        .WithAuthority($"https://login.microsoftonline.com/{tenantId}")
+        .WithAzureRegion("east us")            // Required for SNI


use a real region

bgavrilMS · 2025-11-21T14:29:32Z

docs/msi_v2/how_to_mtls_pop_with_msi.md

+
+---
+
+## 3. Use mTLS PoP with federated identity credentials (FIC)


You should give examples of:

MSI + FIC
OIDC + FIC

Document mTLS PoP usage with managed identities

1e4087f

Added documentation for using managed identities with mTLS proof-of-possession in MSAL.NET, including code examples and installation instructions.

gladjohn requested a review from a team as a code owner November 17, 2025 23:46

gladjohn requested a review from Copilot November 17, 2025 23:47

Copilot started reviewing on behalf of gladjohn November 17, 2025 23:47 View session

Copilot finished reviewing on behalf of gladjohn November 17, 2025 23:50

Copilot AI reviewed Nov 17, 2025

View reviewed changes

Copilot AI mentioned this pull request Nov 18, 2025

Fix typos and improve documentation clarity in mTLS PoP guide #5585

Closed

1 task

Copilot AI mentioned this pull request Nov 18, 2025

[WIP] Document mTLS PoP usage with managed identities #5586

Closed

Fix typos in mTLS PoP documentation

f291488

gladjohn requested a review from Copilot November 18, 2025 00:05

Copilot started reviewing on behalf of gladjohn November 18, 2025 00:06 View session

Copilot finished reviewing on behalf of gladjohn November 18, 2025 00:09

Copilot AI reviewed Nov 18, 2025

View reviewed changes

Update docs/msi_v2/how_to_mtls_pop_with_msi.md

2294449

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

bgavrilMS reviewed Nov 18, 2025

View reviewed changes

docs/msi_v2/how_to_mtls_pop_with_msi.md Outdated Show resolved Hide resolved

Improve mTLS HttpClient handling and example usage

6d48ff3

Refactor mTLS HttpClient creation and usage for better performance and clarity.

bgavrilMS reviewed Nov 18, 2025

View reviewed changes

docs/msi_v2/how_to_mtls_pop_with_msi.md Outdated Show resolved Hide resolved

neha-bhargava reviewed Nov 20, 2025

View reviewed changes

docs/msi_v2/how_to_mtls_pop_with_msi.md Outdated Show resolved Hide resolved

neha-bhargava approved these changes Nov 20, 2025

View reviewed changes

Revise mTLS PoP documentation for MSAL.NET

dfaeff1

Updated the documentation for using managed identities with mTLS proof-of-possession in MSAL.NET, including changes to titles, descriptions, and code examples.

gladjohn changed the title ~~Document mTLS PoP usage with managed identities~~ Document mTLS PoP usage in MSAL (all pop features are on internal preview) Nov 20, 2025

Update docs/msi_v2/how_to_mtls_pop_with_msi.md

d7a50a5

Co-authored-by: Neha Bhargava <61847233+neha-bhargava@users.noreply.github.com>

bgavrilMS reviewed Nov 21, 2025

View reviewed changes

	// result.BindingCertificate is the client cert to use for mTLS
	// result.BindingCertificate is the client cert to use for mTLS in step 4

	# Use mTLS proof-of-possession (mTLS PoP) tokens in MSAL.NET (internal Microsoft only - preview)
	# Use mTLS proof-of-possession (mTLS PoP) tokens in MSAL.NET (preview)


		## Overview

		mTLS PoP builds directly on top of existing MSAL experiences:

	.WithMtlsProofOfPossession() // <-- new API
	.WithMtlsProofOfPossession() // <-- new API from Microsoft.Identity.Client.MtlsPoP package


		---

		## 3. Use mTLS PoP with federated identity credentials (FIC)

Document mTLS PoP usage in MSAL (all pop features are on internal preview) #5584

Are you sure you want to change the base?

Document mTLS PoP usage in MSAL (all pop features are on internal preview) #5584

Uh oh!

Conversation

gladjohn commented Nov 17, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gladjohn commented Nov 18, 2025

Uh oh!

Copilot AI commented Nov 18, 2025

Uh oh!

gladjohn commented Nov 18, 2025

Uh oh!

Copilot AI commented Nov 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

neha-bhargava left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment