pr comments

Author: GladwinJohnson

docs/design/managed_identity_capabilities_devex.md

@@ -1,70 +1,107 @@
-# Microsoft.Identity.Web – Claims & Client Capabilities Mini‑Spec (Managed Identity)
+# Microsoft.Identity.Web – Continuous Access Evaluation (CAE) for Managed Identity
 
-## Why ClientCapabilities (cp1)?
+## Why Continuous Access Evaluation?
 
-Adding the `cp1` client‑capability tells Microsoft Entra ID your service can handle Continuous Access Evaluation (CAE) claims challenges. Tokens will include an extra xms_cc claim, allowing near‑realtime revocation.
+Continuous Access Evaluation (CAE) lets Microsoft Entra ID revoke tokens or demand extra claims almost immediately when risk changes (user disabled, password reset, network change, policy update, etc.).
 
-## Overview
+A workload opts-in by sending the client-capability **`cp1`** when acquiring tokens. Entra then includes an **`xms_cc`** claim in the token so downstream Microsoft services know the caller can handle claims challenges.
 
-cp1 signals to Microsoft Entra ID that a workload identity can handle Continuous Access Evaluation (CAE) claims challenges. When a token includes the extra xms_cc claim, Azure can revoke the token (or demand additional claims) in near‑realtime.
+## What this spec adds to **Microsoft.Identity.Web**
 
-This spec adds declarative cp1 and claims challenge auto‑handling to Managed Identity flows in Microsoft.Identity.Web (Id.Web). The goal is zero‑touch for most developers: a single configuration knob at startup, automatic 401/claims recovery at runtime.
+* **Declarative opt-in** – one configuration knob (`ClientCapabilities: [ "cp1" ]`).
+* **Transparent 401 recovery** – when a downstream Microsoft API responds with a 401+claims challenge, Id.Web automatically:
+  1. extracts the claims body;
+  2. bypasses its token cache;
+  3. requests a fresh token that satisfies the claims;
+  4. retries the HTTP call **once**.
 
-## Typical Flow   (MI + Downstream API)
+The goal is **zero-touch** for most developers.
 
-- MI token request – Id.Web sends xms_cc=cp1 at app creation.
-- Access granted – Downstream API returns 200.
-- Policy change – Token later revoked; next call to Downstream API gets 401 + claims.
-- Transparent recovery – Id.Web detects challenge ⇒ forwards claims body, acquires fresh token, retries once.
+## Typical Flow (Managed Identity → Downstream API)
 
-_app developer does not need to handle claims, downstream api takes care of this_
+```text
+1. Id.Web → MSI endpoint   : GET /token?resource=...&xms_cc=cp1    ──▶
+2. MSI  → ESTS             : request includes cp1              ──▶
+3. ESTS → Id.Web           : access_token (xms_cc claim present)    ◀──
+4. Id.Web → Downstream API : GET /resource  ⟶  200 OK               │
+5. Policy change occurs                                             │
+6. Id.Web → Downstream API : GET /resource  ⟶  401 + claims payload │
+7. Id.Web handles challenge (steps 1-4 again, bypassing msal cache)      ──▶
+```
 
 ## Design Goals
 
 | #   | Goal                                                         | Success Metric                                           |
 |-----|--------------------------------------------------------------|----------------------------------------------------------|
-| G1  | Transparent CAE retry with cache-bypass on 401 claims challenge. | Secret or Graph call recovers without developer code.    |
+| G1  | Transparent CAE retry with cache-bypass on 401 claims challenge. | Downstream API call recovers without developer code.    |
 | G2  | Declarative client capabilities via configuration.           | Single place to add `cp1`; all MI calls include it.      |
 
-## 5 · Public API Impact
+## Public API Impact
 
 no changes to the public api.
 
-## Configuration 
+## Configuration Example
 
 ```
 {
   "AzureAd": {
     "ClientCapabilities": [ "cp1" ]
   },
 
-  // Resource entry (example)
-  "AzureKeyVault": {
-    "BaseUrl": "https://<your‑vault>.vault.azure.net/",
-    "RelativePath": "secrets/<secret-name>?api-version=7.4",
+  // Example downstream API definition (Contoso Storage API)
+  "ContosoStorage": {
+    "BaseUrl": "https://storage.contoso.com/",
+    "RelativePath": "data/records?api-version=1.0",
     "RequestAppToken": true,
-    "Scopes": [ "https://vault.azure.net/.default" ],
-
+    "Scopes": [ "https://storage.contoso.com/.default" ],
     "AcquireTokenOptions": {
       "ManagedIdentity": {
-        "UserAssignedClientId": "<user-assigned-mi-client-id>"
+        // optional – omit for system-assigned MI
+        "UserAssignedClientId": "<client-id>"
       }
     }
   }
 }
 ```
 
