Microsoft Entra Agent ID
Standards

Grant delegated permissions to an agent identity

In brief

The article was retitled and revised to explain OAuth scopes, consent, OBO access tokens, least-privilege permissions, and three consent methods: authorization requests, the admin consent endpoint, and Microsoft Graph.

What Entra admins need to know

Administrators can determine who grants consent and which agent identifier each method requires.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

Grant agents access to Microsoft 365 resources

This article provides guidance on how to grant access to agents through consent, manual authorization, and other authorization systems. Learn about the different methods available for authorizing agents to access Microsoft 365 resources and when to use each approach.

Prerequisites

  • An agent identity blueprint and at least one agent identity created from it.
  • An agent identity blueprint with a valid redirect URI.

How to request consent (delegated or application permissions)

Users or administrators can grant agents access to data by consenting to API permissions during the OAuth flow. This section explains how to request consent for delegated and application permissions for your agents.

When to use delegated or application permissions

The type of permissions you request depends on how your agent operates and what resources it needs to access.

Use delegated permissions when your interactiveto an agent needs to actidentity

Delegated permissions, also called OAuth scopes, let an agent call a downstream API on behalf of a signed-in user. For example, readEach scope defines an operation the agent can perform with that user's mail, calendar,access. Consent records whether a user or files. Delegatedadministrator approved the requested scopes for the agent identity.

An agent needs consent before it can use the OAuth On-Behalf-Of (OBO) flow to get a downstream access token. Request only the scopes required for the current task. Add other scopes later when the agent introduces features that need them.

In this article, you choose a consent method and request or grant the scopes your agent needs.

Choose a consent method

You can grant delegated permissions to an agent identity in three ways:

MethodWho grants consentUse it when
Authorization requestA user, for themselvesThe permission allows user consent and the user is carriedpresent.
Admin consent endpointAn administrator, for the organizationThe permission requires administrator consent, or the organization approves the agent in advance.
Microsoft GraphAn administrator or automation, for the organization or one userYou grant consent programmatically, such as when you provision an agent.

Methods 1 and 2 use the agent identity's client ID; method 3 uses its service principal object ID. For identifier meanings, see Record the identifiers for your scenario.

For an introduction to scopes and consent, see OAuth 2.0 scopes and OpenID Connect scopes and Permissions and consent in the Microsoft identity platform.

Choose delegated permissions

Start with the operations the agent performs, and identify the least-privileged delegated permissions that support them:

  • For Microsoft Graph, use the Microsoft Graph permissions reference.
  • For a custom API, use the scopes exposed by the API owner.
  • Check whether each permission allows user consent or requires administrator consent.

The downstream API includes the granted delegated permissions in the access token's scp claim.

Use application permissions when your autonomous agent runs without a

Method 1: Request user present and requires app-only access. For example, to read all users' profiles. App permissions appear inconsent with an authorization request

Direct the token's roles claim.

For more information, see permissions and consent overview

How consent works

For delegated permissions, when you redirect thesigned-in user to the Microsoft identity platform /authorize endpoint, they review scopes such as User.Read and Mail.Read. Ifauthorization endpoint to consent is granted, Microsoft Entra ID records an OAuth2PermissionGrant from your agent (client) toon their own behalf. Use the resource such as Microsoft Graph. Future delegated tokens for that resource include the approved scopes in scp without reprompting unless consent changes. If your app requests consent for admin restricted permissions, your users get an error. An admin requests these permissions directly. For more information, see admin-restricted permissions.

Building the consent URL

When building your consent URL, the client ID should be your agent identity's ID.

For more information, see requesting permissions through consent. Some permissions require consent from an administrator before they can be granted within a tenant. For more information, see admin consent on the Microsoft identity platform

How to manually grant authorization (delegated or application)

