Introduction
AI agents become significantly more useful when they can do more than generate text. An internal employee agent might look up an order, access a document, search company information, or work with a private API on behalf of the person using it.
That creates an important security question:
Whose identity does the agent use when it calls a tool?
Using the agent's own identity is not always correct. Some tools need access to the signed-in user's data and permissions. For example, an employee-facing agent may need to access information that the current employee is authorized to see, but another employee is not.
This is where user delegation becomes important.
Microsoft Foundry Toolboxes provide a centralized way to configure tools and their authentication, including OAuth 2.0 user delegation. Foundry can manage token acquisition, token isolation, consent, and refresh on behalf of the agent rather than requiring every agent implementation to build this authentication plumbing independently.
The result is a cleaner architecture in which the agent focuses on business logic while the toolbox provides the authenticated tool boundary.
Why User Delegation Is Different From Agent Authentication
There are two fundamentally different authorization models.
Agent Identity
The tool sees the agent or application identity:
User
|
v
AI Agent
|
v
Agent Identity
|
v
Tool
This is useful for service-to-service operations where the application should have its own permissions.
User Delegation
The downstream tool acts on behalf of the signed-in user:
User
|
v
AI Agent
|
v
User Delegation
|
v
Tool
The second model is useful when access should follow the user's existing permissions.
For example, consider an employee agent that retrieves order information.
Alice -> Agent -> Orders API
|
+--> Alice's permissions
Bob -> Agent -> Orders API
|
+--> Bob's permissions
The agent is the same, but the effective downstream identity changes with the caller.
That distinction is central to secure enterprise agent design.
Why Implementing User Delegation Yourself Is Difficult
At first, OAuth-based delegation can look like a straightforward token exchange.
In practice, a production implementation needs to handle several concerns.
Token Isolation
Tokens must be isolated between users and tenants.
Consider:
User A -> Token A
User B -> Token B
The application must never accidentally return Token A when processing User B's request.
Microsoft specifically identifies incorrect token-cache partitioning as a serious risk because a bad cache key could cause one user's downstream access to be exposed to another user.
Consent
Users may need to grant permission for an application to access a protected resource.
The system needs to handle situations such as:
No consent
|
v
Request authorization
|
v
User grants permission
|
v
Acquire token
Consent can also fail or change over time.
Token Refresh
Access tokens are temporary.
A long-running agent therefore needs a mechanism for acquiring or refreshing credentials without forcing the user through authentication for every tool call.
Multiple Tools
The complexity increases when an agent uses many protected tools.
For example:
Agent
|
+--> Orders API
|
+--> CRM API
|
+--> Document API
|
+--> Employee Directory
|
+--> Microsoft 365 context
Each integration can introduce different scopes, authorization requirements, token handling, and failure conditions.
This is one reason centralized tool authentication becomes attractive.
What Microsoft Foundry Toolboxes Change
A Foundry Toolbox moves authentication responsibility away from individual agent implementations.
Conceptually:
+------------------+
User --------------->| AI Agent |
+--------+---------+
|
v
+------------------+
| Foundry Toolbox |
+--------+---------+
|
+------------+------------+
| |
v v
Orders MCP Work IQ
| |
v v
User identity User identity
The agent consumes the toolbox as a tool endpoint.
The authentication configuration lives with the toolbox connection rather than being embedded in the agent's business logic. Microsoft describes this as keeping authentication in the toolbox while Foundry handles token acquisition, exchange, refresh, and caller-specific isolation.
This creates a useful separation:
Agent
-> What should I do?
Toolbox
-> Which tools are available?
Connection
-> How do I authenticate?
Identity system
-> What can this user access?
Supported Authentication Models
Foundry Toolboxes support multiple authentication patterns. Microsoft documents the following models for toolbox connections.
| Authentication | Identity reaching the tool | Typical use |
|---|---|---|
| agentic-identity | Agent identity | Service-to-service operations |
| project-managed-identity | Project managed identity | Application-owned access |
| oauth2 | End user | User-delegated access |
| custom-keys | Stored API key/header | Key-based services |
| none | Anonymous | Public tools |
The important point is that user delegation is only one option.
Do not use delegated access simply because it is available. Choose the identity model that matches the security boundary of the application.
Step 1: Configure the Connection
For an OAuth-based tool, the authentication type is configured when the connection is created.
Microsoft's current Foundry example uses an azd command similar to:
azd ai connection create <name-of-connection> \
--kind remote-tool \
--target <tool-endpoint> \
--auth-type oauth2 \
--authorization-url <auth-url> \
--token-url <token-url> \
--client-id <oauth-client-id> \
--client-secret <oauth-client-secret> \
--scopes "<scope1> <scope2>"
The exact authorization URL, token URL, client ID, secret, and scopes depend on the identity provider and protected tool.
The important architectural decision is that these authentication details are configured on the connection rather than being manually threaded through every agent operation.
Step 2: Build the Toolbox
Once the connections exist, tools can be grouped into a reusable toolbox.
A Python example from Microsoft's documentation uses a toolbox version similar to:
version = project.toolboxes.create_version(
name="employee-toolbox",
description="Private orders MCP and Work IQ connected via user delegation auth",
tools=[
MCPToolboxTool(
server_label="orders",
server_url="https://orders-mcp.example.com/mcp",
require_approval="never",
project_connection_id="orders-mcp",
),
WorkIQPreviewToolboxTool(
name="work_iq",
description="Reason over the caller's M365 mail, chats, meetings, docs.",
project_connection_id="workiq-conn",
),
],
)
This illustrates an important design pattern: the toolbox can contain multiple tools while centralizing how those tools are connected and authenticated.
Step 3: Consume the Toolbox From the Agent
The agent does not need to know the OAuth token implementation.
Instead, it consumes the toolbox endpoint.
For example:
PROJECT_ENDPOINT = "<project-endpoint>"
CONSUMER_URL = (
f"{PROJECT_ENDPOINT}/toolboxes/"
"employee-toolbox/mcp?api-version=v1"
)
toolbox = MCPStreamableHTTPTool(
name="employee_toolbox",
url=CONSUMER_URL,
)
agent = Agent(
client=FoundryChatClient(
project_endpoint=PROJECT_ENDPOINT,
credential=credential,
),
tools=[toolbox],
)
The result is a simpler agent architecture.
Instead of:
Agent
|
+--> OAuth code
+--> Token cache
+--> Consent handling
+--> Refresh logic
+--> Authorization headers
+--> Tool invocation
the architecture becomes:
Agent
|
+--> Toolbox
|
+--> Authenticated tools
Microsoft's example describes the same pattern for hosted agents, where adding another tool can be handled through the toolbox without changing the agent's core integration code.
Token Isolation Is a Security Boundary
One of the most important benefits of centralized user delegation is caller isolation.
Imagine two employees:
Alice
|
+--> Agent
|
+--> Toolbox
|
+--> Alice's token
Join the conversation! Your thoughts help the community grow.