Add agentic ID support by Avery-Dunn · Pull Request #5883 · AzureAD/microsoft-authentication-library-for-dotnet

Avery-Dunn · 2026-03-24T17:36:17Z

This PR adds high-level AcquireTokenForAgent API to perform the series of calls needed for agent identity scenarios, and extends the existing UserFIC behavior (added in #5802) with user OID support.

New public APIs:

AgentIdentity: Model class representing an agent app and the user it acts on behalf of (via a UPN or OID), as well as an app-only option with no user
IConfidentialClientApplication.AcquireTokenForAgent: High-level API that orchestrates the full multi-leg FMI+UserFIC flow internally. Accepts a blueprint CCA configured with SN+I certificate and handles Leg 1 (FMI credential), Leg 2 (assertion via FMI path), and Leg 3 (UserFIC exchange)
AcquireTokenByUserFederatedIdentityCredential(scopes, Guid userObjectId, assertion): New overload using a Guid type instead of a string, to represent a user's OID instead of their username. Matches similar behavior added to ID Web's AgentIdentitiesExtension.cs

Internal implementations:

AgentTokenRequest: New class to orchestrate the multi-leg flow using the blueprint CCA to obtain FMI credentials, building internal agent CCAs for assertion and token exchange
UserFederatedIdentityCredentialRequest conditionally sends user_id or username based on which overload was used, with matching CCS routing hints
New dictionary field in ConfidentialClientApplication to store internal CCA instances: a different CCA instance is needed for the internal token calls as they use a different client ID and credential, and a simple dictionary in the "main" CCA instance will ensure the internal CCA instances (and their token caches) share the lifetime of the main CCA instances
Logic to propagate app-level and request-level parameters, such as custom HTTP clients or claims, from the original caller down into the internal CCA instance and its token requests
Integration tests added to Agentic.cs to cover various agent ID scenarios these changes support: low-level UserFic API vs. high-level AcquireTokenForAgent API, UPN/OID/app-only options, caching and silent call behavior, etc.
Unit tests added to UserFederatedIdentityCredentialTests to cover the silent call/caching behavior on both the new agent API and existing FIC API

Copilot

Pull request overview

Adds agent identity support to MSAL .NET by introducing a new high-level AcquireTokenForAgent API that orchestrates FMI + UserFIC flows, plus extending UserFIC to support user identification by OID (Guid) in addition to UPN.

Changes:

Introduces AgentIdentity model and AcquireTokenForAgent public API (builder + request pipeline).
Adds a Guid overload for AcquireTokenByUserFederatedIdentityCredential and updates request construction (body + CCS routing) to send user_id.
Adds telemetry event ID and integration tests covering UPN/OID/app-only agent scenarios.

Reviewed changes

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

Show a summary per file

File	Description
tests/Microsoft.Identity.Test.Integration.netcore/HeadlessTests/Agentic.cs	Adds integration coverage for agent flows (low-level UserFIC + high-level AcquireTokenForAgent) including UPN/OID/app-only.
src/client/Microsoft.Identity.Client/TelemetryCore/Internal/Events/ApiEvent.cs	Adds telemetry API ID for `AcquireTokenForAgent`.
src/client/Microsoft.Identity.Client/PublicApi/netstandard2.0/PublicAPI.Unshipped.txt	Declares new public APIs (AgentIdentity, AcquireTokenForAgent, UserFIC Guid overload) for netstandard2.0.
src/client/Microsoft.Identity.Client/PublicApi/net8.0/PublicAPI.Unshipped.txt	Declares new public APIs for net8.0.
src/client/Microsoft.Identity.Client/PublicApi/net8.0-ios/PublicAPI.Unshipped.txt	Declares new public APIs for net8.0-ios.
src/client/Microsoft.Identity.Client/PublicApi/net8.0-android/PublicAPI.Unshipped.txt	Declares new public APIs for net8.0-android.
src/client/Microsoft.Identity.Client/PublicApi/net472/PublicAPI.Unshipped.txt	Declares new public APIs for net472.
src/client/Microsoft.Identity.Client/PublicApi/net462/PublicAPI.Unshipped.txt	Declares new public APIs for net462.
src/client/Microsoft.Identity.Client/OAuth2/OAuthConstants.cs	Adds `user_id` parameter constant for UserFIC OID requests.
src/client/Microsoft.Identity.Client/Internal/Requests/UserFederatedIdentityCredentialRequest.cs	Sends `user_id` vs `username` based on overload and aligns CCS routing hint behavior.
src/client/Microsoft.Identity.Client/Internal/Requests/AgentTokenRequest.cs	New internal request orchestrator implementing multi-leg agent flow via internal CCAs.
src/client/Microsoft.Identity.Client/IConfidentialClientApplication.cs	Adds `AcquireTokenForAgent` to the public interface.
src/client/Microsoft.Identity.Client/IByUserFederatedIdentityCredential.cs	Adds `Guid` overload for UserFIC and clarifies UPN vs OID semantics in docs.
src/client/Microsoft.Identity.Client/ConfidentialClientApplication.cs	Implements new public APIs (AcquireTokenForAgent + UserFIC Guid overload).
src/client/Microsoft.Identity.Client/ApiConfig/Parameters/AcquireTokenForAgentParameters.cs	New parameters bag for agent flow (AgentIdentity, ForceRefresh, SendX5C).
src/client/Microsoft.Identity.Client/ApiConfig/Parameters/AcquireTokenByUserFederatedIdentityCredentialParameters.cs	Adds `UserObjectId` to carry OID into request layer.
src/client/Microsoft.Identity.Client/ApiConfig/Executors/IConfidentialClientApplicationExecutor.cs	Adds executor overload for `AcquireTokenForAgent`.
src/client/Microsoft.Identity.Client/ApiConfig/Executors/ConfidentialClientExecutor.cs	Wires executor path to `AgentTokenRequest`.
src/client/Microsoft.Identity.Client/ApiConfig/AcquireTokenForAgentParameterBuilder.cs	New builder for `AcquireTokenForAgent` options (ForceRefresh, SendX5C) and telemetry.
src/client/Microsoft.Identity.Client/ApiConfig/AcquireTokenByUserFederatedIdentityCredentialParameterBuilder.cs	Adds builder factory/constructor for the new `Guid` overload.
src/client/Microsoft.Identity.Client/AgentIdentity.cs	New public model representing agent + (optional) user identity with UPN/OID/app-only options.

src/client/Microsoft.Identity.Client/Internal/Requests/AgentTokenRequest.cs

...client/Microsoft.Identity.Client/Internal/Requests/UserFederatedIdentityCredentialRequest.cs

…AD/microsoft-authentication-library-for-dotnet into avdunn/agent-identity-apis

Copilot

Pull request overview

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

Copilot · 2026-03-24T22:17:19Z

src/client/Microsoft.Identity.Client/Internal/Requests/AgentTokenRequest.cs

+            if (blueprintConfig.HttpManager != null)
+            {
+                builder.WithHttpManager(blueprintConfig.HttpManager);
+            }


PropagateHttpConfig only copies HttpClientFactory/HttpManager. If the blueprint CCA is configured with token-cache options (e.g., WithCacheOptions / shared cache settings), internal CCAs will be created with default cache options, which can change caching behavior and break expectations that the agent flow follows the blueprint’s cache configuration. Consider propagating relevant cache configuration (at minimum CacheOptions) into the internal CCA builders as well.

Suggested change

}

}

