Example for On-behalf-of flow in Azure AI Foundry Agents by Entra ID

Question

Example for On-behalf-of flow in Azure AI Foundry Agents by Entra ID

Brown James 0

I'm working with AI Foundry and try a demo which enables end users to access their own account-specific content (such as Microsoft Graph API data or MCP tools) through the Agent Identity OBO Flow.

Could you please confirm if implementing the OBO flow is currently supported? If it is,is there any workable, reproducible demo to verify the feasibility of end user account access via AI Foundry Agent Identity; or detailed steps and clear guidance are critical to avoid deployment/testing obstacles

https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/agent-on-behalf-of-oauth-flow

Nikhil Duserla 9,685 Reputation points Microsoft External Staff Moderator

2026-02-08T16:24:01.1133333+00:00
Hello @Brown James ,

it sounds like you’re diving into the On-Behalf-Of (OBO) flow with Azure AI Foundry and want to confirm its current support status. You're also looking for a demo or clear guidance on how to implement it effectively. Here's what you need to know:

OBO Flow Support: Yes, the OBO flow is supported. It uses standard OAuth 2.0 to allow agent identities to act on behalf of signed-in users. The agents need to be assigned the necessary delegated permissions to access user-specific resources.

Implementation Guidance:

You can use the approved SDKs, such as Microsoft.Identity.Web and Microsoft Agent ID SDK libraries, for secure implementation. Avoid manual implementations as they can be complex and error-prone.

Typically, the OBO flow involves these steps:
1. The user authenticates and gets an access token. 1. The agent identity blueprint requests a token from Microsoft Entra ID using its client credentials. 1. The agent then sends an OBO token request to exchange for user-specific access. - Ensure that the agent identity blueprint and child agent identities hold the necessary permissions and proper audience settings for tokens. **Demo and Testing**: Unfortunately, there wasn't a direct reference to a reproducible demo in the documentation, but following the outlined steps will help you set up your environment tailored to your needs. **Further Considerations**: Be sure to check the roles your users have, as access will depend on the correct permissions being granted during the setup. For detailed instructions on managing roles and permissions, you can refer to the [Role-based access control for Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/role-based-access-control) documentation.

Here’s a quick rundown of some useful links:

OBO Flow Documentation

Role-Based Access Control

Hope this helps set you on the right track! If you have any more questions or need further details about specific parts, feel free to ask!

Was this helpful? it sounds like you’re diving into the On-Behalf-Of (OBO) flow with Azure AI Foundry and want to confirm its current support status. You're also looking for a demo or clear guidance on how to implement it effectively. Here's what you need to know:

OBO Flow Support: Yes, the OBO flow is supported. It uses standard OAuth 2.0 to allow agent identities to act on behalf of signed-in users. The agents need to be assigned the necessary delegated permissions to access user-specific resources.

Implementation Guidance:

You can use the approved SDKs, such as Microsoft.Identity.Web and Microsoft Agent ID SDK libraries, for secure implementation. Avoid manual implementations as they can be complex and error-prone.

Typically, the OBO flow involves these steps:
1. The user authenticates and gets an access token. 1. The agent identity blueprint requests a token from Microsoft Entra ID using its client credentials. 1. The agent then sends an OBO token request to exchange for user-specific access. - Ensure that the agent identity blueprint and child agent identities hold the necessary permissions and proper audience settings for tokens. **Demo and Testing**: Unfortunately, there wasn't a direct reference to a reproducible demo in the documentation, but following the outlined steps will help you set up your environment tailored to your needs. **Further Considerations**: Be sure to check the roles your users have, as access will depend on the correct permissions being granted during the setup. For detailed instructions on managing roles and permissions, you can refer to the [Role-based access control for Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/role-based-access-control) documentation.

Here’s a quick rundown of some useful links:

OBO Flow Documentation

Role-Based Access Control

Hope this helps set you on the right track! If you have any more questions or need further details about specific parts, feel free to ask!

Was this helpful?
Brown James 0 Reputation points

2026-02-09T03:40:14.31+00:00
First of all, thank you for your reply, but I'm still looking for a clearer answer to my question.

For my own app with Entra ID Authentication(a local or app service with obo server to acquire a access token by device code), should I create an app registration and redirect to my app? and how can I use the app access user's token to request an agent api ?

After my agent obtains a JWT token, I believe the next step—if I am using a Foundry service via a project endpoint—is to create a connection. But I am unsure which method to choose: agent identity or OAuth passthrough?

