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:
| Method | Who grants consent | Use it when |
|---|---|---|
| Authorization request | A user, for themselves | The permission allows user consent and the user is |
| Admin consent endpoint | An administrator, for the organization | The permission requires administrator consent, or the organization approves the agent in advance. |
| Microsoft Graph | An administrator or automation, for the organization or one user | You 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 yourclient ID as the OAuth client. For single-instance agents, it is shared with the blueprint; for fleets, use the selected agentidentity 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. Validatestatewhen 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 packagesUsing access packages, you can enable standardized access for many AI Agents withDirect thesame 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 systemsAgents 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 theagent 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 rolesSome 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 RBACExchange 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 OnlineTeams 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 channelsAn 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>ChannelParameterDisplayed asInbound (channel → agent)Receiving eventsOutbound (agent → channel)Sending responsesDescriptionemailclient_idOutlookMail.ReadorMail.ReadWriteMail.SendorClient ID of the agent identity. For single-instance agents, this is shared with the blueprint. For fleets, don't use the blueprint client ID.Mail.ReadWritespo.files.commentsredirect_uriOneDrive and SharePointFiles.Read.AllorFiles.ReadWrite.AllA registered redirect URI on the blueprint app registration.Files.ReadWrite.Allteams-chatscopeTeams chatsChat.ReadorChat.ReadWriteChat.ReadWriteorSpace-separated, percent-encoded fully qualified downstream scopes.ChatMessage.Sendteams-channelstateTeams channelsChannelMessage.Read.AllOpaque value validated on return to prevent request forgery.ChannelMessage.SendCustom (third‑party) APIsAgents can call other OAuth‑protected APIs. EnsureAfter the administrator authenticates and approves, Microsoft Entra redirects to the redirect URI. Validatestatebefore processing the response.Method 3: Grant consent with Microsoft Graph
Create an
oauth2PermissionGrantto 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" }Property Description clientIdObject ID of the agent identity's service principal. consentTypeAllPrincipalsfor tenant-wide admin consent. UsePrincipalwith aprincipalIdfor single-user consent.resourceIdObject ID of the resource application and itsAPI's service principalexistin thetenant, 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,displayNameThe 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 withPATCHinstead of creating a duplicate.Verify consent
Request a new downstream access token after consent changes. Confirm that its
scpclaim contains the delegated scopes requiredscopes/app roles, and followby thesameoperation.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 topermissions and consent intheMicrosoftagent identity. - The authorization request used the agent identity
platform.client ID (the shared client ID for a single-instance agent).
Related content
Authentication protocols in agentsGrant Microsoft Graph application permissions to an agent identityPermissions and consent in the Microsoft identity platformCall a custom API as a user with ASP.NET CoreMicrosoft Entra built-in rolesCall a custom API as a user with the Auth SDK sidecar- Microsoft identity platform On-Behalf-Of flow
@@ -1,94 +1,139 @@ ----title: Grant agents access to Microsoft 365 resources-description: Learn how to grant access to agents through consent, manual authorization, and other authorization systems for Microsoft 365 resources.+title: Grant delegated permissions to an agent identity+description: Request or grant consent for OAuth scopes used by an agent to call APIs on behalf of a signed-in user. ms.topic: how-to-ms.date: 05/01/2026+ms.date: 11/06/2026+ai-usage: ai-assisted ms.reviewer: ergreenl--#Customer intent: As an IT administrator managing agent identities, I want to understand how to grant agents access to Microsoft 365 resources through various authorization methods, so that I can properly configure consent, manual authorization, and other authorization systems for agents in my organization.+#Customer intent: As a developer, I want to request consent for the minimum delegated permissions my agent needs to call APIs for a signed-in user. --- -# Grant agents access to Microsoft 365 resources+# Grant delegated permissions to an agent identity++Delegated permissions, also called OAuth scopes, let an agent call a downstream API on behalf of a signed-in user. Each scope defines an operation the agent can perform with that user's access. Consent records whether a user or administrator 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. -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.+## Choose a consent method -## Prerequisites+You can grant delegated permissions to an agent identity in three ways: -- An agent identity blueprint and at least one agent identity created from it.-- An agent identity blueprint with a valid redirect URI.+| Method | Who grants consent | Use it when |+| --- | --- | --- |+| [Authorization request](#method-1-request-user-consent-with-an-authorization-request) | A user, for themselves | The permission allows user consent and the user is present. |+| [Admin consent endpoint](#method-2-request-administrator-consent-with-the-admin-consent-endpoint) | An administrator, for the organization | The permission requires administrator consent, or the organization approves the agent in advance. |+| [Microsoft Graph](#method-3-grant-consent-with-microsoft-graph) | An administrator or automation, for the organization or one user | You grant consent programmatically, such as when you provision an agent. | -## How to request consent (delegated or application permissions)+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](key-concepts.md#record-the-identifiers-for-your-scenario). -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.+For an introduction to scopes and consent, see [OAuth 2.0 scopes and OpenID Connect scopes](/entra/identity-platform/scopes-oidc) and [Permissions and consent in the Microsoft identity platform](/entra/identity-platform/permissions-consent-overview). -### When to use delegated or application permissions+## Choose delegated permissions -The type of permissions you request depends on how your agent operates and what resources it needs to access.+Start with the operations the agent performs, and identify the least-privileged delegated permissions that support them: -Use delegated permissions when your interactive agent needs to act on behalf of a signed-in user. For example, read that user's mail, calendar, or files. Delegated access is carried in the token's scp claim.+- For Microsoft Graph, use the [Microsoft Graph permissions reference](/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. -Use application permissions when your autonomous agent runs without a user present and requires app-only access. For example, to read all users' profiles. App permissions appear in the token's roles claim.+The downstream API includes the granted delegated permissions in the access token's `scp` claim. -For more information, see [permissions and consent overview](../identity-platform/permissions-consent-overview.md)+## Method 1: Request user consent with an authorization request -### How consent works+Direct the signed-in user to the authorization endpoint to consent on their own behalf. Use the agent identity client ID as the OAuth client. For single-instance agents, it is shared with the blueprint; for fleets, use the selected agent's client ID, not the blueprint's. -For delegated permissions, when you redirect the user to the Microsoft identity platform `/authorize` endpoint, they review scopes such as `User.Read` and `Mail.Read`. If consent is granted, Microsoft Entra ID records an OAuth2PermissionGrant from your agent (client) to 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](/entra/identity-platform/scopes-oidc#admin-restricted-permissions).+The blueprint must have a registered web redirect URI. The consent-only authorization request uses `response_type=none`. It records consent without returning an access token. -### Building the consent URL+```text+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>+``` -When building your consent URL, the client ID should be your agent identity's ID. +Replace the example scope with the fully qualified downstream scopes the agent needs. Validate `state` when the browser returns to the redirect URI to prevent request forgery. -For more information, see [requesting permissions through consent](#how-to-request-consent-delegated-or-application-permissions). 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](/entra/identity-platform/v2-admin-consent)+For authorization-request parameters, see the [OAuth 2.0 authorization code flow](/entra/identity-platform/v2-oauth2-auth-code-flow). -## How to manually grant authorization (delegated or application)+## Method 2: Request administrator consent with the admin consent endpoint -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.+An administrator can grant delegated permissions for the entire organization when: -- [Manually grant delegated permissions](/graph/api/oauth2permissiongrant-post). Set your client ID as the agent identity ID.-- [Manually grant application permissions (app role assignment)](/graph/api/serviceprincipal-post-approleassignments). Set your principal ID as the agent identity ID.+- 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+Direct the administrator to the admin consent endpoint: -Using access packages, you can enable standardized access for many AI Agents with 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](agent-access-packages.md).+```text+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>+``` -## Other authorization systems+| Parameter | Description |+| --- | --- |+| `client_id` | Client ID of the agent identity. For single-instance agents, this is shared with the blueprint. For fleets, don't use the blueprint client ID. |+| `redirect_uri` | A registered redirect URI on the blueprint app registration. |+| `scope` | Space-separated, percent-encoded fully qualified downstream scopes. |+| `state` | Opaque value validated on return to prevent request forgery. | -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.+After the administrator authenticates and approves, Microsoft Entra redirects to the redirect URI. Validate `state` before processing the response. -### Azure role-based access control (Azure RBAC)+## Method 3: Grant consent with Microsoft Graph -Assign Azure roles 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](/azure/role-based-access-control/built-in-roles).+Create an `oauth2PermissionGrant` to record tenant-wide admin consent for the agent identity: -### Microsoft Entra roles+```http+POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants+Content-Type: application/json+Authorization: Bearer <admin-token> -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](/entra/identity/role-based-access-control/permissions-reference).+{+ "clientId": "<agent-identity-service-principal-object-id>",+ "consentType": "AllPrincipals",+ "resourceId": "<resource-api-service-principal-object-id>",+ "scope": "User.Read Mail.Read"+}+``` -### Exchange RBAC+| Property | Description |+| --- | --- |+| `clientId` | Object ID of the agent identity's service principal. |+| `consentType` | `AllPrincipals` for tenant-wide admin consent. Use `Principal` with a `principalId` for single-user consent. |+| `resourceId` | Object ID of the resource API's service principal in the tenant. |+| `scope` | Space-separated scope names (not URLs). For example, `User.Read Mail.Read`. | -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](/exchange/permissions-exo/application-rbac)+To find the resource API's service principal object ID, query by its app ID: -### Teams Resource-Specific Consent (RSC)+```http+GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<resource-app-id>'&$select=id,displayName+``` -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](/microsoftteams/platform/graph-api/rsc/resource-specific-consent).+The Microsoft Graph app ID is always `00000003-0000-0000-c000-000000000000`. For a custom API, use the app registration's application (client) ID. -### Permissions for agent communication across Microsoft 365 channels+A successful request returns `201 Created`. Update an existing grant with `PATCH` instead of creating a duplicate. -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.+## Verify consent -| Channel | Displayed as | Inbound (channel → agent)<br>Receiving events | Outbound (agent → channel)<br>Sending responses |-|---|---|---|---|-| `email` | Outlook | `Mail.Read` or `Mail.ReadWrite` | `Mail.Send` or `Mail.ReadWrite` |-| `spo.files.comments` | OneDrive and SharePoint | `Files.Read.All` or `Files.ReadWrite.All` | `Files.ReadWrite.All` |-| `teams-chat` | Teams chats | `Chat.Read` or `Chat.ReadWrite` | `Chat.ReadWrite` or `ChatMessage.Send` |-| `teams-channel` | Teams channels | `ChannelMessage.Read.All` | `ChannelMessage.Send` |+Request a new downstream access token after consent changes. Confirm that its `scp` claim contains the delegated scopes required by the operation. -### Custom (third‑party) APIs+If OBO returns a consent-related error, verify: -Agents can call other OAuth‑protected APIs. Ensure the resource application and its service principal exist in the tenant, define required scopes/app roles, and follow the same delegated or app‑permission flows. For more information, see Microsoft's guide to permissions and consent in the Microsoft identity platform.+- The requested scope matches a delegated permission exposed by the downstream API.+- The user or an administrator granted that scope to the agent identity.+- The authorization request used the agent identity client ID (the shared client ID for a single-instance agent). ## Related content -- [Authentication protocols in agents](agent-oauth-protocols.md)-- [Permissions and consent in the Microsoft identity platform](~/identity-platform/permissions-consent-overview.md)-- [Microsoft Entra built-in roles](~/identity/role-based-access-control/permissions-reference.md)+- [Grant Microsoft Graph application permissions to an agent identity](grant-application-permissions-agent-identity.md)+- [Call a custom API as a user with ASP.NET Core](aspnet-core-call-custom-api-as-user.md)+- [Call a custom API as a user with the Auth SDK sidecar](sidecar-call-custom-api-as-user.md)+- [Microsoft identity platform On-Behalf-Of flow](/entra/identity-platform/v2-oauth2-on-behalf-of-flow) 