if (blueprintConfig.CacheOptions != null)

{

builder.WithCacheOptions(blueprintConfig.CacheOptions);

}

I don't believe CacheOptions should be propagated: currently the only option in CacheOptions is to use a shared, static cache, which would make the internal CCA instance's cache be shared with those created by customers.

If a customer created a CCA instance with the same app ID as the one set as the AgentIdentity then other acquireToken flows could find the agent-specific tokens cached in the acquireTokenForAgent flow.

src/client/Microsoft.Identity.Client/Internal/Requests/AgentTokenRequest.cs

Copilot · 2026-03-24T22:17:19Z

src/client/Microsoft.Identity.Client/ConfidentialClientApplication.cs

+        /// (and its in-memory token cache) instead of rebuilding from scratch each time.
+        /// </summary>
+        internal ConcurrentDictionary<string, IConfidentialClientApplication> AgentCcaCache { get; } = new();
+


AgentCcaCache is an unbounded ConcurrentDictionary keyed by agent application id (and currently reused across authorities). In long-lived processes that call AcquireTokenForAgent with many different agentApplicationIds, this can grow without limit and retain token caches indefinitely. Consider an eviction strategy (e.g., LRU/size cap), a way to clear entries, and/or scoping keys to include authority so entries don’t accumulate across tenants.

