Configure user delegation for tools in Microsoft Foundry

Configure client user delegation so that Foundry Agent Service can access a downstream tool in the context of the signed-in user represented by the client that calls the agent. You can reuse the Microsoft Entra user context from the incoming agent request or ask the user to establish a separate OAuth session during the conversation.

For the identity behavior and actor choices behind these options, see User delegation for tools. For the consent boundaries, tenant-policy outcomes, and consent lifecycle, see Microsoft Entra consent for delegated access.

Prerequisites

  • A Foundry project with an existing agent.
  • Permission to create project connections and update the agent.
  • The endpoint URL for the downstream tool.
  • The delegated permissions required by the downstream resource.
  • A tool that supports the selected connection authentication type.
  • For agent identity acting on behalf of the user, agent blueprint endpoint access.
  • For in-conversation OAuth sign-in, an OAuth application or a managed OAuth configuration supported by the tool.

Choose an authentication type

Select the connection authentication type that maps to the behavior supported by the tool. For a conceptual comparison, see User delegation options.

Authentication type Conceptual behavior Use when
UserEntraToken Foundry or agent identity acts on behalf of the user The tool supports Foundry as the actor, or you need compatibility while clients transition between endpoint authorization schemes.
AgentOnBehalfOfUser Agent identity acts on behalf of the user The tool supports the agent identity as the actor. The endpoint must use the AgentBlueprint scheme; AgentOnBehalfOfUser isn't available through AzureRbac or its Entra alias. This behavior is in preview.
OAuth2 In-conversation OAuth sign-in The tool requires the user to establish a separate OAuth session for the connection.

This article configures the project connection. After you create it, make sure to configure your agent to use it.

Configure Microsoft Entra user delegation

Use supported scopes

The following table lists delegated scopes for specific tool integrations. Use these values with either authentication type when the tool supports it:

Authentication type How to use the listed scopes
UserEntraToken Omit scopes to use the listed values as defaults, or configure them explicitly.
AgentOnBehalfOfUser Configure the listed values explicitly.
Tool Delegated scopes
Azure Databricks Genie MCP1 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/user_impersonation
Azure DevOps MCP api://2a72489c-aab2-4b65-b93a-a91edccf33b8/Ado.Mcp.Tools
Fabric IQ — Fabric Data Agent https://analysis.windows.net/powerbi/api/DataAgent.Execute.All
Fabric IQ — Fabric Data Agent with workspace private link https://analysis.windows.net/powerbi/api/DataAgent.Execute.All
Fabric IQ ontology https://analysis.windows.net/powerbi/api/Item.Execute.All
https://analysis.windows.net/powerbi/api/Item.Read.All
Fabric IQ Power BI semantic model https://analysis.windows.net/powerbi/api/Item.Read.All
https://analysis.windows.net/powerbi/api/Item.Execute.All
https://analysis.windows.net/powerbi/api/Dataset.Read.All
Foundry MCP https://mcp.ai.azure.com/Foundry.Mcp.Tools
Microsoft Dataverse api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/McpServers.Dataverse.All
Sentinel Data Exploration 4500ebfb-89b6-4b14-a480-7f749797bfcd/.default
Sentinel Graph 4500ebfb-89b6-4b14-a480-7f749797bfcd/.default
Sentinel Knowledge Objects 4500ebfb-89b6-4b14-a480-7f749797bfcd/.default
Sentinel Memory 4500ebfb-89b6-4b14-a480-7f749797bfcd/.default
Work IQ Calendar api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/McpServers.Calendar.All
Work IQ Copilot api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/McpServers.CopilotMCP.All
Work IQ Mail api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/McpServers.Mail.All
Work IQ MCP1 api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask
Work IQ OneDrive api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/McpServers.OneDrive.All
Work IQ SharePoint api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/McpServers.SharePoint.All
Work IQ Teams api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/McpServers.Teams.All
Work IQ User api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/McpServers.Me.All
Work IQ Word api://ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/McpServers.Word.All

1 Azure Databricks Genie MCP and Work IQ MCP support AgentOnBehalfOfUser, but not UserEntraToken.

For Microsoft Entra on-behalf-of-user access to a custom MCP server, use AgentOnBehalfOfUser, not UserEntraToken. Custom MCP servers aren't listed in the table because their delegated scopes depend on the resource API they expose. Obtain the exact, fully qualified delegated scopes from the server's documentation or publisher, and configure them explicitly on the connection.

