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
and:
Bob
|
+--> Agent
|
+--> Toolbox
|
+--> Bob's token
The application should never implement token storage in a way that allows these identities to overlap.
A dangerous custom implementation might conceptually use:
var cacheKey = "orders-token";
Every user could then potentially resolve the same cached value.
A user-aware design requires the caller context to be part of the isolation boundary:
var cacheKey = $"{tenantId}:{userId}:orders";
This example illustrates the principle rather than prescribing a complete token-cache implementation.
In managed environments, centralizing this responsibility can reduce the amount of custom security-sensitive code that each agent needs to implement. Microsoft specifically identifies automatic per-caller token isolation as one of the benefits of Foundry Toolboxes.
Consent Should Be Explicit
User delegation does not mean an agent should automatically gain unlimited access to everything the user can access.
OAuth scopes should remain narrow.
For example:
orders.read
is preferable to an unnecessarily broad permission when the agent only needs to read order information.
A useful permission model is:
Agent capability
|
v
Required tool
|
v
Required OAuth scope
|
v
User consent
The requested scope should correspond to the actual business capability.
This reduces the impact if the agent or tool integration is compromised.
Adding Approval at the Tool Boundary
Authentication answers:
Who is making the request?
Authorization answers:
What can that identity access?
Approval answers another important question:
Should this particular action happen automatically?
These concerns should not be confused.
For example:
Read order status
|
v
Automatic
Cancel order
|
v
Require approval
An agent may be allowed to inspect information automatically but require explicit user confirmation before performing a consequential operation.
Microsoft's toolbox model also supports tool-level governance and approval configuration, making the tool boundary a natural place to enforce these controls.
Protecting the Toolbox With a Gateway
A toolbox can also sit behind an API gateway or similar infrastructure.
The architecture can look like:
User
|
v
Agent
|
v
Foundry Toolbox
|
v
API Gateway
|
+--> Authentication
+--> Rate limiting
+--> Logging
+--> Network policy
|
v
MCP Server
Microsoft specifically describes using a gateway such as Azure API Management for concerns including rate limiting, logging, and network policy.
This separation can be useful because the gateway handles infrastructure-level policies while the toolbox manages tool composition and authentication.
Toolboxes and MCP
Toolboxes are particularly relevant to Model Context Protocol (MCP) architectures.
An MCP server can expose tools to an agent, but authentication and governance can become complicated when many agents consume many MCP servers.
Without centralized management:
Agent A -> MCP Server -> Auth implementation
Agent B -> MCP Server -> Different auth implementation
Agent C -> MCP Server -> Another auth implementation
With a shared toolbox:
Agent A \
Agent B \
Agent C ---> Toolbox ---> MCP servers
Agent D /
The toolbox becomes a reusable integration boundary.
This is particularly useful when the same tools need to be consumed by multiple agents.
Designing Toolboxes for Reuse
A good toolbox should represent a meaningful capability rather than simply becoming a random collection of tools.
For example:
Employee Operations Toolbox
|
+--> Orders
+--> Customer profile
+--> Support tickets
is easier to reason about than:
Everything Toolbox
|
+--> Orders
+--> HR
+--> Finance
+--> GitHub
+--> Deployment
+--> Production database
+--> Email
+--> Everything else
The second approach creates a much larger authorization and governance surface.
Tool grouping should therefore follow business capabilities and security boundaries.
Versioning the Toolbox
A reusable toolbox should be treated as a managed interface.
For example:
employee-toolbox
|
+--> v1
|
+--> v2
|
+--> v3
This allows changes to the tool set to be managed independently from the agent's application logic.
When adding a tool, consider:
Required authentication
Required scopes
Approval requirements
Input validation
Output sensitivity
Failure behavior
Backward compatibility
A toolbox should not become an uncontrolled dependency where tools are added without reviewing their security implications.
Common Mistakes
Passing User Tokens Through Agent Code
This spreads sensitive authentication logic throughout the application.
Prefer keeping token handling at the appropriate authentication boundary.
Using Broad OAuth Scopes
Request only the permissions required by the tool.
Treating Authentication as Authorization
A valid user token does not mean the agent should be allowed to perform every possible action.
Giving Read and Write Operations the Same Trust Level
Reading information and changing business state often have very different risk profiles.
Ignoring Tenant Isolation
Multi-tenant applications must ensure that identity and authorization boundaries include the tenant context where required.
Putting Every Tool in One Toolbox
A giant toolbox increases governance complexity and makes authorization harder to reason about.
Skipping Observability
Tool calls should be traceable without exposing sensitive credentials or unnecessary user data.
Production Security Checklist
Before exposing a user-delegated toolbox to users, verify:
OAuth scopes are minimal.
User and tenant identity boundaries are clearly defined.
Tokens are never logged.
Secrets are not embedded in agent prompts or source code.
Read and write tools have appropriate approval policies.
Tool inputs are validated.
Sensitive tool outputs are handled according to data-protection requirements.
Failed authorization is handled explicitly.
Tool calls are observable.
Gateway policies are applied where required.
Toolbox versions are managed deliberately.
The agent receives only the tools it actually needs.
Foundry's current toolbox documentation also identifies role requirements for developers, agent identities, and end users in OAuth-based scenarios.
Comparison: Custom Delegation vs Foundry Toolboxes
| Area | Custom implementation | Foundry Toolbox |
|---|
| Token handling | Application-owned | Centralized by Foundry |
| Token isolation | Must be implemented carefully | Managed by Foundry |
| Consent | Application responsibility | Managed through configured connections |
| Token refresh | Application responsibility | Foundry-managed flow |
| Tool reuse | Requires integration work | Toolbox-based reuse |
| Agent code | More authentication plumbing | More focused on business logic |
| Governance | Must be built across integrations | Can be applied at toolbox/tool boundary |
| Initial flexibility | High | Depends on supported integrations |
| Operational burden | Higher | Lower for supported scenarios |
The table describes architectural responsibilities rather than a universal performance or security guarantee.
Frequently Asked Questions
What is user delegation in an AI agent?
User delegation allows an agent to access a downstream resource using the signed-in user's authorization context instead of using only the agent's own identity.
Why should tokens not be handled directly by every agent?
Repeated token handling creates duplicated security-sensitive code for acquisition, storage, refresh, consent, and authorization. Centralizing these concerns can reduce implementation complexity and the number of places where mistakes can occur.
Does a toolbox automatically make every tool secure?
No. Toolboxes provide authentication and governance mechanisms, but developers still need appropriate scopes, authorization policies, input validation, network controls, and approval policies.
When should I use agent identity instead of user delegation?
Use agent or project identity when the operation should run under an application-owned identity. Use user delegation when the downstream operation genuinely needs the permissions and data boundaries of the current user.
Can one toolbox contain multiple tools?
Yes. A toolbox is designed to group and reuse tools, including MCP-based tools and other supported tool types.
Does user delegation eliminate the need for OAuth concepts?
No. OAuth concepts such as scopes, consent, authorization, and token lifetimes still matter. The difference is that Foundry can manage much of the operational flow rather than requiring each agent to implement it independently.
Conclusion
User-delegated AI agents introduce a security problem that becomes increasingly difficult as the number of users, agents, and tools grows. The agent needs to act with the correct user's permissions without exposing tokens, mixing identities, or duplicating OAuth implementation across every integration.
Microsoft Foundry Toolboxes provide a centralized boundary for this problem. Authentication can be configured with the tool connection, while Foundry manages user delegation, token isolation, consent, and refresh for supported scenarios.
The architectural advantage is separation of concerns. The agent focuses on deciding what work needs to be done, while the toolbox handles how the authenticated tool interaction is established.
For production systems, however, user delegation should be only one part of the security design. Keep scopes narrow, separate read and write capabilities, require approval for sensitive operations, preserve tenant isolation, monitor tool calls, and treat every toolbox as a security boundary.
When these principles are applied together, AI agents can move from simply answering questions to safely performing actions on behalf of users without putting authentication logic into every agent implementation.