Use MSAL's recent UserFIC API for agentic flows

[Avery-Dunn]

Replaces the internal ROPC piggybacking mechanism for agentic User FIC token acquisition with MSAL .NET's native AcquireTokenByUserFederatedIdentityCredential API. This resolves a customer-reported caching bug (#3840), modernizes the agentic flow to use purpose-built MSAL APIs, and simplifies the implementation.

Background

ID Web's agentic User FIC flow previously hijacked the ROPC (AcquireTokenByUsernamePassword) path via an internal add-in (AgentUserIdentityMsalAddIn) that rewrote HTTP request bodies at the last moment. This had several drawbacks:

• No cache support: ROPC's silent-flow guard requires a non-null ClaimsPrincipal with oid/tid claims. In agentic scenarios, ClaimsPrincipal is typically null, so the cache was always bypassed — causing 2–4 unnecessary network calls per request (#3840).
• Fragile HTTP body manipulation: Opaque, hard to debug, bypasses MSAL's validation and telemetry.
• No type safety: String manipulation of grant types rather than MSAL's typed API surface.

MSAL .NET's AcquireTokenByUserFederatedIdentityCredential is a first-class API for this scenario with built-in cache support. Version 4.84.2 added the Guid userObjectId overload for OID-based flows.

Approach

Multi-CCA Pattern

Component	Role
Blueprint CCA	ID Web's existing CCA. Handles Leg 1: acquires FMI token (T1) via AcquireTokenForClient + WithFmiPath(agentAppId).
Agent CCA	Per-agent CCA whose client assertion callback chains to the blueprint for Leg 1. Handles Leg 2 (AcquireTokenForClient → T2) and Leg 3 (AcquireTokenByUserFederatedIdentityCredential → user token).

Both use MSAL's shared static cache (EnableSharedCacheOptions), providing natural cache key isolation via distinct ClientId values while ensuring tokens survive CCA re-creation.

Three-Leg Flow

1. Caller → CreateAuthorizationHeaderForUserAsync(scopes, options, claimsPrincipal: null)
2. TryGetAuthenticationResultForAgentUserFicAsync detects agentic flow (UPN or OID)
3. Silent lookup via stored account identifier → cache HIT? Return cached token.
4. Cache MISS:
   Leg 1: Blueprint CCA → AcquireTokenForClient + WithFmiPath → T1 (FMI token)
   Leg 2: Agent CCA → AcquireTokenForClient (T1 as client assertion) → T2
   Leg 3: Agent CCA → AcquireTokenByUserFederatedIdentityCredential(scopes, UPN/OID, T2) → user token
5. Store account identifier for future silent lookups
6. Return user token

On subsequent calls for the same (agent, user, tenant) tuple, step 3 returns the cached token with zero network calls.

Account Identifier Storage

A ConcurrentDictionary<string, string> maps "{agentAppId}:{USER_IDENTIFIER}:{TENANTID}" → MSAL account identifier. This replaces the role that ClaimsPrincipal oid/tid claims serve in other ID Web flows. Entries are cleaned up when the CCA dictionary is cleared at the size threshold.

Agent CCA Eviction

As DOS protection, the agent CCA dictionary is cleared entirely when it exceeds a configurable threshold (default 10,000). Since all agent CCAs use MSAL's shared static cache, clearing the dictionary only discards lightweight CCA objects — tokens remain accessible to newly-built CCAs via AcquireTokenSilent.

Tenant Propagation

The assertion callback extracts the tenant from AssertionRequestOptions.TokenEndpoint (when the host matches the configured instance) and applies WithTenantId to Leg 1. This ensures multi-tenant scenarios work correctly, matching the pattern used by OidcIdpSignedAssertionProvider.

Changes

Directory.Build.props

• Bump MSAL .NET from 4.84.1 → 4.84.2 (adds Guid userObjectId overload)

TokenAcquisition.cs