Configure UserEntraToken

Use UserEntraToken only with a tool in the supported scopes table or for an existing Foundry-to-Foundry A2A integration that uses it as a compatibility path. For the A2A target and audience, see Create an A2A connection.

The incoming endpoint token's audience determines whether Foundry or the agent identity acts with the user. A request authorized through AzureRbac or its Entra alias carries a Foundry-audience token, so Foundry acts on behalf of the user. A request authorized through AgentBlueprint carries an agent blueprint token, so the agent identity acts on behalf of the user.

Property Requirement Description Example
category Required Use RemoteTool for MCP or RemoteA2A for A2A. RemoteTool
target Required Specifies an endpoint that supports UserEntraToken. Use the exact target pattern documented for the tool. https://mcp.dev.azure.com/{orgName}
authType Required Selects conditional on-behalf-of-user behavior based on the incoming endpoint audience. UserEntraToken
audience Required Identifies the canonical Microsoft Entra resource for the target. api://2a72489c-aab2-4b65-b93a-a91edccf33b8
scopes Optional Overrides the default delegated permissions mapped to the target. Use fully qualified scope values unless the tool's contract specifies another format. api://2a72489c-aab2-4b65-b93a-a91edccf33b8/Ado.Mcp.Tools

Choose whether to use the target's default scopes or provide explicit scopes. The effective scopes determine the downstream token request and the permissions shown in any resulting consent flow.

Configuration Result
Omit scopes Agent Service requests the default scopes mapped to the recognized target.
Provide scopes Agent Service requests the specified scopes. Explicit scopes make the permission request clear and can restrict it when the target supports narrower delegated permissions.

Use the target and audience defined for the selected tool. If you provide scopes, they must identify the same downstream resource as the audience.

The following JSON shows an MCP connection with explicit scopes. Replace <tool-endpoint>, <resource-audience>, and <fully-qualified-delegated-scope> with the values for the selected tool. Add another array entry for each additional scope, or omit the scopes property to use the target's defaults.

{
  "properties": {
    "category": "RemoteTool",
    "target": "<tool-endpoint>",
    "authType": "UserEntraToken",
    "audience": "<resource-audience>",
    "scopes": [
      "<fully-qualified-delegated-scope>"
    ],
    "metadata": {
      "type": "generic_mcp",
      "audience": "<resource-audience>"
    }
  }
}

For an A2A connection, use RemoteA2A instead of RemoteTool and the target and audience from Create an A2A connection. Use the A2A connection metadata ("ApiType": "Azure") rather than the MCP-specific "type": "generic_mcp".

When the endpoint uses the AgentBlueprint scheme, we recommend that you record the downstream delegated permissions represented by the connection's scopes. If you omit scopes, record the delegated permissions mapped to the recognized target.

Configure AgentOnBehalfOfUser (preview)

Use AgentOnBehalfOfUser for a supported tool that requires the downstream token to represent both the user and the agent.

For a tool in the supported scopes table, configure the exact listed values.

Property Requirement Description Example
category Required Use RemoteTool for MCP or RemoteA2A for A2A. RemoteTool
target Required Specifies the downstream tool endpoint. https://example.com/mcp
authType Required Requires the agent identity to act on behalf of the user. AgentOnBehalfOfUser
scopes Required Lists the exact, fully qualified delegated permissions required by one downstream resource. api://example-tool/Tool.Access

Before you create the connection, configure the agent endpoint with the AgentBlueprint scheme. Keep AzureRbac or its Entra alias during preview and while any client or channel still depends on Foundry access. Use exact, fully qualified scopes for one downstream resource. Use /.default only when the supported scopes table specifies it.

The configured scopes determine the delegated permissions requested for the agent identity and user. After you create the connection, record the permissions on the agent blueprint before you complete downstream consent.

The following JSON shows the MCP connection properties. Replace <tool-endpoint> and <fully-qualified-delegated-scope> with the values for the downstream resource. Add another array entry for each additional scope.

{
  "properties": {
    "category": "RemoteTool",
    "target": "<tool-endpoint>",
    "authType": "AgentOnBehalfOfUser",
    "scopes": [
      "<fully-qualified-delegated-scope>"
    ],
    "metadata": {
      "type": "generic_mcp"
    }
  }
}

