Grant or revoke API permissions programmatically

When you grant API permissions to a client app in Microsoft Entra ID, the permission grants are recorded as objects that can be accessed, updated, or deleted like any other data. Using Microsoft Graph to directly create permission grants is a programmatic alternative to interactive consent and can be useful for automation scenarios, bulk management, or other custom operations in your organization.

In this article, you learn how to grant and revoke app roles for an app using Microsoft Graph. App roles, also called application permissions, or direct access permissions, allow an app to call an API with its own identity. Learn more about application permissions.

Caution

Be careful! Permissions granted programmatically are not subject to review or confirmation. They take effect immediately.

Prerequisites

To complete these instructions, you need the following resources and privileges:

  • A valid Microsoft Entra tenant.
  • You run the requests in this article in a delegated context. You must complete the following steps:
    • Sign in to an API client such as Graph Explorer as a user with privileges to create applications in the tenant. The privileges to create permission grants might be limited or controlled in your tenant through admin-configured app consent policies.
    • In the app you're signed in to, consent to the Application.Read.All and AppRoleAssignment.ReadWrite.All delegated permissions on behalf of the signed-in user. You don't need to consent on behalf of your organization.
    • Get the object ID of the client service principal to which you grant app roles. In this article, the client service principal is identified by ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. In the Microsoft Entra admin center, expand the Identity menu > expand Applications > select Enterprise applications > App applications to find the client service principal. Select it and on the Overview page, copy the Object ID value.

Caution

Apps that have been granted the AppRoleAssignment.ReadWrite.All permission should only be accessed by appropriate users.

Step 1: Get the appRoles of the resource service principal

Before you can grant app roles, you must first identify the resource service principal that exposes the app roles you want to grant. App roles are defined in the appRoles object of a service principal. In this article, you use the Microsoft Graph service principal in your tenant as the resource service principal.

Request

The following request retrieves the app roles defined by the Microsoft Graph service principal in the tenant.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,appRoles

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(id,displayName,appId,appRoles)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "appRoles": [
                {
                    "allowedMemberTypes": [
                        "Application"
                    ],
                    "description": "Allows the app to read user profiles without a signed in user.",
                    "displayName": "Read all users' full profiles",
                    "id": "df021288-bdef-4463-88db-98f22de89214",
                    "isEnabled": true,
                    "origin": "Application",
                    "value": "User.Read.All"
                }
            ]
        }
    ]
}

Step 2: Grant an app role to a client service principal

In this step, you grant your app an app role that's exposed by Microsoft Graph, resulting in an app role assignment. From Step 1, the object ID of Microsoft Graph is 7ea9e944-71ce-443d-811c-71e8047b557a and the app role User.Read.All is identified by ID df021288-bdef-4463-88db-98f22de89214.

Request

The following request grants your client app (the principal of ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94) an app role of ID df021288-bdef-4463-88db-98f22de89214 that's exposed by a resource service principal of ID 7ea9e944-71ce-443d-811c-71e8047b557a.

Note

If you're using the Python SDK, import the following libraries:

from msgraph.generated.models.app_role_assignment import AppRoleAssignment
from msgraph.generated.models.service_principal import ServicePrincipal
POST https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo
Content-Type: application/json

{
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214"
}

Response

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo/$entity",
    "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
    "deletedDateTime": null,
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
    "createdDateTime": "2022-05-18T15:37:21.8215423Z",
    "principalDisplayName": "My application",
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "principalType": "ServicePrincipal",
    "resourceDisplayName": "Microsoft Graph",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
}

Confirm the app role assignment

To verify the principals with role assignments to the resource service principal, run the following request.

Request

GET https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo

Response

The response object includes a collection of app role assignments to your resource service principal and includes the app role assignment you created in the preceding request.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo",
    "value": [
        {
            "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
            "deletedDateTime": null,
            "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
            "createdDateTime": "2022-05-18T15:37:21.8997216Z",
            "principalDisplayName": "My application",
            "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "principalType": "ServicePrincipal",
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
        }
    ]
}

Step 3: Revoke an app role assignment from a client service principal

Request

DELETE https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo/47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M

Response

HTTP/1.1 204 No Content

Conclusion

You learned how to manage app role grants for a service principal. This method of granting permissions using Microsoft Graph is an alternative interactive consent and should be used with caution.

In this article, you learn how to grant and revoke delegated permissions for an app using Microsoft Graph. Delegated permissions, also called scopes, or OAuth2 permissions, allow an app to call an API on behalf of a signed-in user. Learn more about delegated permissions.

Caution

Be careful! Permissions granted programmatically are not subject to review or confirmation. They take effect immediately.

Prerequisites

