Merge branch 'main' into rginsburg/msiv2_feature_branch

Author: Robbie-Microsoft

CHANGELOG.md

@@ -1,3 +1,16 @@
+4.76.0
+======
+
+### New Features
+* Removal of `ExperimentalFeatures` flag on `WithMtlsProofOfPossession` API
+* Add Service Fabric token revocation support
+* Adding WithExtraBodyParameters api
+* Enable mTLS Proof‑of‑Possession for Client‑Assertion Delegates
+
+### Bug Fixes
+* #5400 Fixing issue that leads to multiple active access tokens in the cache for non-tenanted oidc authority 
+* Update NativeInterop package version to 0.19.4 
+
 4.74.1
 ======
 

Directory.Packages.props

@@ -2,7 +2,7 @@
   <PropertyGroup>
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
     <!-- Version of the Microsoft.Identity.Client.NativeInterop package. -->
-    <MSALRuntimeNativeInteropVersion>0.19.2</MSALRuntimeNativeInteropVersion>
+    <MSALRuntimeNativeInteropVersion>0.19.4</MSALRuntimeNativeInteropVersion>
     <!-- Version of MSAL if not defined by the CI-->
     <MsalInternalVersion>4.61.0</MsalInternalVersion>
   </PropertyGroup>

LibsAndSamples.sln

@@ -46,6 +46,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "all", "all", "{C44AADC0-1E9
 		.editorconfig = .editorconfig
 		.gitattributes = .gitattributes
 		.gitignore = .gitignore
+		CHANGELOG.md = CHANGELOG.md
 		build\CodeCoverage.runsettings = build\CodeCoverage.runsettings
 		build\credscan-exclusion.json = build\credscan-exclusion.json
 		Directory.Build.props = Directory.Build.props

build/template-build-and-run-all-tests.yaml

@@ -68,7 +68,7 @@ jobs: #Build and stage projects
   steps:
   - template: template-desktop-unit-and-automation.yaml
 
-  - task: BuildQualityChecks@9
+  - task: BuildQualityChecks@10
     condition: ne(variables['Build.SourceBranch'], 'refs/heads/main') #gate should not run on main branch
     inputs:
       checkCoverage: '$(CodeCoverageGateEnabled)'

docs/msi_v2/msi_with_credential_design.md

@@ -120,7 +120,7 @@ This section outlines the necessary steps to acquire an access token using the M
 
 ### 1. Retrieve Platform Metadata
 
-`GET /metadata/identity/getPlatformMetadata?api-version=2025-05-01&cid={CUID}&uaid={client_id}`
+`GET /metadata/identity/getPlatformMetadata?api-version=2025-05-01&uaid={client_id}`
 
 Response supplies the UAID/client_id, tenant_id, CUID, and (for attestable VMs) the regional MAA endpoint
 

docs/msiv1_token_revocation.md

@@ -125,6 +125,82 @@ The `xms_cc` parameter can hold **multiple** client capabilities, formatted as:
 > [!NOTE]  
 > RPs or MITS should not bypass cache if a bad token is not passed by MSAL. 
 