For an A2A connection, use RemoteA2A instead of RemoteTool and the A2A endpoint as the target. Use the A2A connection metadata ("ApiType": "Azure") rather than the MCP-specific "type": "generic_mcp". The delegated scopes must be permissions exposed by the downstream resource. For target requirements, see Create an A2A connection.

Use a separate connection for each downstream resource. Don't combine scopes for multiple resources in one connection.

Configure OAuth2

Use OAuth2 when the tool requires the user to establish a separate OAuth session during the conversation.

Existing MCP documentation refers to this behavior as OAuth identity passthrough. Use that article for the detailed setup and authorization flow.

Property Requirement Description Example
category Required Identifies the connection as a remote tool or remote agent. RemoteTool
target Required Specifies the endpoint that receives the OAuth-authenticated requests. https://example.com/mcp
authType Required Selects in-conversation OAuth sign-in. OAuth2
connectorName Required for managed OAuth Selects an OAuth configuration managed by Microsoft or the tool publisher. github
credentials.clientId Required for custom OAuth Identifies your OAuth application. <oauth-client-id>
credentials.clientSecret Conditional Authenticates a confidential OAuth client. Omit it when the OAuth application doesn't require a client secret. A secret stored in the project connection
authorizationUrl Required for custom OAuth Specifies the endpoint where the user signs in and grants consent. https://provider.example.com/oauth2/authorize
tokenUrl Required for custom OAuth Specifies the endpoint used to obtain access tokens. https://provider.example.com/oauth2/token
refreshUrl Required for custom OAuth Specifies the endpoint used to refresh access. Use the token URL when the provider doesn't expose a separate refresh endpoint. https://provider.example.com/oauth2/token
scopes Provider-dependent Lists the permissions requested from the provider. Omit this property only when the provider defines an appropriate default scope set. Include the provider's refresh-token scope when required. ["tool.read", "tool.write"]

Use managed OAuth when the tool publisher provides a managed configuration. Otherwise, configure a custom OAuth application with the values in the table. Preserve the caller context that Agent Service uses to partition authorization state by user and connection.

Note

When a service-to-service integration calls a hosted agent for multiple end users, set x-ms-user-identity to a stable value that identifies the user associated with each request. Agent Service uses this value to partition OAuth authorization state so that users don't share interactive sign-in context. Reuse the value for subsequent requests associated with the same user, and use a different value for each other user. For setup and required permissions, see Multiplex multiple users in one hosted agent session.

Record permissions on the agent blueprint

Complete this section for UserEntraToken or AgentOnBehalfOfUser when the endpoint uses the AgentBlueprint scheme. OAuth2 uses a separate provider-owned authorization flow.

Add the required permissions to the agent blueprint as a recommended bookkeeping step. This declaration records the access that the agent is expected to request and makes administrator review and consent easier, but Agent Service can request dynamic consent without it. The permission declaration is separate from the project connection:

  • The connection scopes identify the delegated permissions that Agent Service requests when the agent calls the downstream tool.
  • requiredResourceAccess declares the corresponding delegated permissions on the agent blueprint so that administrators can review them during consent.
  • inheritablePermissions identifies the downstream resource application whose granted delegated scopes can flow from the blueprint principal to its agent identities.

Neither configuration grants access. A user or administrator must still complete consent.

Configure permissions through Microsoft Entra

Use this process when you're an Owner of the agent blueprint in Microsoft Entra. For the exact role and Microsoft Graph permission requirements, see Configure inheritable permissions for agent identity blueprints.

  1. Get blueprint.client_id from the agent endpoint configuration.

  2. In the Microsoft Entra admin center, locate the agent identity blueprint with that application ID and record its Object ID.

  3. Resolve the downstream resource application's application ID and the ID of each delegated permission represented by the connection's fully qualified scopes. The permission ID is the id of the matching scope in the resource service principal's oauth2PermissionScopes collection.

  4. Update requiredResourceAccess on the agent blueprint. Preserve any existing resource entries and permissions that the agent still requires.

    PATCH https://graph.microsoft.com/v1.0/applications/<agent-blueprint-object-id>/microsoft.graph.agentIdentityBlueprint
Authorization: ******
Content-Type: application/json