To complete these instructions, you need the following resources and privileges:

  • A valid Microsoft Entra tenant.
  • You run the requests in this article as a user. You must complete the following steps:
    • Sign in to an API client such as Graph Explorer as a user with the Cloud Application Administrator Microsoft Entra role, which is the least privilege role for creating applications and granting consent to delegated permissions in the tenant. The privileges to create permission grants might be limited or controlled in your tenant through admin-configured app consent policies.
    • In the app you're signed in to, consent to the Application.Read.All, DelegatedPermissionGrant.ReadWrite.All delegated permissions on behalf of the signed-in user. You don't need to consent on behalf of your organization.
    • Get the object ID of the client service principal to which you grant delegated permissions on behalf of a user. In this article, the client service principal is identified by ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. In the Microsoft Entra admin center, expand the Identity menu > expand Applications > select Enterprise applications > App applications to find the client service principal. Select it and on the Overview page, copy the Object ID value.

Caution

Apps that have been granted the DelegatedPermissionGrant.ReadWrite.All permission should only be accessed by appropriate users.

Step 1: Get the delegated permissions of the resource service principal

Before you can grant delegated permissions, you must first identify the resource service principal that exposes the delegated permissions you want to grant. Delegated permissions are defined in the oauth2PermissionScopes object of a service principal. In this article, you use the Microsoft Graph service principal in your tenant as the resource service principal.

Request

The following request retrieves the delegated permissions defined by the Microsoft Graph service principal in the tenant.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,oauth2PermissionScopes

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(id,displayName,appId,oauth2PermissionScopes)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "oauth2PermissionScopes": [
                {
                    "adminConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user.",
                    "adminConsentDisplayName": "Read all users' full profiles",
                    "id": "a154be20-db9c-4678-8ab7-66f6cc099a59",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on your behalf.",
                    "userConsentDisplayName": "Read all users' full profiles",
                    "value": "User.Read.All"
                },
                {
                    "adminConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on behalf of the signed-in user.  Also allows the app to read calendar, conversations, files, and other group content for all groups the signed-in user can access. ",
                    "adminConsentDisplayName": "Read all groups",
                    "id": "5f8c59db-677d-491f-a6b8-5f174b11ec1d",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on your behalf.  Also allows the app to read calendar, conversations, files, and other group content for all groups you can access.  ",
                    "userConsentDisplayName": "Read all groups",
                    "value": "Group.Read.All"
                }                
            ]
        }
    ]
}

Step 2: Grant a delegated permission to the client service principal on behalf of a user

Request

In this step, you grant your app, on behalf of a user, a delegated permission that's exposed by Microsoft Graph, resulting in a delegated permission grant.

  • From Step 1, the object ID of Microsoft Graph in the tenant is 7ea9e944-71ce-443d-811c-71e8047b557a
  • The delegated permissions User.Read.All and Group.Read.All are identified by the globally unique IDs a154be20-db9c-4678-8ab7-66f6cc099a59 and 5f8c59db-677d-491f-a6b8-5f174b11ec1d respectively.
  • The principal is a user identified by ID 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5.
  • The client service principal is identified by ID b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. This is the object id of the service principal and not its appId.
POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "scope": "User.Read.All Group.Read.All"
}

While the preceding request grants consent on behalf of a single user, you can choose to grant consent on behalf of all users in the tenant. The request body is similar to the previous request body except with the following changes:

  • The consentType is AllPrincipals, indicating that you're consenting on behalf of all users in the tenant.
  • The principalId property isn't supplied or can be null.

An example request body for granting consent on behalf all users is as follows:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "AllPrincipals",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

Response

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants/$entity",
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

If you granted consent for all users in the tenant, the consentType in the response object would be AllPrincipals, and the principalId would be null.

Confirm the permission grant

To verify the delegated permissions assigned to the service principal on behalf of the user, you run the following request.

Request

GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94' and principalId eq '3fbd929d-8c56-4462-851e-0eb9a7b3a2a5' and consentType eq 'Principal'

Response

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants",
    "value": [
        {
            "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "consentType": "Principal",
            "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
            "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "scope": "User.Read.All Group.Read.All"
        }
    ]
}

Step 3: Revoke delegated permissions granted to a service principal on behalf of a user [Optional]

If a service principal has been granted multiple delegated permission grants on behalf of a user, you can choose to revoke either specific grants or all grants. Use this method to remove and revoke consent for the delegated permissions that you assigned to the client service principal.

  • To revoke one or some grants, run a PATCH request on the oauth2PermissionGrant object and specify only the delegated permissions to retain in the scope parameter.
  • To revoke all grants, run a DELETE request on the oauth2PermissionGrant object.

Request

The following request revokes all permission grants and retains only the User.Read.All permission grant. The permissions are removed and the consent that was previously granted is revoked.

PATCH https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl
Content-Type: application/json

{
    "scope": "User.Read.All"
}

Response

HTTP/1.1 204 No Content

Request

The following request revokes all permission grants for a service principal on behalf of a user.

DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl

Response

HTTP/1.1 204 No Content

Conclusion

You granted delegated permissions (or scopes) to a service principal. This method of granting permissions using Microsoft Graph is an alternative to interactive consent and should be used with caution.