Does x-ms-user-identity enable per-user Toolbox OAuth for a Microsoft Foundry hosted agent invoked by a middle-tier service?

Brandon Litton 20 Reputation points
2026-08-11T21:30:33.2933333+00:00

We need clarification on the supported identity architecture for a Microsoft Foundry hosted agent using a Foundry Toolbox with a private, Microsoft Entra-protected MCP server.

Our request flow is:

Microsoft Teams user
→ trusted middle-tier bot
→ Microsoft Foundry hosted agent
→ Foundry Toolbox
→ private MCP server

The middle-tier bot authenticates the Teams user and invokes the hosted-agent Responses endpoint using its own managed identity. It also sends:

x-ms-user-identity: <server-verified Entra object ID>

The bot has the required UserIdentityImpersonation/action permission.

The documentation describes two relevant behaviors:

  1. x-ms-user-identity is an opaque delegated identifier that scopes hosted-agent sessions to an end user.
  2. Toolbox authentication states that oauth2 and user-entra-token connections can provide the downstream tool with credentials representing the signed-in user.

It is unclear whether these two mechanisms integrate when a middle-tier service principal—not the end user—calls the hosted-agent endpoint.

Could Microsoft clarify:

  1. Does a delegated x-ms-user-identity establish the “signed-in user” used by Toolbox oauth2 or user-entra-token connections?
  2. For a private MCP using oauth2, is consent and token storage partitioned by the delegated identity? Will the MCP receive an access token representing the end user rather than the bot or hosted-agent identity?
  3. Does every delegated end user require the Foundry Agent Consumer or Foundry User role when only the middle-tier service directly invokes the agent?
  4. Is user-entra-token supported for a custom, private MCP audience, or should a custom MCP use oauth2?
  5. Can a Toolbox connection forward request-specific application context such as account ID, office ID, and application role? If not, is the supported approach for the MCP to derive these attributes from oid, tid, protected token claims, or server-side records?
  6. What is Microsoft’s recommended architecture when authorization is based on user, account, and office and must be enforced independently on every tool call?

A previous test using project-managed-identity correctly resulted in a shared service identity. We want to determine whether the documented per-user OAuth boundary supports this middle-tier architecture without requiring a custom direct-MCP claims implementation.

Please distinguish generally available functionality from preview functionality and identify any required SDK or Microsoft Agent Framework versions.

Suggested tags: Microsoft Foundry, Azure AI Foundry, Hosted Agents, Toolbox, MCP, Microsoft Entra ID.We need clarification on the supported identity architecture for a Microsoft Foundry hosted agent using a Foundry Toolbox with a private, Microsoft Entra-protected MCP server.

Our request flow is:

Microsoft Teams user
→ trusted middle-tier bot
→ Microsoft Foundry hosted agent
→ Foundry Toolbox
→ private MCP server

The middle-tier bot authenticates the Teams user and invokes the hosted-agent Responses endpoint using its own managed identity. It also sends:

x-ms-user-identity: <server-verified Entra object ID>

The bot has the required UserIdentityImpersonation/action permission.

The documentation describes two relevant behaviors:

  1. x-ms-user-identity is an opaque delegated identifier that scopes hosted-agent sessions to an end user.
  2. Toolbox authentication states that oauth2 and user-entra-token connections can provide the downstream tool with credentials representing the signed-in user.

It is unclear whether these two mechanisms integrate when a middle-tier service principal—not the end user—calls the hosted-agent endpoint.

clarify:

  1. Does a delegated x-ms-user-identity establish the “signed-in user” used by Toolbox oauth2 or user-entra-token connections?
  2. For a private MCP using oauth2, is consent and token storage partitioned by the delegated identity? Will the MCP receive an access token representing the end user rather than the bot or hosted-agent identity?
  3. Does every delegated end user require the Foundry Agent Consumer or Foundry User role when only the middle-tier service directly invokes the agent?
  4. Is user-entra-token supported for a custom, private MCP audience, or should a custom MCP use oauth2?
  5. Can a Toolbox connection forward request-specific application context such as account ID, office ID, and application role? If not, is the supported approach for the MCP to derive these attributes from oid, tid, protected token claims, or server-side records?
  6. What is Microsoft’s recommended architecture when authorization is based on user, account, and office and must be enforced independently on every tool call?

A previous test using project-managed-identity correctly resulted in a shared service identity. We want to determine whether the documented per-user OAuth boundary supports this middle-tier architecture without requiring a custom direct-MCP claims implementation.

Please distinguish generally available functionality from preview functionality and identify any required SDK or Microsoft Agent Framework versions.