For my self-hosted MCP server, the process will proceed with the token exchanged using the agent identity. I have created a server app registration and plan to use masl.ConfidentialClientApplication#acquire_token_on_behalf_of() to exchange the user’s token for access to downstream APIs.

To simplify, I am confused about how to configure the Entra Agent ID flow to enable users in my own application to request the MCP server using their own identities. Furthermore, I would like to clarify the relationship between this configuration and the steps I need to take with the Agent Identity Blueprint and Foundry service.

I sincerely look forward to your reply and greatly appreciate the efforts you will make to help me resolve these doubts.
SRILAKSHMI C 15,040 Reputation points Microsoft External Staff Moderator

2026-02-10T13:25:03.35+00:00

Hi Brown James,

Did you get any chance to review the above response. Do let me know if you have any further queries.

Thank you!
Brown James 0 Reputation points

2026-02-21T15:12:07.2733333+00:00

Thanks for your attention. Here is the problem, and I would appreciate your help.
SRILAKSHMI C 15,040 Reputation points Microsoft External Staff Moderator

2026-02-23T06:23:53.68+00:00

Hi Brown James,

Thanks for confirming the solution. Since I’ve converted my earlier comment into an answer, could you please take a moment to mark it as Accepted? This helps others in the community with the same question find the solution more easily.

Thank you!

1 answer

Your answer

Brown James 0 Reputation points

2026-02-09T03:40:14.31+00:00

First of all, thank you for your reply, but I'm still looking for a clearer answer to my question.

For my own app with Entra ID Authentication(a local or app service with obo server to acquire a access token by device code), should I create an app registration and redirect to my app? and how can I use the app access user's token to request an agent api ?

After my agent obtains a JWT token, I believe the next step—if I am using a Foundry service via a project endpoint—is to create a connection. But I am unsure which method to choose: agent identity or OAuth passthrough?

For my self-hosted MCP server, the process will proceed with the token exchanged using the agent identity. I have created a server app registration and plan to use masl.ConfidentialClientApplication#acquire_token_on_behalf_of() to exchange the user’s token for access to downstream APIs.

To simplify, I am confused about how to configure the Entra Agent ID flow to enable users in my own application to request the MCP server using their own identities. Furthermore, I would like to clarify the relationship between this configuration and the steps I need to take with the Agent Identity Blueprint and Foundry service.

I sincerely look forward to your reply and greatly appreciate the efforts you will make to help me resolve these doubts.
SRILAKSHMI C 15,040 Reputation points Microsoft External Staff Moderator

2026-02-10T13:25:03.35+00:00

Hi Brown James,

Did you get any chance to review the above response. Do let me know if you have any further queries.

Thank you!
Brown James 0 Reputation points

2026-02-21T15:12:07.2733333+00:00

Thanks for your attention. Here is the problem, and I would appreciate your help.
SRILAKSHMI C 15,040 Reputation points Microsoft External Staff Moderator

2026-02-23T06:23:53.68+00:00

Hi Brown James,

Thanks for confirming the solution. Since I’ve converted my earlier comment into an answer, could you please take a moment to mark it as Accepted? This helps others in the community with the same question find the solution more easily.

Thank you!

Answer 1

Hello Brown James,

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

Do you need an app registration for your own app?

Yes. Absolutely. Your own application (local app, App Service, web app, etc.) must have its own Entra ID App Registration.

This app is responsible for:

Authenticating the end user
Acquiring a user access token (via device code, auth code, etc.)
Acting as the OBO client when calling the agent

Typical setup

Client app: Your frontend / API

App registration with delegated permissions
Uses device code or auth code flow

User signs in

You get a user access token (JWT) issued by Entra ID

You do not redirect to Foundry, Foundry is not the login experience, Foundry never authenticates the user directly

How does my app use the user token to call an Agent API?

Your app calls the Foundry Agent endpoint and includes the user’s access token in the Authorization header.

At this point:

Your app is saying: “This user is calling the agent”

The agent runtime receives a delegated user token

This is where Agent Identity OBO begins.

Agent Identity Blueprint, what is it actually for?

Think of the Agent Identity Blueprint as:

“The agent’s Entra identity + trust policy for token exchange”

It defines:

Which app registration represents the agent

Which downstream APIs the agent is allowed to call

That the agent is allowed to perform OBO token exchange

You do not exchange tokens yourself for Foundry-managed tools.

Instead:

Foundry uses the Agent Identity Blueprint