You can create the underlying authorization objects directly. It's useful for situations where you want to automate authorization or when you want to avoid interactive prompts.

  • Manually grant delegated permissions. Set your client ID as the OAuth client. For single-instance agents, it is shared with the blueprint; for fleets, use the selected agent identity ID.
  • Manually grant application permissions (app role assignment)'s client ID, not the blueprint's.

    The blueprint must have a registered web redirect URI. The consent-only authorization request uses response_type=none. Set your principal ID asIt records consent without returning an access token.

    https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize
    ?client_id=<agent-identity-client-id>
    &response_type=none
    &redirect_uri=<registered-redirect-uri>
    &response_mode=query
    &scope=https%3A%2F%2Fgraph.microsoft.com%2FUser.Read
    &state=<opaque-state-value>
    

    Replace the example scope with the fully qualified downstream scopes the agent identity ID.needs. Validate state when the browser returns to the redirect URI to prevent request forgery.

    For authorization-request parameters, see the OAuth 2.0 authorization code flow.

    Method 2: Request administrator consent with the admin consent endpoint

    An administrator can grant delegated permissions for the entire organization when:

    • The permission requires administrator consent.
    • User consent is turned off or restricted in the tenant.
    • The organization wants to preapprove the agent before any user accesses it.

    How to manage access through access packages

    Using access packages, you can enable standardized access for many AI Agents withDirect the same access needs. The access package can include Entra roles, OAuth2 delegated and application permission grants and security group memberships. Agents can then request an access package, or a sponsor or admin can request for them, and once approved, the agent identity or agent's user account receives the access rights until the assignment is revoked or expires. For more information, see access packages for agent identities.

    Other authorization systems

    Agents can be authorized in several ways beyond app-role assignments, group memberships and OAuth2 permission grants. These alternative systems offer flexibility for assigning access tailored to different platforms, services, and security requirements. The following sections summarize some of the many methods for agent authorization.

    Azure role-based access control (Azure RBAC)

    Assign Azure rolesadministrator to the agent identity at the narrowest scope (resource, resource group, subscription). For example, you can grant the Key Vault Reader role on a single vault so the agent can read secrets without needing broad directory or tenant permissions. For more information and step-by-step guidance, see Azure RBAC documentation.admin consent endpoint:

    Microsoft Entra roles

    Some low-privilege directory roles might be assignable to agents for metadata or read scenarios. High-privilege roles are blocked for agents by platform policy. To learn more about Microsoft Entra roles and PIM, see Microsoft Entra roles.

    Exchange RBAC

    Exchange RBAC (Role-Based Access Control) lets administrators delegate permissions to Exchange resources. It ensures agents can get granular authorization, such as autonomous access to one mailbox or a few mailboxes. For information, see Role Based Access Control for Applications in Exchange Online

    Teams Resource-Specific Consent (RSC)

    Teams Resource-Specific Consent (RSC) enables granular permission assignments for agents within Microsoft Teams. RSC allows you to grant permissions to an app or agent on a per-team basis, rather than at the tenant level. This approach is especially useful when you want to limit access to only the resources and data within specific teams. Such data includes channels, messages, or roster information, without granting broader organizational permissions. For more information, see Resource-specific consent for your Teams app.

    Permissions for agent communication across Microsoft 365 channels

    An agent with its own identity (Agent ID) can communicate across Microsoft 365 surfaces, including sending and receiving Outlook email, receiving and responding to comments in OneDrive and SharePoint files, and sending and receiving messages from Teams chats and channels. Each surface the agent communicates in requires specific permissions, which you declare in the agent identity blueprint's required resource access, and which a tenant admin must consent to before the agent can send or receive anything there.

    https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent
    ?client_id=<agent-identity-client-id>
    &redirect_uri=<registered-redirect-uri>
    &scope=https%3A%2F%2Fgraph.microsoft.com%2FUser.Read%20https%3A%2F%2Fgraph.microsoft.com%2FMail.Read
    &state=<opaque-state-value>
    
    ChannelParameter Displayed asInbound (channel → agent)
    Receiving events
    Outbound (agent → channel)
    Sending responsesDescription
    emailclient_id OutlookMail.Read or Mail.ReadWriteMail.Send or Mail.ReadWriteClient ID of the agent identity. For single-instance agents, this is shared with the blueprint. For fleets, don't use the blueprint client ID.
    spo.files.commentsredirect_uri OneDrive and SharePointFiles.Read.All or Files.ReadWrite.AllFiles.ReadWrite.AllA registered redirect URI on the blueprint app registration.
    teams-chatscope Teams chatsChat.Read or Chat.ReadWriteChat.ReadWrite or ChatMessage.SendSpace-separated, percent-encoded fully qualified downstream scopes.
    teams-channelstate Teams channelsChannelMessage.Read.AllChannelMessage.SendOpaque value validated on return to prevent request forgery.

    Custom (third‑party) APIs

    Agents can call other OAuth‑protected APIs. EnsureAfter the administrator authenticates and approves, Microsoft Entra redirects to the redirect URI. Validate state before processing the response.

    Method 3: Grant consent with Microsoft Graph

    Create an oauth2PermissionGrant to record tenant-wide admin consent for the agent identity:

    POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
    Content-Type: application/json
    Authorization: Bearer <admin-token>
    
    {
      "clientId": "<agent-identity-service-principal-object-id>",
      "consentType": "AllPrincipals",
      "resourceId": "<resource-api-service-principal-object-id>",
      "scope": "User.Read Mail.Read"
    }
    
    PropertyDescription
    clientIdObject ID of the agent identity's service principal.
    consentTypeAllPrincipals for tenant-wide admin consent. Use Principal with a principalId for single-user consent.
    resourceIdObject ID of the resource application and itsAPI's service principal exist in the tenant, definetenant.
    scopeSpace-separated scope names (not URLs). For example, User.Read Mail.Read.

    To find the resource API's service principal object ID, query by its app ID:

    GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<resource-app-id>'&$select=id,displayName
    

    The Microsoft Graph app ID is always 00000003-0000-0000-c000-000000000000. For a custom API, use the app registration's application (client) ID.

    A successful request returns 201 Created. Update an existing grant with PATCH instead of creating a duplicate.

    Verify consent

    Request a new downstream access token after consent changes. Confirm that its scp claim contains the delegated scopes required scopes/app roles, and followby the sameoperation.

    If OBO returns a consent-related error, verify:

    • The requested scope matches a delegated permission exposed by the downstream API.
    • The user or app‑permission flows. For more information, see Microsoft's guidean administrator granted that scope to permissions and consent in the Microsoftagent identity.
    • The authorization request used the agent identity platform.

      client ID (the shared client ID for a single-instance agent).

    Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…