Microsoft Foundry, Azure AI Foundry, Hosted Agents, Toolbox, MCP, Microsoft Entra ID.

Foundry Tools
Foundry Tools

Formerly known as Azure AI Services or Azure Cognitive Services is a unified collection of prebuilt AI capabilities within the Microsoft Foundry platform

Answer accepted by question author
Karnam Venkata Rajeswari 5,255 Reputation points Microsoft External Staff Moderator
2026-08-11T21:48:31.1833333+00:00

Hello @Brandon Litton ,

Welcome to Microsoft Q&A .Thank you for reaching out to us.

Based on the current Microsoft Foundry documentation, the key distinction is between Hosted Agent delegated identity/session isolation and downstream OAuth identity passthrough.

Regarding if x-ms-user-identity establish the signed-in user for Toolbox oauth2 or user-entra-token - Not explicitly as an OAuth credential selector.

x-ms-user-identity allows a trusted middle tier to associate a Hosted Agent session with a specific end user. The middle tier must have the UserIdentityImpersonation/action permission.

Therefore , x-ms-user-identity establishes Hosted Agent user/session context; OAuth identity passthrough establishes the downstream authentication context.

For oauth2, is consent/token storage user-specific, and will the MCP receive the user's token - Yes, for OAuth identity passthrough.

It is documented that:

  • each user authorizes access through their own consent flow;
  • Agent Service securely stores that user's credentials; and
  • subsequent MCP calls use those credentials.

Therefore, when OAuth identity passthrough is successfully established, the MCP should receive a user-specific OAuth credential, rather than the shared project or agent identity. ([Microsoft Learn][2])

The remaining undocumented point is whether a middle-tier-supplied x-ms-user-identity automatically selects that user's stored OAuth credential.

For validation, inspect only non-sensitive claims at the MCP, such as:

oid, tid, aud, iss, scp, and roles.

Test two users and confirm that the MCP receives the expected user identity and custom audience.

Regarding if every delegated user require Foundry Agent Consumer or Foundry User- For OAuth identity passthrough, Foundry Agent Consumer is the current least-privilege role. Foundry User also works but provides broader permissions intended for developers. ([Microsoft Learn][2])

The middle-tier service principal separately needs:

  • Microsoft.CognitiveServices/accounts/AIServices/endpoints/interact/action
  • Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/UserIdentityImpersonation/action

The latter is not included in the current built-in roles and requires an appropriate custom role. ([Microsoft Learn][1])

So, the fact that the middle tier directly invokes the Hosted Agent does not eliminate the Foundry Agent Consumer requirement for users participating in OAuth identity passthrough.

Regarding if a custom private MCP use user-entra-token or oauth2 -

For a customer-owned private MCP with its own Entra audience, custom oauth2 is the recommended approach.

Microsoft restricts managed OAuth tokens scoped to known Microsoft audiences from being sent to custom or third-party MCP endpoints. Custom OAuth allows the organization to use its own Entra app registration and controlled audience.user-entra-token should be used where the target service supports Microsoft's documented managed user-token/audience model.

Regarding if Toolbox can forward account ID, office ID and application role -There is no documented generic Toolbox mechanism for injecting arbitrary business attributes such as accountId or officeId into the OAuth credential.

The recommended security pattern is:

Validated OAuth token > tid / oid / validated scopes & roles >Trusted entitlement store >Account + Office + Application authorization >MCP operation

Application roles can be used when present in validated token claims. Account and office permissions should normally come from trusted server-side entitlement data rather than client-supplied values.

For the requirement that authorization be enforced independently on every tool call, the recommended architecture is:

Teams user >Trusted middle tier >Hosted Agent>Toolbox custom OAuth2

Private MCP>Token validation + entitlement lookup>User / Account / Office authorization>Business services

The MCP must remain the final authorization boundary and independently validate every tool invocation:

  • user (oid/tid);
  • token issuer and audience;
  • scopes/roles;
  • account entitlement;
  • office entitlement; and
  • requested operation.

This prevents authorization from relying solely on the model, session, x-ms-user-identity, or client-supplied business identifiers.

The following references might be helpful , please check them out

Please let us know if the response was helpful

 

Thank you

Was this answer helpful?

1 person found this answer helpful.
0 comments

2 additional answers

Sort by: Most helpful
Most helpful Newest Oldest
  1. Brandon Litton 20 Reputation points
    2026-08-13T17:16:39.3433333+00:00

    How can i get a support ticket submitted and receive a phone call on this ?

    Was this answer helpful?

  2. Brandon Litton 20 Reputation points
    2026-08-13T17:09:40.01+00:00

    Yes, thank you for the response!

    Was this answer helpful?

    0 comments

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.