+#### Cluster-wide cache-bypass optimization (hash-based)
+
+```mermaid
+sequenceDiagram
+    %% cluster-wide cache-bypass (hash-based)
+    autonumber
+    participant NodeA as "Node A (stale token T0)"
+    participant NodeB as "Node B (fresh token T1)"
+    participant MI   as "Managed-Identity endpoint / cache"
+    participant AAD  as "Azure AD"
+
+    Note over NodeA,AAD: Conditional-Access change → claims="{…}"
+
+    NodeA->>MI: GET /token? claims + hash(T0)
+    MI->>MI: cache lookup hash(T0)  (hit - stale)
+    MI->>AAD: request fresh token T1
+    AAD-->>MI: token T1
+    MI->>MI: store hash(T1)\ninvalidate hash(T0)
+    MI-->>NodeA: token T1 (fresh)
+
+    Note over NodeA,NodeB: shortly after …
+
+    NodeB->>MI: GET /token? claims + hash(T1)
+    MI->>MI: cache lookup hash(T1)  (hit - fresh)
+    MI-->>NodeB: token T1 (from cache)
+
+    Note over NodeA,NodeB: **Only one** AAD call for this revoked token
+```
+
+#### Step-by-step flow
+
+1. **Claims challenge arrives** (e.g., CAE / Conditional Access).  
+   `AcquireToken*` receives `claims="{...}"`.
+
+---
+
+##### **Node A** (first node that still holds the stale token)
+
+| Step | Action |
+|------|--------|
+| A-1 | Finds **`access_token_A`** in its local MSAL cache. |
+| A-2 | Computes **`hash_A = sha256(access_token_A)`**. |
+| A-3 | Calls the Managed-Identity (MI) endpoint with<br/>`token_sha256_to_refresh = hash_A`. |
+| A-4 | MI detects `hash_A` in its cache ⇒ marks token revoked, requests a new token **`access_token_B`** from AAD. |
+| A-5 | MI cache now stores `hash_B = sha256(access_token_B) → access_token_B`. |
+
+---
+
+##### **Node B** (arrives moments later)
+
+| Step | Action |
+|------|--------|
+| B-1 | Already has **`access_token_B`** via cache propagation/read-through. |
+| B-2 | Computes **`hash_B = sha256(access_token_B)`**. |
+| B-3 | Sends `token_sha256_to_refresh = hash_B`. |
+| B-4 | MI cache looks up `hash_B` → **hit** (token already fresh). |
+| B-5 | MI returns **HTTP 200** + **`access_token_B`** — _no extra AAD round-trip_. |
+
+---
+
+##### Cluster settles
+
+* **Only one** outbound call to AAD per unique revoked token, no matter how many nodes receive the claims challenge.  
+* Dramatically reduces pressure on the MI proxy and on ESTS in large Service Fabric (or AKS) deployments.
+
+---
+
+##### Why a simple `bypass_cache=true` flag isn’t enough
+
+* `bypass_cache=true` forces **every** node to refresh → scales **O(N)** with cluster size.  
+  Large clusters could issue thousands of token requests within seconds, triggering throttling (`429`) or high latency.
+
+* The **hash check** turns the problem into **O(1)**:  
+  The first node refreshes; the hash acts as an idempotency key so all other nodes immediately reuse the fresh token already in the MI cache.
+
+
 #### Motivation
 
 The *internal protocol* between the client and the RP (i.e. calling the MITS endpoint in case of Service Fabric), is a simplified version of CAE. This is because CAE is claims driven and involves JSON operations such as JSON doc merges. The RP doesn't need the actual claims to perform revocation, it just needs a signal to bypass the cache. As such, it was decided to not use the full claims value internally.

eng/Move-PublicAPI.ps1