{
  "requiredResourceAccess": [
    {
      "resourceAppId": "<downstream-resource-application-id>",
      "resourceAccess": [
        {
          "id": "<delegated-permission-id>",
          "type": "Scope"
        }
      ]
    }
  ]
}

    Reference: Update agentIdentityBlueprint, requiredResourceAccess resource type, and resourceAccess resource type

  5. Add the downstream resource application to inheritablePermissions. This example allows delegated scopes granted on the blueprint principal to flow to agent identities, but doesn't allow application roles to flow.

    POST https://graph.microsoft.com/v1.0/applications/microsoft.graph.agentIdentityBlueprint/<agent-blueprint-object-id>/inheritablePermissions
Authorization: ******
Content-Type: application/json
OData-Version: 4.0

{
  "resourceAppId": "<downstream-resource-application-id>",
  "inheritableScopes": {
    "@odata.type": "#microsoft.graph.allAllowedScopes",
    "kind": "allAllowed"
  },
  "inheritableRoles": {
    "@odata.type": "#microsoft.graph.noRoles",
    "kind": "none"
  }
}

    Reference: Configure inheritable permissions for agent identity blueprints

  6. Read the agent blueprint and its inheritablePermissions collection. Confirm that requiredResourceAccess contains the intended permission IDs and that the downstream resource application is configured for scope inheritance. These read operations use the read-only AgentIdentityBlueprint.Read.All Microsoft Graph permission, rather than the permissions required to modify the blueprint.

    Reference: Get agentIdentityBlueprint and List inheritablePermission objects

For more information about the difference between declaration, grant, and inheritance, see Inheritable permissions and required resource access in Microsoft Entra Agent ID.

Configure permissions through Foundry

Use the managed agent identity blueprint API as an alternative when you can manage the agent in Foundry but can't update its agent blueprint directly in Microsoft Entra.

Use one PATCH request to configure requiredResourceAccess and inheritablePermissions together.

To call the API, the caller needs one of these permissions:

  • Microsoft.CognitiveServices/accounts/AIServices/managedAgentIdentityBlueprints/write
  • Microsoft.MachineLearningServices/workspaces/agents/action

Send a PATCH request for the managed agent identity blueprint. Replace {project-endpoint} with your Foundry project endpoint and <agent-blueprint-name> with the managed blueprint resource name.

PATCH {project-endpoint}/managedAgentIdentityBlueprints/<agent-blueprint-name>?api-version=2025-05-01
Authorization: ******
Content-Type: application/json

{
  "requiredResourceAccess": [
    {
      "resourceAppId": "<downstream-resource-application-id>",
      "resourceAccess": [
        {
          "id": "<delegated-permission-id>",
          "type": "Scope"
        }
      ]
    }
  ],
  "inheritablePermissions": [
    {
      "resourceAppId": "<downstream-resource-application-id>",
      "inheritableScopes": {
        "@odata.type": "#microsoft.graph.allAllowedScopes",
        "kind": "allAllowed"
      }
    }
  ]
}

The managed agent identity blueprint GET and list responses don't return inheritablePermissions or requiredResourceAccess. Request the permission configuration through Foundry:

POST {project-endpoint}/managedAgentIdentityBlueprints/<agent-blueprint-name>/listPermissions?api-version=2025-05-01
Authorization: ******

Complete this section when the incoming request is authorized through the AgentBlueprint scheme and Agent Service needs delegated authorization for a downstream resource. For connections that use UserEntraToken or AgentOnBehalfOfUser, the configured downstream delegated permissions require authorization for the agent identity and user. OAuth2 uses the separate authorization flow described in OAuth identity passthrough.

Foundry IQ knowledge bases also use this consent behavior when the incoming request targets the agent blueprint. Agent Service requests https://search.azure.com/user_impersonation and dynamically sets the x-ms-query-source-authorization header on the knowledge base request. If consent is missing, the agent response can include an oauth_consent_request.

Choose the authorization path that applies to the downstream resource:

Authorization path Use when
Interactive user consent The downstream resource and tenant policy allow users to consent to the requested delegated permissions.
Preauthorization You own or control the downstream resource registration and can preauthorize the agent blueprint for the requested delegated permissions.
Tenant administrator consent The organization requires centralized approval or wants users to avoid interactive consent.

