Microsoft Entra consent for delegated access in Foundry

Microsoft Entra consent lets a user or administrator authorize an application to request delegated permissions for a protected resource. In Foundry Agent Service, a single interaction can involve separate Microsoft Entra consent decisions for access to the agent and access from the agent to a downstream resource. This article explains how consent applies to Microsoft Entra on-behalf-of-user access in Foundry. For general Microsoft identity platform guidance, see Developer's guide to requesting permissions and consent.

Important

The AgentBlueprint endpoint authorization scheme and agent identity acting on behalf of a user are in preview. The consent concepts in this article also distinguish these preview capabilities from existing Foundry-as-actor compatibility behavior and connection-owned OAuth.

An agent interaction can cross two Microsoft Entra authorization boundaries. This article focuses on downstream consent for an agent to access a resource in the user's context. Endpoint consent is included to distinguish the client application's authorization to call the agent from the agent's authorization to access a downstream resource.

flowchart LR
    User[Signed-in user]
    Client[Client application]
    Agent[Foundry agent]
    Tool[Downstream resource]

    User --> Client
    Client -- "1. Token for Foundry or agent blueprint" --> Agent
    Agent -- "2. Delegated token for downstream resource" --> Tool

Endpoint consent authorizes the client application to request a token for the agent:

  • By using AzureRbac or its Entra alias, the client requests the Foundry resource's delegated permission.
  • By using AgentBlueprint, the client requests a delegated permission exposed by the individual agent blueprint.

Downstream consent authorizes access from the agent to another resource in the user's context. When the agent identity acts on behalf of the user, the consent grant lets the agent blueprint obtain a token for the downstream resource with the consented delegated scopes. A successful grant at one boundary doesn't satisfy the other: consent to call an agent blueprint doesn't authorize that agent to read the user's data from Microsoft Graph, Azure AI Search, or another downstream resource.

An OAuth2 project connection uses a separate authorization session between the user and the tool's OAuth provider. It doesn't reuse the incoming agent endpoint token or make the agent identity the actor in a Microsoft Entra token exchange.

The actor in the downstream token exchange determines whether the agent blueprint needs consent for the downstream resource. For an explanation of the available actor configurations, see On-behalf-of-user access.

Foundry can act on behalf of the user only for a limited set of supported Microsoft-owned tools. Treat this behavior as a compatibility path, not as a general alternative to agent-identity delegation.

Incoming access and connection behavior Downstream actor Consent consideration
A Foundry-audience request uses UserEntraToken for one of the limited supported Microsoft-owned tools Foundry This compatibility behavior isn't available for custom or third-party tools. Foundry is already authorized for the supported integration, so the agent blueprint doesn't need an additional downstream consent grant.
An agent-blueprint-audience request uses UserEntraToken Agent identity The agent blueprint can require user consent, administrator consent, or preauthorization for the downstream delegated permissions.
An agent-blueprint-audience request uses AgentOnBehalfOfUser Agent identity The agent blueprint can require user consent, administrator consent, or preauthorization for the downstream delegated permissions.

How permissions become available to an agent

When the agent identity acts on behalf of the user, several related elements determine whether access succeeds. Each element answers a different authorization question.

Element Where it's defined or recorded Question it answers
Connection scopes Foundry project connection Which delegated permissions does Agent Service request for this tool?
requiredResourceAccess1 Agent blueprint Which downstream permissions does the agent blueprint declare for administrator review?
inheritablePermissions1 Agent blueprint Which granted permissions can flow from the blueprint principal to its agent identities?
api.preAuthorizedApplications2 Downstream resource app registration Which client applications can request specific delegated permissions without an interactive consent prompt?
Consent grant Microsoft Entra tenant Has a user or administrator authorized the application to request those delegated permissions?
Resource authorization Downstream resource Does the signed-in user have access to the requested downstream data or operation?

1 For the relationship between permission declaration, consent grants, and inheritance, see Inheritable permissions and required resource access in Microsoft Entra Agent ID.