@@ -0,0 +1,112 @@
+param(
+    [Parameter(Mandatory = $false)]
+    [string]$Root,
+
+    [switch]$DryRun
+)
+
+<#!
+.SYNOPSIS
+    Moves all APIs from PublicAPI.Unshipped.txt files into the corresponding PublicAPI.Shipped.txt files.
+
+.DESCRIPTION
+    This script scans the repository for files named "PublicAPI.Unshipped.txt" and, for each one found,
+    appends its content to the sibling "PublicAPI.Shipped.txt" file and then clears the unshipped file.
+
+    Run this script every time a release is made to move unshipped API entries to the shipped list.
+
+.PARAMETER Root
+    Optional. The root directory to scan. Defaults to the repository root (one level above the script's folder).
+
+.PARAMETER DryRun
+    Optional. If specified, the script will only report what it would do without making any changes.
+
+.EXAMPLE
+    ./Move-PublicAPI.ps1
+
+.EXAMPLE
+    ./Move-PublicAPI.ps1 -Root C:\g\msal
+
+.EXAMPLE
+    ./Move-PublicAPI.ps1 -DryRun
+#>
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if (-not $PSBoundParameters.ContainsKey('Root') -or [string]::IsNullOrWhiteSpace($Root)) {
+    # Default Root to the repo root (one level above script directory)
+    $Root = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+}
+
+Write-Host "Scanning for PublicAPI.Unshipped.txt under: $Root"
+
+# Find all PublicAPI.Unshipped.txt files
+$unshippedFiles = Get-ChildItem -LiteralPath $Root -Recurse -File -Filter 'PublicAPI.Unshipped.txt' -ErrorAction Stop
+
+if (-not $unshippedFiles -or $unshippedFiles.Count -eq 0) {
+    Write-Host 'No PublicAPI.Unshipped.txt files found. Nothing to do.'
+    return
+}
+
+$updatedCount = 0
+
+foreach ($unshipped in $unshippedFiles) {
+    $unshippedPath = $unshipped.FullName
+    $shippedPath = Join-Path $unshipped.DirectoryName 'PublicAPI.Shipped.txt'
+
+    # Read unshipped content
+    $unshippedContent = Get-Content -LiteralPath $unshippedPath -Raw -ErrorAction Stop
+
+    if ([string]::IsNullOrWhiteSpace($unshippedContent)) {
+        Write-Host "Skipping (empty): $unshippedPath"
+        continue
+    }
+
+    # Ensure shipped file exists
+    if (-not (Test-Path -LiteralPath $shippedPath)) {
+        if ($DryRun) {
+            Write-Host "Would create missing shipped file: $shippedPath"
+        }
+        else {
+            New-Item -ItemType File -Path $shippedPath -Force | Out-Null
+        }
+    }
+
+    # Read existing shipped content if any
+    $existingShipped = ''
+    if (Test-Path -LiteralPath $shippedPath) {
+        $existingShipped = Get-Content -LiteralPath $shippedPath -Raw -ErrorAction Stop
+    }
+
+    # Prepare content to append with reasonable separation
+    $toAppend = $unshippedContent.TrimEnd("`r", "`n")
+
+    if (-not [string]::IsNullOrEmpty($existingShipped)) {
+        # Ensure at least one blank line separation between existing shipped content and new additions
+        $needsTrailingNewLine = -not $existingShipped.EndsWith("`n")
+        $separator = if ($needsTrailingNewLine) { "`r`n`r`n" } else { "`r`n" }
+        $toAppend = $separator + $toAppend + "`r`n"
+    }
+    else {
+        # If shipped is empty, just ensure the appended content ends with a newline
+        $toAppend = $toAppend + "`r`n"
+    }
+
+    if ($DryRun) {
+        $movedLines = ($unshippedContent -split "(`r`n|`n|`r)").Where({ $_ -ne '' }).Count
+        Write-Host "Would move $movedLines line(s) from: $unshippedPath"`n"              to: $shippedPath"
+        continue
+    }
+
+    # Append to shipped and clear unshipped
+    Add-Content -LiteralPath $shippedPath -Value $toAppend -Encoding UTF8
+
+    # Clear the unshipped file (leave file present but empty)
+    Set-Content -LiteralPath $unshippedPath -Value '' -NoNewline -Encoding UTF8
+
+    $updatedCount++
+    Write-Host "Moved content from: $unshippedPath"`n"               to: $shippedPath"
+}
+
+Write-Host "Done. Files updated: $updatedCount"

src/client/Microsoft.Identity.Client/ApiConfig/AcquireTokenForClientParameterBuilder.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
 using System;
@@ -15,6 +15,9 @@
 using Microsoft.Identity.Client.Utils;
 using Microsoft.Identity.Client.Extensibility;
 using Microsoft.Identity.Client.OAuth2;
+using System.Security.Cryptography.X509Certificates;
+using System.Security.Cryptography;
+using System.Text;
 
 namespace Microsoft.Identity.Client
 {
@@ -44,9 +47,9 @@ internal static AcquireTokenForClientParameterBuilder Create(
 
             if (!string.IsNullOrEmpty(confidentialClientApplicationExecutor.ServiceBundle.Config.CertificateIdToAssociateWithToken))
             {
-                builder.WithAdditionalCacheKeyComponents(new SortedList<string, string>
+                builder.WithAdditionalCacheKeyComponents(new SortedList<string, Func<CancellationToken, Task<string>>>
                 {
-                    { Constants.CertSerialNumber, confidentialClientApplicationExecutor.ServiceBundle.Config.CertificateIdToAssociateWithToken }
+                    { Constants.CertSerialNumber, (CancellationToken ct) => { return Task.FromResult(confidentialClientApplicationExecutor.ServiceBundle.Config.CertificateIdToAssociateWithToken); } }
                 });
             }
 
@@ -96,18 +99,20 @@ public AcquireTokenForClientParameterBuilder WithSendX5C(bool withSendX5C)
         /// <returns>The current instance of <see cref="AcquireTokenForClientParameterBuilder"/> to enable method chaining.</returns>
         public AcquireTokenForClientParameterBuilder WithMtlsProofOfPossession()
         {
-            if (ServiceBundle.Config.ClientCredential is not CertificateClientCredential certificateCredential)
+            if (ServiceBundle.Config.ClientCredential is CertificateClientCredential certificateCredential)
             {
-                throw new MsalClientException(
+                if (certificateCredential.Certificate == null)
+                {
+                    throw new MsalClientException(
                     MsalError.MtlsCertificateNotProvided,
                     MsalErrorMessage.MtlsCertificateNotProvidedMessage);
-            }
-            else
-            {
+                }
+
                 CommonParameters.AuthenticationOperation = new MtlsPopAuthenticationOperation(certificateCredential.Certificate);
-                CommonParameters.MtlsCertificate = certificateCredential.Certificate;
+                CommonParameters.MtlsCertificate = certificateCredential.Certificate;               
             }
 
+            CommonParameters.IsMtlsPopRequested = true;
             return this;
         }
 
@@ -141,9 +146,9 @@ public AcquireTokenForClientParameterBuilder WithFmiPath(string pathSuffix)
                 throw new ArgumentNullException(nameof(pathSuffix));
             }
 
-            var cacheKey = new SortedList<string, string>
+            var cacheKey = new SortedList<string, Func<CancellationToken, Task<string>>>
             { 
-                { OAuth2Parameter.FmiPath, pathSuffix } 
+                { OAuth2Parameter.FmiPath, (CancellationToken ct) => {return Task.FromResult(pathSuffix);} } 
             };
 
             this.WithAdditionalCacheKeyComponents(cacheKey);

src/client/Microsoft.Identity.Client/ApiConfig/Executors/ClientApplicationBaseExecutor.cs

@@ -33,7 +33,8 @@ public async Task<AuthenticationResult> ExecuteAsync(
             var requestParameters = await _clientApplicationBase.CreateRequestParametersAsync(
                 commonParameters,
                 requestContext,
-                _clientApplicationBase.UserTokenCacheInternal).ConfigureAwait(false);
+                _clientApplicationBase.UserTokenCacheInternal,
+                cancellationToken).ConfigureAwait(false);
 
             requestParameters.SendX5C = silentParameters.SendX5C ?? false;
 
@@ -59,7 +60,8 @@ public async Task<AuthenticationResult> ExecuteAsync(
             var requestParameters = await _clientApplicationBase.CreateRequestParametersAsync(
                 commonParameters,
                 requestContext,
-                _clientApplicationBase.UserTokenCacheInternal).ConfigureAwait(false);
+                _clientApplicationBase.UserTokenCacheInternal,
+                cancellationToken).ConfigureAwait(false);
 
             requestContext.Logger.Info(() => LogMessages.UsingXScopesForRefreshTokenRequest(commonParameters.Scopes.Count()));