Use this path for agent identity consent when the user can grant the requested permissions. It doesn't apply to OAuth2 connections.

  1. Call the agent with a prompt that requires the configured tool.
  2. Inspect the response output for an oauth_consent_request.
  3. Present its consent_link as a link or button that opens the authorization flow in a browser window. The user signs in and reviews the requested permissions there.
  4. If your client manages the authorization window, watch for navigation to {projectEndpoint}/consent/done. After consent completes, close the window and return the user to the agent interaction. If your client can't observe browser navigation, ask the user to return after completing consent.
  5. After the user completes consent, continue from the previous response.

{projectEndpoint} is your Foundry project endpoint, such as https://<resource-name>.services.ai.azure.com/api/projects/<project-name>. The /consent/done redirect applies to this agent identity consent flow, not to OAuth2 connections. Opening the link or closing the window doesn't by itself establish that the user granted consent. If the user cancels or authorization fails, explain that the tool still requires authorization.

Agent Service can return a consent request even when tenant policy prevents user consent. In that case, the attempt fails when the user tries to complete it.

Preauthorize the application

Preauthorization is configuration on the downstream resource, not on the project connection. Use it only when you own or control the downstream resource registration.

  1. In the downstream resource's Microsoft Entra application manifest, add the agent blueprint and the permission IDs for the configured delegated scopes to api.preAuthorizedApplications. For the property format, see the api attribute in the application manifest.
  2. Call the agent with a prompt that requires the configured tool.
  3. Confirm that the tool call completes without an oauth_consent_request.

Use tenant administrator consent to approve the configured delegated permissions centrally and avoid prompting each user to consent interactively.

  1. Ask a tenant administrator to grant the configured delegated permissions to the agent blueprint.
  2. Call the agent with a prompt that requires the configured tool.
  3. Confirm that the tool call completes without an oauth_consent_request.

Consent for one downstream resource doesn't authorize another resource. Complete authorization separately for each resource.

Verify user delegation

After the tool is attached to the agent, verify both successful access and user isolation.

  1. Call the agent as a user who is authorized for the downstream data and confirm that the tool call completes.
  2. Call the agent as a user who isn't authorized for the same data and confirm that the tool doesn't return the restricted result.
  3. For in-conversation OAuth sign-in, confirm that each user receives and completes their own authorization flow.
  4. Confirm that subsequent calls use the established authorization state without exposing the downstream access token.
  5. Record the response ID and tool call ID needed to correlate the completed tool call. Don't log bearer tokens, refresh tokens, or consent links.

Migrate user delegation

The endpoint authorization migration is the primary workflow. Follow Transition from Azure RBAC to agent blueprint access to add the AgentBlueprint scheme, move clients to agent blueprint access, and remove AzureRbac or its Entra alias when the migration is complete. Use the applicable connection path while you validate agent blueprint access.

Migrate from another authentication type

Create a separate connection when you migrate from an authentication type that doesn't provide on-behalf-of-user access. Keeping the existing connection available lets you validate the new user-delegation behavior before switching the agent.

  1. Inventory the current connection, tool endpoint, authorization schemes, token audiences, and authorization behavior.
  2. Create an AgentOnBehalfOfUser connection beside the existing connection, and configure the exact, fully qualified delegated scopes required by the downstream resource.
  3. Attach the new connection only to a separate test version of the agent. Keep the production version configured with the existing connection, and don't expose both connections for the same tool in one agent version.
  4. When you test the AgentBlueprint scheme during the endpoint migration, complete downstream consent and verify the tool call and user isolation.
  5. After every intended client and user path succeeds, update the production agent to replace the existing connection reference with the new connection.
  6. Keep the previous connection available for rollback until the new production version is stable, and then retire it.

Migrate UserEntraToken callers to agent blueprint access

You don't need another connection when clients transition from Foundry-audience tokens to agent blueprint tokens. UserEntraToken supports both token audiences and selects the actor from the incoming token's audience.

  1. Inventory the connection target, audience, scopes, and downstream consent grants.
  2. Keep the existing UserEntraToken connection while you follow Transition from Azure RBAC to agent blueprint access.
  3. Test the AgentBlueprint scheme without replacing the connection.
  4. Complete downstream consent for the agent blueprint when required.
  5. Verify the tool call and user isolation before continuing the client migration.
  6. After you remove AzureRbac or its Entra alias, either keep UserEntraToken or optionally update the connection in place: change authType to AgentOnBehalfOfUser, remove audience, and configure the exact, fully qualified delegated scopes.
  7. If you change the connection authentication type, validate the tool call and user isolation again.

Related content

  • Last updated on