Update managed_identity_capabilities_devex.md

Author: gladjohn

docs/design/managed_identity_capabilities_devex.md

@@ -1,38 +1,34 @@
-# Using **ClientCapabilities** (`cp1`) with **Managed Identity** and **Downstream APIs**
+# Microsoft.Identity.Web – Claims & Client Capabilities Mini‑Spec (Managed Identity)
 
 ## Why ClientCapabilities (cp1)?
 
-Adding the `cp1` client‑capability tells Azure AD your service can handle Continuous Access Evaluation (CAE) claims challenges. Tokens will include an extra xms_cc claim, allowing near‑realtime revocation.
+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.
 
-## Purpose
+## Overview
 
-This guide shows how to declare the cp1 client capability (Continuous Access Evaluation)
-in a .NET service that authenticates with Managed Identity and calls
-resources through Microsoft.Identity.Web’s Downstream API helpers. You’ll learn
-how to configure appsettings.json, acquire a CAE‑ready token (xms_cc=cp1),
-and optionally invoke Azure Key Vault — all without secrets or certificates.
+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.
 
-## Prerequisites
+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.
 
-| Requirement                               | Notes                                                     |
-|-------------------------------------------|-----------------------------------------------------------|
-| .NET SDK                                  | **8.0** or newer                                          |
-| Microsoft.Identity.Web                    | **latest**                                                |
-| Microsoft.Identity.Abstractions           | **latest**                                                |
-| Azure resource with Managed Identity      | VM, App Service, Functions, Container Apps, etc.          |
-| Key Vault permission                      | MI needs **Get Secret** on the vault                      |
+## Typical Flow   (MI + Downstream API)
 
-> **Tip** — For **user-assigned** MI, note the **Client ID** (GUID). Leave it blank for **system-assigned** MI.
+- 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.
 
-## Specification: Configuration Layers
+_app developer does not need to handle claims, downstream api takes care of this_
 
-| Layer            | JSON path / property                                      | Examples                                                                                                  | Lifespan                 | Rationale                                                                                                  |
-|------------------|-----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|---------------------------|-------------------------------------------------------------------------------------------------------------|
-| **App-level**    | `AzureAd` root → `ClientCapabilities`                     | `ClientCapabilities: [ "cp1" ]`<br>`Instance`, `TenantId`, credentials                                     | **Process-wide** — set once at startup | MSAL builds the client object **once**; everything here is stamped onto **every** token request.            |
-| **Request-level**| `AcquireTokenOptions` (inside each *DownstreamApi* entry, or passed programmatically) | • `ManagedIdentity.UserAssignedClientId`<br>• `Claims` (CAE challenges)<br>• `ForceRefresh`<br>• `UseMtlsPoP` | **Per token call**        | These knobs can differ by resource or retry and therefore belong in the per-call options object.           |
+## Design Goals
 
-### Why `cp1` stays at the App-level
-* **Identity of the client** – signals a *capability of the app*, not an individual request.  
+| #   | Goal                                                         | Success Metric                                           |
+|-----|--------------------------------------------------------------|----------------------------------------------------------|
+| G1  | Transparent CAE retry with cache-bypass on 401 claims challenge. | Secret or Graph 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
+
+no changes to the public api.
 
 ## Configuration 
 
@@ -42,6 +38,7 @@ and optionally invoke Azure Key Vault — all without secrets or certificates.
     "ClientCapabilities": [ "cp1" ]
   },
 
+  // Resource entry (example)
   "AzureKeyVault": {
     "BaseUrl": "https://<your‑vault>.vault.azure.net/",
     "RelativePath": "secrets/<secret-name>?api-version=7.4",
@@ -60,58 +57,24 @@ and optionally invoke Azure Key Vault — all without secrets or certificates.
 ## Code 
 
 ```cs
-// Copyright (c) Microsoft Corporation. All rights reserved.
-// Licensed under the MIT License.
-
-using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Logging;
-using Microsoft.Identity.Abstractions;
-using Microsoft.Identity.Web;
-using System.Net;
-using System.Text.Json;
-
-// ── 1. bootstrap factory (reads appsettings.json automatically) ─────────
-var factory = TokenAcquirerFactory.GetDefaultInstance();
-
-// optional console logging
-factory.Services.AddLogging(b => b.AddConsole().SetMinimumLevel(LogLevel.Warning));
-
-// ── 2. register the downstream API using the "AzureKeyVault" section ────
+// 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>();
 
 // ── 3. call the vault (app-token path) ──────────────────────────────────
 HttpResponseMessage response = await api.CallApiForAppAsync("AzureKeyVault");
+```
 
-if (response.StatusCode != HttpStatusCode.OK)
-{
-    Console.WriteLine($"Vault returned {(int)response.StatusCode} {response.ReasonPhrase}");
-    return;
-}
-
-//Get the secret value from the response
-using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+## Telemetry
 
-// Check if the "value" property exists and is a string
-if (doc.RootElement.TryGetProperty("value", out var valueElement) && valueElement.ValueKind == JsonValueKind.String)
-{
-    // Retrieve the secret value but do not print it
-    string secret = valueElement.GetString()!;
+We rely on server side telemetry for the token revocation features.
 
-    // Optionally, you can check if the secret is not null or empty
-    if (!string.IsNullOrEmpty(secret))
-    {
-        Console.WriteLine("Secret retrieved successfully (non-null).");
-    }
-    else
-    {
-        Console.WriteLine("Secret value was empty.");
-    }
-}
-```
+Server dashboards add MI success‑rate with/without cp1.
 
 ## Options as seen in MSAL 
 
-![alt text](capab1.png)
+![alt text](capab1.png)
+
+### reference - [How to use Continuous Access Evaluation enabled APIs in your applications](https://learn.microsoft.com/en-us/entra/identity-platform/app-resilience-continuous-access-evaluation?tabs=dotnet)