Foundry performs the OBO exchange on behalf of the agent

You configure the blueprint once, You do not pass client secrets to Foundry, Foundry securely executes the OBO flow

Agent Identity vs OAuth passthrough (this is the key confusion)

Use Agent Identity when:

You want the agent to call:

Microsoft Graph
Azure services
MCP tools
Fabric, Search, etc.

You want per-user access control

You want Foundry to handle OBO securely

This is what you want for your scenario

OAuth passthrough is for:

Forwarding a raw token to an external service

No OBO exchange

No enforcement by Foundry

Limited scenarios

OAuth passthrough is not recommended for Entra Agent ID flows, It does not give you proper delegated access semantics

For Foundry project endpoints, choose Agent Identity

What happens when the agent calls a Foundry service (project endpoint)?

Flow looks like this:

User signs in → user token issued

Your app calls Agent API with user token

Foundry validates the token

Foundry uses Agent Identity Blueprint

Foundry performs OBO token exchange

Agent calls Foundry services as the user

You do not create a connection manually for OBO, The identity mapping comes from the blueprint, The connection uses Agent Identity

Self-hosted MCP server your approach is correct

For your self-hosted MCP server, you do handle OBO yourself.

Your setup should be:

Server app registration

Expose scopes / app roles

Trust the agent identity

Use:

ConfidentialClientApplication.acquire_token_on_behalf_of()

Flow:

Agent receives user token

Agent calls MCP server with token

MCP server exchanges token via OBO

MCP server accesses downstream APIs as the user

This is correct, MASL / MSAL ConfidentialClientApplication is the right approach

How everything fits together

Here’s the clean mental picture:

Your App

Authenticates the user

Gets a user token

Calls Agent API with that token

Azure AI Foundry Agent

Receives the user token

Uses Agent Identity Blueprint

Performs OBO automatically

Calls tools / services as the user

Self-hosted MCP

Receives a token from the agent

Performs its own OBO exchange

Calls downstream APIs

You configure identity once, then the flow becomes automatic.

I hope this helps, do let me know if you have any further queries.

Thank you!

Brown James 0 Reputation points

2026-02-21T15:14:41.3633333+00:00

thanks for your attention, here is the problem

In my app I try interactive_login with scope https://ai.azure.com/.default and success require access token, simply example:

self.credential = OnBehalfOfCredential( tenant_id=self.tenant_id, client_id=self.client_id, client_secret=self.client_secret, user_assertion=user_token) endpoint = f"https://{self.foundry_account_name}.services.ai.azure.com" client # ERROR OCCURS agent_status = client.agents.get_agent( resource_group_name=self.foundry_resource_group, project_name=self.foundry_project_name, agent_id

I've got an error like below when I try to invoke ai service api, by the way the aud '73fcb0f6-330f-4f4e-b002-f921ae07d0ce' is my client id with display name 'mcp-client'. Is there anything wrong with my code or configuration?

{"error":"invalid_grant","error_description":"AADSTS500131: Assertion audience does not match the Client app presenting the assertion. The audience in the assertion was 'https://ai.azure.com' and the expected audience is '73fcb0f6-330f-4f4e-b002-f921ae07d0ce' or one of the Application Uris of this application with App ID '73fcb0f6-330f-4f4e-b002-f921ae07d0ce'(mcp-client). The downstream client must request a token for the expected audience (the application that made the OBO request) and this application should use that token as the assertion. Trace ID: a77b8bf0-af57-435e-8bfa-8fde2c1f6200 Correlation ID: f7365c14-27e5-451a-a934-48fe31a0e6ff Timestamp: 2026-02-21 14:52:10Z","error_codes":[500131],"timestamp":"2026-02-21 14:52:10Z","trace_id":"a77b8bf0-af57-435e-8bfa-8fde2c1f6200","correlation_id":"f7365c14-27e5-451a-a934-48fe31a0e6ff","error_uri":"https://login.microsoftonline.com/error?code=500131"}
SRILAKSHMI C 15,040 Reputation points Microsoft External Staff Moderator

2026-02-27T05:47:05.3033333+00:00

Hi Brown James,

We haven’t heard from you on the last response and was just checking back to see if you have a resolution yet. In case if you have any resolution please do share that same with the community as it can be helpful to others. Otherwise, will respond with more details and we will try to help.

Thank you!

Share via

Example for On-behalf-of flow in Azure AI Foundry Agents by Entra ID

1 answer

Your answer