Edit

Grant Microsoft Graph application permissions to an agent identity

Application permissions let an agent call Microsoft Graph as itself, without a signed-in user. All application permissions require administrator approval. Users can't consent to them.

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

Method Who grants consent Use it when
Authorization request An administrator who signs in through the agent's consent flow The agent or its setup experience prompts an administrator interactively.
Admin consent endpoint An administrator, for the organization You send an administrator a link to approve the agent.
Microsoft Graph An administrator or automation You grant permissions programmatically, such as when you provision an agent.

Note

For Azure services, grant the agent identity an Azure RBAC role on the target resource rather than an application permission. See Call Azure services as an agent with ASP.NET Core.

Prerequisites

  • An agent identity created from a blueprint. Record its client ID for methods 1 and 2, and its service principal object ID for method 3. For identifier meanings, see Record the identifiers for your scenario.
  • Global Administrator or Privileged Role Administrator role to grant admin consent.
  • For methods 1 and 2, a web redirect URI registered on the blueprint.
  • For method 3, a Microsoft Graph management client with AppRoleAssignment.ReadWrite.All and Application.Read.All. For delegated access, the signed-in administrator also needs Privileged Role Administrator to assign Microsoft Graph app roles. See the app role assignment API permissions.

Direct an administrator to the authorization endpoint. 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. Use the role parameter to specify each required permission. The consent-only request uses response_type=none, so it records consent without returning a 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
&role=User.Read.All
&role=Mail.Read
&state=<opaque-state-value>

The administrator signs in and approves the permissions for the organization. Validate state when the browser returns to the redirect URI to prevent request forgery.

Direct an administrator to the admin consent endpoint. Use the role parameter to specify each required permission:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent
?client_id=<agent-identity-client-id>
&role=User.Read.All
&redirect_uri=<registered-redirect-uri>
&state=<opaque-state-value>

To request multiple permissions in a single request, repeat the role parameter:

https://login.microsoftonline.com/<tenant-id>/v2.0/adminconsent
?client_id=<agent-identity-client-id>
&role=User.Read.All
&role=Mail.Read
&redirect_uri=<registered-redirect-uri>
&state=<opaque-state-value>
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.
role Permission name to grant, such as User.Read.All. Repeat for each permission.
redirect_uri A registered redirect URI on the blueprint app registration.
state Opaque value validated on return to prevent request forgery.

After the administrator authenticates and approves, Microsoft Entra redirects to the redirect URI. Validate state before processing the response.

Method 3: Assign application permissions with Microsoft Graph

Create an app role assignment directly on the agent identity's service principal:

Use the management client's access token, not the agent's runtime credential. Don't grant these directory-management permissions to the agent just to let it call a downstream API.

POST https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments
Content-Type: application/json
Authorization: Bearer <admin-token>

{
  "principalId": "<agent-identity-id>",
  "resourceId": "<microsoft-graph-service-principal-object-id>",
  "appRoleId": "<app-role-id>"
}
Property Description
principalId ID of the agent identity.
resourceId Object ID of the Microsoft Graph service principal in your tenant.
appRoleId GUID of the specific application permission to grant.

Grant one permission per request.

Find the Microsoft Graph service principal object ID:

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id,displayName

Find the app role ID for a specific permission:

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=appRoles

In the response, find the entry in appRoles where value matches the permission name, such as User.Read.All. Use its id as appRoleId.

Verify the assignment

After granting permissions, verify that each app role assignment was created:

GET https://graph.microsoft.com/v1.0/servicePrincipals/<agent-identity-id>/appRoleAssignments

Each entry in the response represents one granted application permission. The agent identity can request tokens with https://graph.microsoft.com/.default to receive the granted roles in the token's roles claim.