Suggested change

/// <summary>

/// Clears all cached agent <see cref="IConfidentialClientApplication"/> instances.

/// This can be used by long-lived hosts to avoid unbounded growth of the in-memory cache.

/// </summary>

internal void ClearAgentCcaCache()

{

AgentCcaCache.Clear();

}

/// <summary>

/// Removes a specific agent <see cref="IConfidentialClientApplication"/> instance

/// from the cache by its agent application identifier, if present.

/// Returns <c>true</c> if an entry was removed; otherwise, <c>false</c>.

/// </summary>

/// <param name="agentApplicationId">The agent application identifier used as the cache key.</param>

internal bool RemoveAgentCcaCacheEntry(string agentApplicationId)

{

if (string.IsNullOrEmpty(agentApplicationId))

{

return false;

}

return AgentCcaCache.TryRemove(agentApplicationId, out _);

}

I don't believe this will be a problem: each entry in the cache is pegged to a specific application ID, and customers likely won't have enough Entra apps to cause any memory issues here.

...client/Microsoft.Identity.Client/Internal/Requests/UserFederatedIdentityCredentialRequest.cs

src/client/Microsoft.Identity.Client/ApiConfig/Parameters/AcquireTokenForAgentParameters.cs

src/client/Microsoft.Identity.Client/Internal/Requests/AgentTokenRequest.cs

Copilot

Pull request overview

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

src/client/Microsoft.Identity.Client/Internal/Requests/AgentTokenRequest.cs

Copilot · 2026-03-25T20:51:50Z

src/client/Microsoft.Identity.Client/Internal/Requests/AgentTokenRequest.cs

+            // Instance discovery: honor the Blueprint's custom metadata or disabled discovery
+            agentConfig.CustomInstanceDiscoveryMetadata = blueprintConfig.CustomInstanceDiscoveryMetadata;
+            agentConfig.CustomInstanceDiscoveryMetadataUri = blueprintConfig.CustomInstanceDiscoveryMetadataUri;
+            agentConfig.IsInstanceDiscoveryEnabled = blueprintConfig.IsInstanceDiscoveryEnabled;


When building the internal Agent CCA, PropagateBlueprintConfig copies several config fields but does not propagate ServiceBundle.Config.AccessorOptions (set via .WithCacheOptions(...)). This can change token cache behavior (e.g., shared/static internal caches) between the blueprint and the internal Agent CCA, leading to surprising cache misses or memory growth differences. Consider copying AccessorOptions (and any other cache-related config required) into the Agent CCA config so the internal app/user caches respect the blueprint's cache configuration.

Suggested change

agentConfig.IsInstanceDiscoveryEnabled = blueprintConfig.IsInstanceDiscoveryEnabled;

agentConfig.IsInstanceDiscoveryEnabled = blueprintConfig.IsInstanceDiscoveryEnabled;

// Cache: propagate cache accessor options so Agent CCA respects Blueprint cache configuration