-## Code 
+> **Note** : The same configuration block works in *appsettings.json* or can be supplied programmatically.
+
+
+## Code Snippets
+
+### Registering & Calling a Downstream API
+
+```csharp
+// 1 – set up the TokenAcquirerFactory (test-helper shown for brevity)
+var factory = TokenAcquirerFactory.GetDefaultInstance();
+
+// 2 – register the downstream API using section "ContosoStorage"
+factory.Services.AddDownstreamApi("ContosoStorage",
+    factory.Configuration.GetSection("ContosoStorage"));
 
-```cs
-// register the downstream API using the "AzureKeyVault" section ────
-factory.Services.AddDownstreamApi("AzureKeyVault",
-    factory.Configuration.GetSection("AzureKeyVault"));
 IServiceProvider sp = factory.Build();
-IDownstreamApi api = sp.GetRequiredService<IDownstreamApi>();
+IDownstreamApi api   = sp.GetRequiredService<IDownstreamApi>();
+
+// 3 – call the API (Id.Web handles CAE automatically)
+HttpResponseMessage resp = await api.CallApiForAppAsync("ContosoStorage");
+```
 
-// ── 3. call the vault (app-token path) ──────────────────────────────────
-HttpResponseMessage response = await api.CallApiForAppAsync("AzureKeyVault");
+### Using **IAuthorizationHeaderProvider** (advanced)
+
+`IAuthorizationHeaderProvider` is fully supported with Managed Identity. Claims challenges propagate the same way:
+
+```csharp
+var headerProvider = sp.GetRequiredService<IAuthorizationHeaderProvider>();
+string header = await headerProvider.CreateAuthorizationHeaderForAppAsync(
+    scope: "https://storage.contoso.com/.default",
+    options: new AuthorizationHeaderProviderOptions
+    {
+        AcquireTokenOptions = new AcquireTokenOptions
+        {
+            ManagedIdentity = new ManagedIdentityOptions(), // system-assigned MI
+            Claims = claimsChallengeJson // when retrying after 401
+        }
+    });
 ```
 
 ## Telemetry

tests/Microsoft.Identity.Web.Test/ManagedIdentityCaeTests.cs

@@ -9,6 +9,15 @@
 using Microsoft.Identity.Web.TestOnly;
 using Xunit;
 using Microsoft.Identity.Web.Test;
+using NSubstitute;
+using System.Collections.Generic;
+using System.Net.Http;
+using System.Net;
+using System;
+using System.Text;
+using System.Security.Claims;
+using System.Threading;
+using Microsoft.IdentityModel.Tokens;
 
 namespace Microsoft.Identity.Web.Tests.Certificateless
 {
@@ -21,6 +30,14 @@ public class ManagedIdentityTests
         private const string CaeClaims =
             @"{""access_token"":{""nbf"":{""essential"":true,""value"":""1702682181""}}}";
 
+        private const string Downstream401Service = "Downstream401";
+        private const string FirstToken = "mocked.access.token-1";
+        private const string SecondToken = "mocked.access.token-2";
+        private const string VaultBaseUrl = "https://my-vault.vault.azure.net/";
+        private const string SecretPath = "secrets/mySecret";
+
+        private sealed record VaultSecret(string Value);
+
         [Fact]
         public async Task ManagedIdentity_ReturnsBearerHeader()
         {
@@ -32,13 +49,14 @@ public async Task ManagedIdentity_ReturnsBearerHeader()
             mockHttp.AddMockHandler(
                 MockHttpCreator.CreateMsiTokenHandler(accessToken: MockToken));
 
+            // Add the mock handler to the DI container
             factory.Services.AddSingleton<IManagedIdentityHttpClientFactory>(
                 _ => new TestManagedIdentityHttpFactory(mockHttp));
 
             IAuthorizationHeaderProvider headerProvider = factory.Build()
                                         .GetRequiredService<IAuthorizationHeaderProvider>();
 
-            // basic mi flow
+            // basic mi flow where we get a token
             string header = await headerProvider.CreateAuthorizationHeaderForAppAsync(
                                 Scope,
                                 new AuthorizationHeaderProviderOptions
@@ -52,6 +70,56 @@ public async Task ManagedIdentity_ReturnsBearerHeader()
             Assert.Equal($"Bearer {MockToken}", header);
         }
 
+        [Fact]
+        public async Task ManagedIdentity_WithClaims_HeaderBypassesCache()
+        {
+            // Arrange
+            TokenAcquirerFactoryTesting.ResetTokenAcquirerFactoryInTest();
+            var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
+            var mockedHttp = new MockHttpClientFactory();
+
+            // token-1 will be cached, token-2 should be returned when claims force a bypass
+            mockedHttp.AddMockHandler(MockHttpCreator.CreateMsiTokenHandler("token1"));
+            mockedHttp.AddMockHandler(MockHttpCreator.CreateMsiTokenHandler("token2"));
+
+            tokenAcquirerFactory.Services.AddSingleton<IManagedIdentityHttpClientFactory>(
+                _ => new TestManagedIdentityHttpFactory(mockedHttp));
+
+            var headerProvider = tokenAcquirerFactory.Build()
+                                        .GetRequiredService<IAuthorizationHeaderProvider>();
+
+            // Initial call – no claims, token cached
+            string header1 = await headerProvider.CreateAuthorizationHeaderForAppAsync(
+                Scope,
+                new AuthorizationHeaderProviderOptions
+                {
+                    AcquireTokenOptions = new AcquireTokenOptions
+                    {
+                        ManagedIdentity = new ManagedIdentityOptions
+                        {
+                            UserAssignedClientId = "UamiClientId2"
+                        }
+                    }
+                });
+            Assert.Equal("Bearer token1", header1);
+
+            // Same UAMI with CAE claims – should bypass cache
+            string header2 = await headerProvider.CreateAuthorizationHeaderForAppAsync(
+                Scope,
+                new AuthorizationHeaderProviderOptions
+                {
+                    AcquireTokenOptions = new AcquireTokenOptions
+                    {
+                        ManagedIdentity = new ManagedIdentityOptions
+                        {
+                            UserAssignedClientId = "UamiClientId2"
+                        },
+                        Claims = CaeClaims
+                    }
+                });
+            Assert.Equal("Bearer token2", header2);
+        }
+
         [Fact]
         public async Task UserAssigned_MI_Caching_and_Claims()
         {
@@ -143,5 +211,79 @@ public async Task SystemAssigned_MSI_Forwards_ClientCapabilities_InQuery()
             //string query = captureHandler.ActualRequestMessage!.RequestUri!.Query;
             //Assert.Contains("xms_cc=cp1%2Ccp2", query, StringComparison.OrdinalIgnoreCase);
         }
+
+        [Fact]
+        public async Task DownstreamApi_401Claims_TriggersSingleRetry_AndSucceeds()
+        {
+            // challenge JSON 
+            string challengeB64 = Base64UrlEncoder.Encode(
+                                      Encoding.UTF8.GetBytes(CaeClaims));
+
+            // authProvider mock 
+            var authProvider = Substitute.For<IAuthorizationHeaderProvider>();
+            DownstreamApiOptions? capturedOpts = null;
+
+            authProvider.CreateAuthorizationHeaderAsync(
+                    Arg.Any<IEnumerable<string>>(),
+                    Arg.Do<DownstreamApiOptions>(o => capturedOpts = o),
+                    Arg.Any<ClaimsPrincipal?>(),
+                    Arg.Any<CancellationToken>())
+                .Returns(ci => $"Bearer {FirstToken}",
+                         ci => $"Bearer {SecondToken}");
+
+            // queue handler: 401 w/ claims ? 200 OK
+            // Id Web will single retry the request on 401
+            var queue = new QueueHttpMessageHandler();
+
+            // 401 response with claims
+            var r401 = new HttpResponseMessage(HttpStatusCode.Unauthorized);
+
+            // add the claims challenge with error in the header
+            r401.Headers.WwwAuthenticate.ParseAdd(
+                $"Bearer realm=\"\", error=\"insufficient_claims\", " +
+                $"error_description=\"token requires claims\", " +
+                $"claims=\"{challengeB64}\"");
+            queue.AddHttpResponseMessage(r401);
+
+            queue.AddHttpResponseMessage(new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent("{ \"value\": \"MockSecretValue\" }",
+                                            Encoding.UTF8, "application/json")
+            });
+
+            // DI container
+            var services = new ServiceCollection();
+            services.AddHttpClient(Downstream401Service)
+                    .ConfigurePrimaryHttpMessageHandler(() => queue);
+            services.AddLogging();
+            services.AddTokenAcquisition();
+            services.AddSingleton(authProvider);
+
+            services.AddDownstreamApi(Downstream401Service, opts =>
+            {
+                opts.BaseUrl = VaultBaseUrl;
+                opts.RelativePath = SecretPath;
+                opts.RequestAppToken = true;
+                opts.Scopes = [ Scope ];
+            });
+
+            var sp = services.BuildServiceProvider();
+            var api = sp.GetRequiredService<IDownstreamApi>();
+
+            //  ACT 
+            VaultSecret? secret = await api.GetForAppAsync<VaultSecret>(Downstream401Service);
+
+            // ASSERT
+            Assert.NotNull(secret);
+            Assert.Equal("MockSecretValue", secret!.Value);             // retry succeeded
+
+            await authProvider.Received(2).CreateAuthorizationHeaderAsync(
+                Arg.Any<IEnumerable<string>>(),
+                Arg.Any<DownstreamApiOptions>(),
+                Arg.Any<ClaimsPrincipal?>(),
+                Arg.Any<CancellationToken>());                           // called twice
+
+            Assert.Equal(challengeB64, capturedOpts!.AcquireTokenOptions.Claims);
+        }
     }
 }