2 For the Microsoft Graph property, see apiApplication.preAuthorizedApplications.

Declaring a permission doesn't grant it. Configuring permission inheritance also doesn't create a consent grant. Conversely, a consent grant doesn't override the downstream resource's roles, ownership rules, access control lists, or other authorization policies.

What happens at runtime

Agent Service requests a downstream token with the scopes configured on the project connection. If Microsoft Entra finds an applicable grant or preauthorization, it issues the token and the tool call continues without a consent prompt.

If Microsoft Entra indicates that consent is required, Agent Service constructs a user consent link for the requested scopes and returns an oauth_consent_request output item. The link requests consent for the individual agent identity, not the agent blueprint principal. Completing the flow authors the consent grant for that agent identity, after which the calling application can continue the interaction.

The presence of a consent link means that downstream authorization is needed. It doesn't mean that the signed-in user is permitted to grant it. Microsoft Entra evaluates tenant policy when the user follows the link, so the attempt can fail during consent.

Ways to authorize delegated permissions

The available authorization path depends on the downstream resource, the permissions it exposes, and the policies of the user's tenant.

Authorization path Who makes the decision Typical consideration
Interactive user consent The signed-in user Appropriate only when the tenant permits the user to consent to the application and requested permissions.
Tenant administrator consent An authorized tenant administrator Centralizes review and can avoid individual consent prompts for the approved delegated permissions.
Preauthorization The owner of the protected resource application Avoids a consent prompt for an explicitly trusted client. Available only when the resource owner controls the application registration.

Note

For autopilots, the blueprint approval process presents the permissions registered on the agent blueprint to the tenant administrator. The administrator reviews them in the Accept permissions step and can grant admin consent before publishing the blueprint. For the approval flow, see Approve the blueprint.

Preauthorization and administrator consent can both remove an interactive prompt, but they operate differently. Preauthorization is configured by the protected resource to trust a client for specific delegated permissions. Administrator consent records an organization-wide grant in the tenant where users access the application.

No single path is universally preferred. Organizations can favor centralized review for sensitive resources while allowing user consent for lower-impact permissions from trusted applications.

Tenant policy determines whether the signed-in user can complete the interactive user consent path. The consent link returned by Agent Service doesn't identify the applicable policy. Tenant policy falls into one of these categories:

  • Default policy — The tenant uses a built-in Microsoft Entra user consent policy. Depending on the built-in policy assigned, users can consent only to selected low-impact permissions for qualifying applications, or to permissions that don't require administrator consent. Requests outside that policy require an existing tenant administrator grant or preauthorization.
  • User consent disabled — Users can't create consent grants for themselves. A consent link can still appear, but the user can't complete it. Access requires tenant administrator consent or preauthorization to be configured separately.
  • Custom policy — The tenant uses an organization-defined application consent policy. Whether the user can complete the link depends on that policy's conditions. Confirm the applicable conditions with the tenant administrator and arrange another authorization path when required.

When user consent is disabled, an administrator can assign selected developers the Microsoft Entra Application Developer role. This one-time role assignment lets a developer consent on their own behalf instead of requesting administrator consent for each eligible permission grant during development. It doesn't let the developer grant permissions that inherently require administrator consent. Users in this role are also added as owners when they create application registrations. For more information, see Delegate app registration permissions in Microsoft Entra ID.

For the Microsoft Entra policy categories and controls, see Overview of user and admin consent and Manage app consent policies.

Consent responsibilities change as an agent moves from individual development to team use and broader distribution. A consent grant that lets one developer test an agent isn't necessarily an appropriate authorization model for collaborators or users of a shared agent.

Start developing

During individual development, you can grant consent for yourself when the requested permissions are eligible for user consent and tenant policy allows it. If user consent is disabled, the Microsoft Entra Application Developer role lets you consent on your own behalf for eligible permissions, avoiding a separate administrator consent request for each permission grant during development. This Microsoft Entra role is separate from Azure RBAC roles that control access to Foundry resources.