agentConfig.AccessorOptions = blueprintConfig.AccessorOptions;

src/client/Microsoft.Identity.Client/Internal/Requests/AgentTokenRequest.cs

neha-bhargava · 2026-03-27T20:41:53Z

...ntity.Client/ApiConfig/Parameters/AcquireTokenByUserFederatedIdentityCredentialParameters.cs

+                builder.AppendLine("=== AcquireTokenByUserFederatedIdentityCredentialParameters ===");
+                builder.AppendLine("SendX5C: " + SendX5C);
+                builder.AppendLine("ForceRefresh: " + ForceRefresh);
+                builder.AppendLine("UserIdentifiedByOid: " + UserObjectId.HasValue);


Log username as well

neha-bhargava · 2026-03-27T20:46:29Z

...client/Microsoft.Identity.Client/Internal/Requests/UserFederatedIdentityCredentialRequest.cs

+            // The user_fic grant identifies the user by either OID (user_id) or UPN (username).
+            // The parameter builder enforces that exactly one is set via separate constructors,
+            // so both values cannot be populated simultaneously through the public API.
+            // OID is checked first because it is immutable and preferred over UPN, which can be renamed.


I am not sure if this line is true. Is OID preferred in case of user fic?

I think username is common and logic is fine. Only the comment seems a bit misleading

Add agent ID support

588c935

Copilot AI review requested due to automatic review settings March 24, 2026 17:36

Merge branch 'main' into avdunn/agent-identity-apis

0950e3f

Copilot started reviewing on behalf of Avery-Dunn March 24, 2026 17:43 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

Avery-Dunn added 3 commits March 24, 2026 14:53

Improve caching behavior for agent scenarios

9f5ea5c

Merge branch 'avdunn/agent-identity-apis' of https://github.com/Azure…

5f86f9a

…AD/microsoft-authentication-library-for-dotnet into avdunn/agent-identity-apis

Improve unit test coverage of caching behavior

9462880

Copilot AI review requested due to automatic review settings March 24, 2026 22:09

Copilot started reviewing on behalf of Avery-Dunn March 24, 2026 22:10 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

Avery-Dunn added 2 commits March 25, 2026 09:31

Simplify internal CCA behavior and improve readability

a1c2246

Propagate app-level and request-level parameters

d67bd28

Copilot AI review requested due to automatic review settings March 25, 2026 20:45

Copilot started reviewing on behalf of Avery-Dunn March 25, 2026 20:46 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

Various PR feedback items

ed0ceb7

neha-bhargava reviewed Mar 27, 2026

View reviewed changes

-            }
+            }
+            if (blueprintConfig.CacheOptions != null)
+            {
+                builder.WithCacheOptions(blueprintConfig.CacheOptions);
+            }

+        /// <summary>
+        /// Clears all cached agent <see cref="IConfidentialClientApplication"/> instances.
+        /// This can be used by long-lived hosts to avoid unbounded growth of the in-memory cache.
+        /// </summary>
+        internal void ClearAgentCcaCache()
+        {
+            AgentCcaCache.Clear();
+        }
+        /// <summary>
+        /// Removes a specific agent <see cref="IConfidentialClientApplication"/> instance
+        /// from the cache by its agent application identifier, if present.
+        /// Returns <c>true</c> if an entry was removed; otherwise, <c>false</c>.
+        /// </summary>
+        /// <param name="agentApplicationId">The agent application identifier used as the cache key.</param>
+        internal bool RemoveAgentCcaCacheEntry(string agentApplicationId)
+        {
+            if (string.IsNullOrEmpty(agentApplicationId))
+            {
+                return false;
+            }
+            return AgentCcaCache.TryRemove(agentApplicationId, out _);
+        }

Conversation

Avery-Dunn commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Avery-Dunn Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Avery-Dunn Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

neha-bhargava Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

neha-bhargava Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

neha-bhargava Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Avery-Dunn commented Mar 24, 2026 •

edited

Loading