Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Client user delegation lets an agent access a downstream tool or resource in the context of a signed-in user represented by the client that calls the agent. The downstream service can apply the user's permissions, data access, and other authorization policies instead of treating every tool call as application-only access.
This article focuses on attended agent scenarios, in which a signed-in user interacts with an agent and the agent accesses downstream tools in that user's context. Foundry Agent Service supports multiple delegated authentication options for these scenarios. The right option depends on how the caller reaches the agent endpoint, how the downstream service accepts user authorization, and whether you're creating a new configuration or maintaining compatibility with an existing one.
Clients that connect directly to a toolbox, rather than through a Foundry agent, can use a separate per-tool OAuth sign-in for user delegation. Direct toolbox access doesn't support agent blueprint sign-in or the agent identity acting on behalf of the user.
At runtime, the tool connection determines how Agent Service obtains a credential that represents the user to the downstream service. The downstream service then authorizes the request according to the user's permissions and its own policies.
User delegation compared with application access
User delegation is appropriate when the downstream service must make an authorization decision for the signed-in user. Use an application or agent identity when the operation isn't user-specific.
| Authentication model | Identity presented downstream | Typical use |
|---|---|---|
| User delegation | The signed-in user, through Microsoft Entra on-behalf-of-user behavior or a separate OAuth sign-in | Reading a user's messages, files, records, or other user-authorized data. |
| Agent identity | The agent as an independent Microsoft Entra principal | Access controlled through roles or application permissions assigned to the agent. |
| Project managed identity | The Foundry project's managed identity | Shared project-level access to an Azure resource. |
| API key or custom credential | The principal associated with the stored credential | Services that don't support Microsoft Entra or delegated OAuth access. |
| No authentication | No authenticated principal | Public tools that intentionally allow anonymous access. |
Don't use user delegation when every user should receive the same application-level authority. Conversely, don't use an application identity when the downstream service must preserve user-specific authorization. Tool and channel support can narrow the available choices. Confirm the authentication types supported by the selected tool before creating a connection.
User delegation options
User delegation can reuse the Microsoft Entra user context from the incoming agent request or establish a separate OAuth session during the conversation.
| Delegation behavior | How it represents the user |
|---|---|
| On-behalf-of-user access | Agent Service uses the Microsoft Entra user context from the incoming agent request to obtain a credential for the downstream resource. |
| In-conversation OAuth sign-in | The user establishes a separate per-connection OAuth session during the conversation with the agent. |
Foundry IQ uses on-behalf-of-user access with target-specific source authorization behavior. For details, see Foundry IQ source authorization.
On-behalf-of-user access
With on-behalf-of-user access, a Microsoft Entra-protected tool receives a credential representing the user who called the agent. Agent Service performs the downstream token exchange. The downstream token represents both the user and an actor that participates in the exchange.
The available actor configurations depend on the tool. Some tools support a configuration in which the incoming endpoint audience determines the actor at runtime:
- When the incoming token targets Foundry, Foundry is the actor.
- When the incoming token targets the agent blueprint, the agent identity is the actor.
Other tools support or require a configuration in which the agent identity is always the actor. For this behavior, the endpoint must use the AgentBlueprint authorization scheme, and the incoming token must target the agent blueprint.
Note
In the connection API, UserEntraToken represents conditional selection between Foundry and the agent identity, AgentOnBehalfOfUser represents the agent-identity-only behavior, and OAuth2 represents in-conversation OAuth sign-in. For configuration details, see the guidance for the selected tool.
Foundry as the actor
Foundry can act on behalf of the user for a limited set of Microsoft-owned tools. It can't do so for custom servers or third-party integrations. The downstream resource receives a token obtained through an application rather than an agent. Foundry doesn't require an additional consent grant to interact with the supported tools.
The same actor configuration also allows the agent identity to act on behalf of the user when the incoming token targets the agent blueprint. Foundry acts only when the incoming token targets Foundry. This conditional behavior supports a transition from Azure RBAC access to agent blueprint access while both endpoint authorization schemes are configured. For more information, see Agent endpoint authorization.
Agent identity as the actor (preview)
The agent identity can act on behalf of the user when the incoming request is authorized through the AgentBlueprint scheme and its token targets the agent blueprint. This behavior is in preview. The downstream token represents both the user and the agent, which allows the resource to make authorization decisions about the agent. Microsoft Entra Conditional Access policies can also govern these tool calls.
The agent identity must be authorized for the requested downstream delegated permissions. Depending on the resource and tenant policy, this authorization can require user consent, administrator consent, or preauthorization. This article provides a concise overview in Consent behavior. For the fuller consent model, see Microsoft Entra consent for delegated access.
This behavior currently applies to direct runtime clients. Foundry development clients and Azure Bot Service integrations continue to use the Foundry audience and can't use an agent-identity-only actor configuration.
Agent Service can select the agent identity in either of these ways:
- Use the agent identity for every request.
- Select the actor from the incoming token's audience. This conditional behavior allows Foundry to remain the actor for compatibility with existing clients.
Some tools only allow the agent identity to be the actor.
Foundry IQ source authorization
Foundry IQ knowledge bases use a target-specific authorization behavior. Agent Service dynamically sets x-ms-query-source-authorization with the signed-in user's Azure AI Search token so the knowledge base can enforce source permissions. This behavior applies whether the incoming request targets Foundry or the agent blueprint.
When the agent request targets the blueprint audience, Agent Service attempts to get an access token for https://search.azure.com/user_impersonation on behalf of the user. If the required authorization hasn't been granted, the tool call can return an oauth_consent_request.
In-conversation OAuth sign-in
In-conversation OAuth sign-in prompts the user to establish a separate OAuth session during the conversation.
Direct toolbox clients can also use this separate per-tool OAuth sign-in with an OAuth2 connection. The term in-conversation describes the agent experience; the interface exposed by an MCP client isn't necessarily conversational. This downstream sign-in doesn't replace the client's authentication to the toolbox endpoint.
The calling application must support interactive authorization: surface the sign-in request to the user and continue after the user completes it. Configuring OAuth2 alone doesn't provide that client behavior. Confirm that your client supports this flow before relying on tools that require user sign-in.
The connection configuration specifies the authorization, token, and refresh endpoints, along with the scopes requested from the provider. Agent Service stores and refreshes the resulting credentials. It partitions the authorization state by user and connection, so each user's downstream credentials remain isolated. Applications must preserve the caller context required for this partitioning when they interact with the agent or connect directly to a toolbox.
For toolbox connection configuration and per-user OAuth handling, see How toolbox authentication works.
Consent behavior
Consent authorizes delegated permissions for a downstream resource. It doesn't grant the user access to data that the resource would otherwise deny. The resource continues to evaluate the user's permissions and its own authorization policies.
Administrator consent can avoid an interactive user prompt. Preauthorization can do the same thing when the downstream resource supports it. When interactive authorization is required, Agent Service can return an oauth_consent_request output item. The calling application surfaces the product-owned consent link and continues the interaction after consent. If tenant policy doesn't allow user consent, the attempt fails when the user tries to complete it. The application doesn't collect, inspect, or relay the downstream access token.
Consent is specific to the downstream resource. Each resource has its own permissions and consent state. For more information, see Microsoft Entra consent for delegated access.