The role doesn't replace the agent blueprint's permission declarations or permission inheritance configuration. It also doesn't override permissions that require administrator consent or the downstream resource's authorization of the signed-in user.

Add collaborators

Adding a collaborator to a Foundry project or agent doesn't transfer your user-specific consent grants. Each collaborator might need to consent for their own delegated access unless a tenant administrator grants consent for the organization or the downstream resource preauthorizes the agent identity.

If user consent is disabled, collaborators who need to test delegated access can request the Microsoft Entra Application Developer role described in Start developing. The role lets each assigned collaborator consent on their own behalf for eligible permissions.

Foundry collaboration permissions, Microsoft Entra application ownership, consent grants, and downstream resource authorization serve different purposes. For example, application ownership can let a collaborator manage Microsoft Entra configuration, but it doesn't grant the collaborator access to downstream data. Similarly, permission to work on the agent doesn't make the collaborator an owner of its Microsoft Entra objects or authorize delegated access.

Prepare to publish or share

Before sharing an agent with a broader audience, treat the connection scopes and the agent blueprint's registered permissions as the agent's permission contract. Confirm that:

  • The connection scopes represent the permissions that Agent Service requests.
  • requiredResourceAccess declares permissions that require administrator review.
  • inheritablePermissions includes the permissions that individual agent identities need.
  • The expected users can use interactive consent, or an applicable tenant administrator grant or preauthorization exists.
  • Users have authorization to the downstream resources that the agent accesses.

Don't rely on a user-specific grant held only by the original developer. A shared or published agent needs an authorization path that works for its intended users. For autopilots, the blueprint approval process provides one publishing model in which a tenant administrator reviews the registered permissions and can grant administrator consent before publishing.

Consent isn't necessarily a one-time design decision. Changes to the applications, permissions, users, or tenant policies can require another authorization review:

  • Adding downstream scopes can require a new grant for the additional permissions.
  • Removing a scope from the connection stops Agent Service from requesting it, but doesn't itself remove an existing Microsoft Entra consent grant.
  • Revoking a user or administrator grant can cause a later tool call to require consent again.
  • Changing tenant consent policy can affect new consent attempts without automatically removing grants that already exist.
  • Consent for one downstream resource doesn't authorize another resource.
  • Administrator consent doesn't guarantee that every user can access the application or the downstream data. Assignment requirements and resource authorization still apply.

Review delegated permissions when you add tools, widen connection scopes, change the endpoint audience, or migrate from Foundry acting on behalf of the user to the agent identity acting on behalf of the user.

An interaction can fail at the agent endpoint, during consent, while Agent Service requests the downstream token, or when the downstream resource authorizes the request. The point of failure determines which configuration or policy applies:

  • The client can't call the agent. This is an endpoint authorization issue, not a downstream consent issue. Check the endpoint scheme, token audience, Azure RBAC, and token-validation rules. For more information, see Agent endpoint authorization.
  • Agent Service returns an oauth_consent_request. The downstream token request needs a consent grant. This output item isn't itself a failure. The user must complete the link for the interaction to continue. If the user can't grant consent, an administrator grant or preauthorization must be established separately before retrying.
  • The user can't complete the consent link. This is a consent failure. Tenant policy might prevent user consent, the requested permission might require administrator consent, or the user might not be authorized to grant it. Review the tenant policy category and the available authorization paths.
  • Consent completes, but the tool call is denied. Consent doesn't determine whether the user can access the downstream data or operation. Check the user's roles, permissions, ownership, or other authorization at the downstream resource.
  • The requested downstream permissions are incorrect or unavailable to the agent identity. This is a configuration issue. Compare the connection scopes with the agent blueprint's requiredResourceAccess and inheritablePermissions. For more information, see How permissions become available to an agent.

Related content

  • Last updated on