Skip to content

Commit aac8d53

Browse files
SteveMutungi254SteveMutungi254
authored
Merge pull request #637 from msewaweru/freshness-grant-api-permissions
Converted the articles to use zone pivots and doing a freshness check
2 parents 5566edd + 2715751 commit aac8d53

7 files changed

+359
-367
lines changed

‎.openpublishing.redirection.json

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,17 @@
22
"redirections": [
33
{
44
"source_path": "microsoftgraph/graph-powershell-1.0/Microsoft.Graph.Calendar/Get-MgPlace.md",
5-
"redirect_url": "https://learn.microsoft.com/en-us/powershell/microsoftgraph/?view=graph-powershell-1.0",
5+
"redirect_url": "https://learn.microsoft.com//powershell/microsoftgraph/",
6+
"redirect_document_id": false
7+
},
8+
{
9+
"source_path": "microsoftgraph/docs-conceptual/tutorial-grant-delegated-api-permissions.md",
10+
"redirect_url": "https://learn.microsoft.com/powershell/microsoftgraph/how-to-grant-revoke-api-permissions&pivots=grant-delegated-permissions",
11+
"redirect_document_id": false
12+
},
13+
{
14+
"source_path": "microsoftgraph/docs-conceptual/tutorial-grant-app-only-api-permissions.md",
15+
"redirect_url": "https://learn.microsoft.com/powershell/microsoftgraph/how-to-grant-revoke-api-permissions&pivots=grant-application-permissions",
616
"redirect_document_id": false
717
},
818
{

‎microsoftgraph/docs-conceptual/how-to-grant-revoke-api-permissions.md

Lines changed: 339 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,339 @@
1+
---
2+
title: "Grant and revoke API permissions programmatically in Microsoft Entra ID"
3+
description: "Learn how to programmatically grant and revoke delegated and application API permissions for an app using Microsoft Graph PowerShell."
4+
ms.topic: how-to
5+
ms.date: 01/27/2025
6+
author: msewaweru
7+
manager: CelesteDG
8+
ms.author: eunicewaweru
9+
ms.reviewer: jawoods, phsignor
10+
zone_pivot_groups: graph-powershell-grant-api-permissions
11+
zone_pivot_group_filename: microsoftgraph/zone-pivot-groups.json
12+
13+
#customer intent: As an IT admin managing permissions in Microsoft Entra ID, I want to learn how to grant and revoke API permissions for an app using Microsoft Graph PowerShell, to automate permission management tasks and ensure efficient and secure access control in my organization.
14+
---
15+
16+
# Grant and revoke API permissions in Microsoft Entra ID
17+
18+
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 other objects. Using Microsoft Graph PowerShell cmdlets to directly create permission grants is a programmatic alternative to [interactive consent](/azure/active-directory/manage-apps/consent-and-permissions-overview). This can be useful for automation scenarios, bulk management, or other custom operations in your organization.
19+
20+
<!-- start the grant-delegated-permissions zone -->
21+
::: zone pivot="grant-delegated-permissions"
22+
23+
In this article, you grant and revoke delegated permissions that are exposed by an API to an app. Delegated permissions, also called scopes or OAuth2 permissions, allow an app to call an API on behalf of a signed-in user.
24+
25+
## Prerequisites
26+
27+
To successfully complete this guide, make sure you have the required prerequisites:
28+
29+
1. A working Microsoft Entra tenant.
30+
1. Microsoft Graph PowerShell SDK is installed. Follow the [Install the Microsoft Graph PowerShell SDK](installation.md) guide to install the SDK.
31+
1. Microsoft Graph PowerShell using a [Privileged Role Administrator](/entra/identity/role-based-access-control/permissions-reference#privileged-role-administrator), [Application Administrator](/entra/identity/role-based-access-control/permissions-reference#application-administrator), or a [Cloud Application Administrator](/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator) in the tenant and the appropriate permissions. For this guide, the `Application.Read.All` and `DelegatedPermissionGrant.ReadWrite.All` delegated permissions are required. To set the permissions in Microsoft Graph PowerShell, run:
32+
33+
```powershell
34+
Connect-MgGraph -Scopes "Application.ReadWrite.All", "DelegatedPermissionGrant.ReadWrite.All"
35+
```
36+
37+
>[!Caution]
38+
>The `DelegatedPermissionGrant.ReadWrite.All` permission allows an app or a service to manage permission grants and elevate privileges for any app, user, or group in your organization. Only appropriate users should access apps that have been granted this permission.
39+
40+
## Step 1: Get the delegated permissions of the resource service principal
41+
42+
Before you can grant delegated permissions, you must first identify the delegated permissions to grant and the resource service principal that exposes the delegated permissions. Delegated permissions are defined in the `oauth2PermissionScopes` object of a service principal.
43+
44+
In this article, you use the `Microsoft Graph` service principal in the tenant as your resource service principal.
45+
46+
```powershell
47+
Get-MgServicePrincipal -Filter "displayName eq 'Microsoft Graph'" -Property Oauth2PermissionScopes | Select -ExpandProperty Oauth2PermissionScopes | Format-List
48+
```
49+
50+
```Output
51+
AdminConsentDescription : Allows the app to read and write the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user.
52+
AdminConsentDisplayName : Read and write all users' full profiles
53+
Id : 204e0828-b5ca-4ad8-b9f3-f32a958e7cc4
54+
IsEnabled : True
55+
Origin :
56+
Type : Admin
57+
UserConsentDescription : Allows the app to read and write the full set of profile properties, reports, and managers of other users in your organization, on your behalf.
58+
UserConsentDisplayName : Read and write all users' full profiles
59+
Value : User.ReadWrite.All
60+
AdditionalProperties : {}
61+
62+
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,
63+
and other group content for all groups the signed-in user can access.
64+
AdminConsentDisplayName : Read all groups
65+
Id : 5f8c59db-677d-491f-a6b8-5f174b11ec1d
66+
IsEnabled : True
67+
Origin :
68+
Type : Admin
69+
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
70+
content for all groups you can access.
71+
UserConsentDisplayName : Read all groups
72+
Value : Group.Read.All
73+
AdditionalProperties : {}
74+
```
75+
76+
>[!NOTE]
77+
>The output has been truncated for readability.
78+
79+
## Step 2: Create a client service principal
80+
81+
The first step in granting consent is to [create the service principal for the app that you grant permissions](/powershell/module/microsoft.graph.applications/new-mgserviceprincipal). To do so, you need the `App Id` of your application.
82+
83+
<a name='register-an-application-with-azure-ad'></a>
84+
85+
### Register an application with Microsoft Entra ID
86+
87+
If the application isn't available, register an application with Microsoft Entra ID.
88+
89+
```powershell
90+
New-MgApplication -DisplayName 'My application' |
91+
Format-List Id, DisplayName, AppId, SignInAudience, PublisherDomain
92+
```
93+
94+
```Output
95+
Id : 40cbfad6-f138-4fb4-9e7f-5a44044efbd6
96+
DisplayName : My application
97+
AppId : 00001111-aaaa-2222-bbbb-3333cccc4444
98+
SignInAudience : AzureADandPersonalMicrosoftAccount
99+
PublisherDomain : Contoso.com
100+
```
101+
102+
### Create a service principal for the application
103+
104+
```powershell
105+
New-MgServicePrincipal -AppId '00001111-aaaa-2222-bbbb-3333cccc4444' |
106+
Format-List Id, DisplayName, AppId, SignInAudience
107+
```
108+
109+
```Output
110+
Id : 11112222-bbbb-3333-cccc-4444dddd5555
111+
DisplayName : My application
112+
AppId : 00001111-aaaa-2222-bbbb-3333cccc4444
113+
SignInAudience : AzureADandPersonalMicrosoftAccount
114+
```
115+
116+
## Step 3: Grant delegated permissions to the client enterprise application
117+
118+
To create a delegated permission grant, you need the following information:
119+
120+
1. **ClientId** - object ID of the client service principal to be authorized to act on behalf of the user. In this case, the service principal we created in step 2.
121+
1. **ConsentType** - `AllPrincipals` to authorize all users in the tenant or `Principal` for a single user.
122+
1. **PrincipalId** - `Null` for *AllPrincipals* consents or ID of the user for *Principal* consents.
123+
1. **ResourceId** - object ID of the service principal representing the resource app in the tenant.
124+
1. **Scope** - space-delimited list of permission claim values, for example `User.Read.All`.
125+
126+
In this example, you grant the `Group.Read.All` scope to the service principal and grant consent on behalf of all users in the tenant.
127+
128+
```powershell
129+
$resource = Get-MgServicePrincipal -Filter "displayName eq 'Microsoft Graph'"
130+
$params = @{
131+
"ClientId" = "11112222-bbbb-3333-cccc-4444dddd5555"
132+
"ConsentType" = "AllPrincipals"
133+
"ResourceId" = $resource.Id
134+
"Scope" = "Group.Read.All"
135+
}
136+
137+
New-MgOauth2PermissionGrant -BodyParameter $params |
138+
Format-List Id, ClientId, ConsentType, ExpiryTime, PrincipalId, ResourceId, Scope
139+
```
140+
141+
```Output
142+
Id : DXfBIt8w50mnY_OdLvmzadDQeqbRp9tKjNm83QyGbTw
143+
ClientId : 11112222-bbbb-3333-cccc-4444dddd5555
144+
ConsentType : AllPrincipals
145+
PrincipalId :
146+
ResourceId : 11112222-bbbb-3333-cccc-4444dddd5555
147+
Scope : Group.Read.All
148+
```
149+
150+
To confirm the delegated permissions assigned to the service principal on behalf of the user, you run the following command.
151+
152+
```powershell
153+
Get-MgOauth2PermissionGrant -Filter "clientId eq '11112222-bbbb-3333-cccc-4444dddd5555' and consentType eq 'AllPrincipals'" | Format-List
154+
```
155+
156+
```Output
157+
ClientId : 11112222-bbbb-3333-cccc-4444dddd5555
158+
ConsentType : AllPrincipals
159+
Id : DXfBIt8w50mnY_OdLvmzadDQeqbRp9tKjNm83QyGbTw
160+
PrincipalId :
161+
ResourceId : 11112222-bbbb-3333-cccc-4444dddd5555
162+
Scope : Group.Read.All User.Read.All
163+
AdditionalProperties : {}
164+
```
165+
166+
### Step 4: Grant more delegated permissions to the enterprise application
167+
168+
You can add more permissions to an existing oauth2PermissionGrant object.
169+
170+
To add the `User.Read.All` scope to the oauthPermissionGrant object, run:
171+
172+
```powershell
173+
$params = @{
174+
Scope = "Group.Read.All User.Read.All"
175+
}
176+
177+
Update-MgOauth2PermissionGrant -OAuth2PermissionGrantId 'DXfBIt8w50mnY_OdLvmzadDQeqbRp9tKjNm83QyGbTw' -BodyParameter $params
178+
```
179+
180+
### Step 5: Revoke delegated permissions granted to an enterprise application
181+
182+
If a service principal has been granted multiple delegated permission grants, you can choose to revoke either specific grants or all grants.
183+
184+
- To revoke one or more grants, update oauthPermissionGrant object and specify only the delegated permissions to retain in the **scope** parameter. For example, to revoke the `User.read.All` permission, run:
185+
186+
```powershell
187+
$params = @{
188+
Scope = "Group.Read.All"
189+
}
190+
191+
Update-MgOauth2PermissionGrant -OAuth2PermissionGrantId 'DXfBIt8w50mnY_OdLvmzadDQeqbRp9tKjNm83QyGbTw' -BodyParameter $params
192+
```
193+
194+
- Use [Remove-MgOauth2PermissionGrant](/powershell/module/microsoft.graph.identity.signins/remove-mgoauth2permissiongrant) to revoke all grants.
195+
196+
```powershell
197+
Remove-MgOauth2PermissionGrant -OAuth2PermissionGrantId 'DXfBIt8w50mnY_OdLvmzadDQeqbRp9tKjNm83QyGbTw'
198+
```
199+
200+
When a delegated permission grant is deleted, the access it granted is revoked. Existing access tokens will continue to be valid for their lifetime, but new access tokens won't be granted for the delegated permissions identified in the deleted oAuth2PermissionGrant.
201+
202+
::: zone-end
203+
<!-- end the grant-delegated-permissions zone -->
204+
205+
<!-- start the grant-application-permissions zone -->
206+
::: zone pivot="grant-application-permissions"
207+
208+
In this article, you grant app roles that are exposed by an API to an app. App roles, also called application permissions, or direct access permissions, allow an app to call an API with its own identity.
209+
210+
## Prerequisites
211+
212+
To successfully complete this guide, make sure you have the required prerequisites:
213+
214+
1. A working Microsoft Entra tenant.
215+
1. Microsoft Graph PowerShell SDK is installed. Follow the [Install the Microsoft Graph PowerShell SDK](installation.md) guide to install the SDK.
216+
1. Microsoft Graph PowerShell using a [Privileged Role Administrator](/entra/identity/role-based-access-control/permissions-reference#privileged-role-administrator) in the tenant and the appropriate permissions. For this guide, the `Application.Read.All` and `AppRoleAssignment.ReadWrite.All` delegated permissions are required. To set the permissions in Microsoft Graph PowerShell, run:
217+
218+
```powershell
219+
Connect-MgGraph -Scopes "Application.ReadWrite.All", "AppRoleAssignment.ReadWrite.All"
220+
```
221+
222+
>[!Caution]
223+
>The `AppRoleAssignment.ReadWrite.All` permission allows an app or a service to manage permission grants and elevate privileges for any app, user, or group in your organization. Only appropriate users should access apps that have been granted this permission.
224+
225+
## Step 1: Get the app roles of the resource service principal
226+
227+
Before you can grant app roles, you must first identify the app roles to grant and the resource service principal that exposes the app roles. App roles are defined in the `appRoles` object of a service principal.
228+
229+
In this article, you use the `Microsoft Graph` service principal in the tenant as your resource service principal.
230+
231+
```powershell
232+
Get-MgServicePrincipal -Filter "displayName eq 'Microsoft Graph'" -Property AppRoles | Select-Object -ExpandProperty appRoles | Format-List
233+
```
234+
235+
```Output
236+
AllowedMemberTypes : {Application}
237+
Description : Allows the app to read and update user profiles without a signed in user.
238+
DisplayName : Read and write all users' full profiles
239+
Id : 741f803b-c850-494e-b5df-cde7c675a1ca
240+
IsEnabled : True
241+
Origin : Application
242+
Value : User.ReadWrite.All
243+
AdditionalProperties : {}
244+
245+
AllowedMemberTypes : {Application}
246+
Description : Allows the app to read user profiles without a signed in user.
247+
DisplayName : Read all users' full profiles
248+
Id : df021288-bdef-4463-88db-98f22de89214
249+
IsEnabled : True
250+
Origin : Application
251+
Value : User.Read.All
252+
AdditionalProperties : {}
253+
```
254+
255+
>[!NOTE]
256+
>The output has been truncated for readability.
257+
258+
## Step 2: Create a client service principal
259+
260+
The first step in granting consent is to [create the service principal for the app that you grant permissions](/powershell/module/microsoft.graph.applications/new-mgserviceprincipal). To do so, you need the `App Id` of your application.
261+
262+
<a name='register-an-application-with-azure-ad'></a>
263+
264+
### Register an application with Microsoft Entra ID
265+
266+
If the application isn't available, register an application with Microsoft Entra ID.
267+
268+
```powershell
269+
New-MgApplication -DisplayName 'My application' |
270+
Format-List Id, DisplayName, AppId, SignInAudience, PublisherDomain
271+
```
272+
273+
```Output
274+
Id : 40cbfad6-f138-4fb4-9e7f-5a44044efbd6
275+
DisplayName : My application
276+
AppId : 00001111-aaaa-2222-bbbb-3333cccc4444
277+
SignInAudience : AzureADandPersonalMicrosoftAccount
278+
PublisherDomain : Contoso.com
279+
```
280+
281+
### Create a service principal for the application
282+
283+
```powershell
284+
New-MgServicePrincipal -AppId '00001111-aaaa-2222-bbbb-3333cccc4444' |
285+
Format-List Id, DisplayName, AppId, SignInAudience
286+
```
287+
288+
```Output
289+
Id : 11112222-bbbb-3333-cccc-4444dddd5555
290+
DisplayName : My application
291+
AppId : 00001111-aaaa-2222-bbbb-3333cccc4444
292+
SignInAudience : AzureADandPersonalMicrosoftAccount
293+
```
294+
295+
## Step 3: Assign an app role to the client enterprise application
296+
297+
In this step, you assign an app role exposed by your resource app to the service principal we created in step 2. To create an app role assignment, you need the following information:
298+
299+
1. **PrincipalId** - object Id of the service principal to be authorized for direct access.
300+
1. **ResourceId** - object Id of the service principal representing the resource app in your tenant.
301+
1. **AppRoleId** - Id of the app role to be assigned, defined on the service principal representing the resource.
302+
303+
304+
305+
```powershell
306+
$resource = Get-MgServicePrincipal -Filter "displayName eq 'Microsoft Graph'"
307+
$roleId = $resource.AppRoles | Where-Object { $_.Value -eq 'User.Read.All' } | Select-Object -ExpandProperty Id
308+
$params = @{
309+
"PrincipalId" ="11112222-bbbb-3333-cccc-4444dddd5555"
310+
"ResourceId" = $resource.Id
311+
"AppRoleId" = $roleId
312+
}
313+
314+
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $resource.Id -BodyParameter $params |
315+
Format-List Id, AppRoleId, CreatedDateTime, PrincipalDisplayName, PrincipalId, PrincipalType, ResourceDisplayName
316+
```
317+
318+
The `ServicePrincipalId` must always be same as the `ResourceId`, which references the service principal that exposes the app roles that you want to assign to the `PrincipalId`.
319+
320+
```Output
321+
Id : DXfBIt8w50mnY_OdLvmzaUbMIDgaM6pCpU8rpQHnPf0
322+
AppRoleId : df021288-bdef-4463-88db-98f22de89214
323+
CreatedDateTime : 10/31/2022 11:00:47 AM
324+
PrincipalDisplayName : My application
325+
PrincipalId : 11112222-bbbb-3333-cccc-4444dddd5555
326+
PrincipalType : ServicePrincipal
327+
ResourceDisplayName : Microsoft Graph
328+
```
329+
330+
## Step 4: Revoke an app role assignment from a client enterprise application
331+
332+
To revoke the app roles assigned in step 3, run:
333+
334+
```powershell
335+
Remove-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId '11112222-bbbb-3333-cccc-4444dddd5555' -AppRoleAssignmentId 'DXfBIt8w50mnY_OdLvmzaUbMIDgaM6pCpU8rpQHnPf0'
336+
```
337+
338+
::: zone-end
339+
<!-- end the grant-application-permissions zone -->

‎microsoftgraph/docs-conceptual/index.yml

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -65,10 +65,8 @@ landingContent:
6565
url: how-to-assign-microsoft-entra-roles-in-pim.md
6666
- text: Manage PIM policies
6767
url: how-to-manage-pim-policies.md
68-
- text: Grant and revoke delegated permissions
69-
url: tutorial-grant-delegated-api-permissions.md
70-
- text: Grant and revoke app roles
71-
url: tutorial-grant-app-only-api-permissions.md
68+
- text: Grant and revoke API permissions
69+
url: how-to-grant-revoke-api-permissions.md
7270

7371

7472
# Card

‎microsoftgraph/docs-conceptual/toc.yml

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,7 @@
2929
- name: Manage PIM policies
3030
href: how-to-manage-pim-policies.md
3131
- name: Grant API permissions
32-
items:
33-
- name: Manage delegated permissions
34-
href: tutorial-grant-delegated-api-permissions.md
35-
- name: Manage app roles
36-
href: tutorial-grant-app-only-api-permissions.md
32+
href: how-to-grant-revoke-api-permissions.md
3733
- name: Query parameters
3834
items:
3935
- name: Use query parameters

0 commit comments

Comments
 (0)