• TryGetAuthenticationResultForAgentUserFicAsync (new): Detects UPN/OID agentic flows, performs silent retrieval or the 3-leg flow via native MSAL APIs
• GetOrBuildAgentUserFicCcaAsync (new): Builds and caches agent CCAs with assertion callbacks that chain to the blueprint CCA; applies shared cache and size-threshold eviction
• ExtractTenantFromTokenEndpointIfSameInstance (new): Extracts tenant from token endpoint URL when host matches configured instance
• Early return in TryGetAuthenticationResultForConfidentialClientUsingRopcAsync: Intercepts agentic flows before the ROPC path
• Silent catch broadened: MsalException instead of MsalUiRequiredException
• Dead code removal: Agent identity extraction blocks from the ROPC method

TokenAcquisition.Logger.cs

• 6 structured log messages (LoggerMessage.Define):
  • AgentUserFicFlowDetected, AgentUserFicSilentSuccess, AgentUserFicSilentFailure
  • AgentUserFicAcquisitionComplete, AgentCcaCreated, AgentCcaEviction

LoggingEventId.cs

• 6 new event IDs (600–605)

AgentIdentitiesExtension.cs

• Removed add-in callback registration from AddAgentIdentities() (AddOidcFic() preserved)

AgentUserIdentityMsalAddIn.cs

• Deleted. Fully superseded by native MSAL API usage.

TokenAcquisitionTests.cs

• 4 core agent User FIC tests: UPN caching, OID caching, ClaimsPrincipal independence, UPN/OID isolation
• 3 shared cache isolation tests: Multi-agent/multi-user correctness, per-instance eviction behavior, shared cache token survival across CCA re-creation
• 1 size-threshold eviction test: Verifies dictionary clear at threshold
• 4 ExtractTenantFromTokenEndpointIfSameInstance tests: Same/different instance, null inputs, invalid URI

No Breaking Changes

All public APIs are unchanged:

• WithAgentUserIdentity(options, agentAppId, username) — now uses native UPN path internally
• WithAgentUserIdentity(options, agentAppId, userId) — now uses native OID path internally
• AddAgentIdentities() — still registers OidcFic; no longer registers the (internal) add-in callback

The deleted AgentUserIdentityMsalAddIn was internal static with no external consumers.

Known Limitations

• National cloud FIC scope: Hardcoded to api://AzureADTokenExchange/.default (public cloud). National cloud support requires cloud-aware inference in MSAL itself — to be addressed in a follow-up.

Resolves

• Agentic (User FIC) token flow bypasses MSAL cache when ClaimsPrincipal is null #3840 — Agentic User FIC cache bypass when ClaimsPrincipal is null

[Copilot]

Pull request overview

This PR modernizes the agentic “User FIC” token acquisition flow by replacing the prior ROPC piggybacking/request-rewrite add-in with MSAL’s native AcquireTokenByUserFederatedIdentityCredential API, aiming to restore proper MSAL cache usage and fix the cache-bypass reported in #3840.

Changes:

• Bumps MSAL .NET to 4.84.2 and switches agentic user token acquisition to native UserFIC (multi-CCA / 3-leg flow).
• Adds internal caching structures for per-agent CCA instances and MSAL account identifiers to enable silent token acquisition even when ClaimsPrincipal is null.
• Removes the internal MSAL add-in that rewrote ROPC requests and adds new unit tests covering UPN/OID cache behavior.

Reviewed changes

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

Show a summary per file

File	Description
Directory.Build.props	Updates MSAL .NET version to enable the needed UserFIC overload.
src/Microsoft.Identity.Web.TokenAcquisition/TokenAcquisition.cs	Implements native UserFIC flow, agent CCA caching, and account-id mapping for silent cache hits.
src/Microsoft.Identity.Web.TokenAcquisition/Constants.cs	Adds an internal key for overriding the token-exchange audience via ExtraParameters.
src/Microsoft.Identity.Web.AgentIdentities/AgentIdentitiesExtension.cs	Stops registering the old ROPC-rewrite callback in AddAgentIdentities().
src/Microsoft.Identity.Web.AgentIdentities/AgentUserIdentityMsalAddIn.cs	Deletes the internal add-in that rewrote token requests.
tests/Microsoft.Identity.Web.Test/TokenAcquisitionTests.cs	Adds new tests for agentic UserFIC caching behavior (UPN + OID).

[Copilot]

Pull request overview

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

Files not reviewed (1)

• src/Microsoft.Identity.Web.UI/Microsoft.Identity.Web.UI.xml: Generated file