Skip to content

Commit c2b2b9f

Browse files
fabianhutzlifabianhutzli
committed
Add Get, Grant, Set and Revoke cmdlets for EntraID app file permissions
Implements Files.SelectedOperations.Selected support via the Microsoft Graph Drive API. Files can be addressed by path relative to the library root (e.g. Folder/file.docx) or by Graph drive item ID. The drive is resolved through the list's associated drive endpoint. Permission roles use the correct values (Read, Write, Owner). Documentation included.
1 parent fd8e757 commit c2b2b9f

11 files changed

Lines changed: 1658 additions & 0 deletions

‎documentation/Get-PnPEntraIDAppFilePermission.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
Module Name: PnP.PowerShell
3+
schema: 2.0.0
4+
applicable: SharePoint Online
5+
online version: https://pnp.github.io/powershell/cmdlets/Get-PnPEntraIDAppFilePermission.html
6+
external help file: PnP.PowerShell.dll-Help.xml
7+
title: Get-PnPEntraIDAppFilePermission
8+
---
9+
10+
# Get-PnPEntraIDAppFilePermission
11+
12+
## SYNOPSIS
13+
14+
**Required Permissions**
15+
16+
* Microsoft Graph API: Files.ReadWrite.All or Sites.ReadWrite.All
17+
18+
Returns Entra ID App permissions for a file in a document library.
19+
20+
## SYNTAX
21+
22+
### All Permissions
23+
```powershell
24+
Get-PnPEntraIDAppFilePermission -List <String> [-Path <String>] [-FileId <String>] [-Site <SitePipeBind>] [-Connection <PnPConnection>]
25+
```
26+
27+
### By Permission Id
28+
```powershell
29+
Get-PnPEntraIDAppFilePermission -PermissionId <String> -List <String> [-Path <String>] [-FileId <String>] [-Site <SitePipeBind>] [-Connection <PnPConnection>]
30+
```
31+
32+
### By App Display Name or App Id
33+
```powershell
34+
Get-PnPEntraIDAppFilePermission -AppIdentity <String> -List <String> [-Path <String>] [-FileId <String>] [-Site <SitePipeBind>] [-Connection <PnPConnection>]
35+
```
36+
37+
## DESCRIPTION
38+
39+
This cmdlet returns app permissions for a file in a document library. It is used in conjunction with the Entra ID SharePoint application permission `Files.SelectedOperations.Selected`.
40+
41+
The file can be identified by either:
42+
- `-Path`: the path to the file relative to the document library root (e.g. `Folder/SubFolder/file.docx`)
43+
- `-FileId`: the Graph drive item ID of the file
44+
45+
Exactly one of `-Path` or `-FileId` must be specified.
46+
47+
## EXAMPLES
48+
49+
### EXAMPLE 1
50+
```powershell
51+
Get-PnPEntraIDAppFilePermission -List "Documents" -Path "Contracts/2024/Agreement.docx"
52+
```
53+
54+
Returns all app permissions set on the file at the given path in the Documents library of the currently connected site.
55+
56+
### EXAMPLE 2
57+
```powershell
58+
Get-PnPEntraIDAppFilePermission -List "Documents" -Path "Report.xlsx" -Site https://contoso.sharepoint.com/sites/finance
59+
```
60+
61+
Returns all app permissions set on the file at the root of the Documents library on the specified site.
62+
63+
### EXAMPLE 3
64+
```powershell
65+
Get-PnPEntraIDAppFilePermission -List "Documents" -FileId "01ABC123DEF456GHI789"
66+
```
67+
68+
Returns all app permissions set on the file with the specified drive item ID.
69+
70+
### EXAMPLE 4
71+
```powershell
72+
Get-PnPEntraIDAppFilePermission -List "Documents" -Path "Report.xlsx" -PermissionId aTowaS50fG1zLnNwLmV4dHxlMzhjZmIzMS00
73+
```
74+
75+
Returns the specific permission details for the given permission id on the file.
76+
77+
### EXAMPLE 5
78+
```powershell
79+
Get-PnPEntraIDAppFilePermission -List "Documents" -Path "Report.xlsx" -AppIdentity "My App"
80+
```
81+
82+
Returns the specific permission details for the app with the provided display name on the file.
83+
84+
### EXAMPLE 6
85+
```powershell
86+
Get-PnPEntraIDAppFilePermission -List "Documents" -Path "Report.xlsx" -AppIdentity "89ea5c94-7736-4e25-95ad-3fa95f62b66e"
87+
```
88+
89+
Returns the specific permission details for the app with the provided app id on the file.
90+
91+
## PARAMETERS
92+
93+
### -AppIdentity
94+
Specify either the display name or the app id (client id) to filter the returned permissions to a specific app.
95+
96+
```yaml
97+
Type: String
98+
Parameter Sets: By App Display Name or App Id
99+
100+
Required: True
101+
Position: Named
102+
Default value: None
103+
Accept pipeline input: False
104+
Accept wildcard characters: False
105+
```
106+
107+
### -Connection
108+
Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
109+
110+
```yaml
111+
Type: PnPConnection
112+
Parameter Sets: (All)
113+
114+
Required: False
115+
Position: Named
116+
Default value: None
117+
Accept pipeline input: False
118+
Accept wildcard characters: False
119+
```
120+
121+
### -FileId
122+
The Graph drive item ID of the file. Use this as an alternative to `-Path` when you already know the drive item ID. Mutually exclusive with `-Path`.
123+
124+
```yaml
125+
Type: String
126+
Parameter Sets: (All)
127+
128+
Required: False
129+
Position: Named
130+
Default value: None
131+
Accept pipeline input: False
132+
Accept wildcard characters: False
133+
```
134+
135+
### -List
136+
The document library containing the file. Accepts a list GUID or display name.
137+
138+
```yaml
139+
Type: String
140+
Parameter Sets: (All)
141+
142+
Required: True
143+
Position: Named
144+
Default value: None
145+
Accept pipeline input: False
146+
Accept wildcard characters: False
147+
```
148+
149+
### -Path
150+
The path to the file relative to the document library root (e.g. `Folder/SubFolder/file.docx` or just `file.docx` for a file at the root). Mutually exclusive with `-FileId`.
151+
152+
```yaml
153+
Type: String
154+
Parameter Sets: (All)
155+
156+
Required: False
157+
Position: Named
158+
Default value: None
159+
Accept pipeline input: False
160+
Accept wildcard characters: False
161+
```
162+
163+
### -PermissionId
164+
If specified, the permission with that id will be retrieved.
165+
166+
```yaml
167+
Type: String
168+
Parameter Sets: By Permission Id
169+
170+
Required: True
171+
Position: Named
172+
Default value: None
173+
Accept pipeline input: False
174+
Accept wildcard characters: False
175+
```
176+
177+
### -Site
178+
Optional url of a site to retrieve the permissions for. Defaults to the currently connected site.
179+
180+
```yaml
181+
Type: SitePipeBind
182+
Parameter Sets: (All)
183+
184+
Required: False
185+
Position: Named
186+
Default value: Currently connected site
187+
Accept pipeline input: False
188+
Accept wildcard characters: False
189+
```
190+
191+
## RELATED LINKS
192+
193+
[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

‎documentation/Grant-PnPEntraIDAppFilePermission.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
Module Name: PnP.PowerShell
3+
schema: 2.0.0
4+
applicable: SharePoint Online
5+
online version: https://pnp.github.io/powershell/cmdlets/Grant-PnPEntraIDAppFilePermission.html
6+
external help file: PnP.PowerShell.dll-Help.xml
7+
title: Grant-PnPEntraIDAppFilePermission
8+
---
9+
10+
# Grant-PnPEntraIDAppFilePermission
11+
12+
## SYNOPSIS
13+
14+
**Required Permissions**
15+
16+
* Microsoft Graph API: Files.ReadWrite.All or Sites.ReadWrite.All
17+
18+
Adds permissions for a given Entra ID application registration on a file in a document library.
19+
20+
## SYNTAX
21+
22+
```powershell
23+
Grant-PnPEntraIDAppFilePermission -AppId <Guid> -DisplayName <String> -Permissions <Read|Write|Owner> -List <String> [-Path <String>] [-FileId <String>] [-Site <SitePipeBind>] [-Connection <PnPConnection>]
24+
```
25+
26+
## DESCRIPTION
27+
28+
This cmdlet adds permissions for a given Entra ID application registration on a file in a document library. It is used in conjunction with the Entra ID SharePoint application permission `Files.SelectedOperations.Selected`.
29+
30+
The file can be identified by either:
31+
- `-Path`: the path to the file relative to the document library root (e.g. `Folder/SubFolder/file.docx`)
32+
- `-FileId`: the Graph drive item ID of the file
33+
34+
Exactly one of `-Path` or `-FileId` must be specified.
35+
36+
## EXAMPLES
37+
38+
### EXAMPLE 1
39+
```powershell
40+
Grant-PnPEntraIDAppFilePermission -AppId "aa37b89e-75a7-47e3-bdb6-b763851c61b6" -DisplayName "TestApp" -Permissions Read -List "Documents" -Path "Contracts/Agreement.docx"
41+
```
42+
43+
Grants the Entra ID application registration Read access on the file at the specified path in the Documents library of the currently connected site.
44+
45+
### EXAMPLE 2
46+
```powershell
47+
Grant-PnPEntraIDAppFilePermission -AppId "aa37b89e-75a7-47e3-bdb6-b763851c61b6" -DisplayName "TestApp" -Permissions Write -List "Documents" -FileId "01ABC123DEF456GHI789"
48+
```
49+
50+
Grants Write access on the file with the specified drive item ID in the Documents library.
51+
52+
### EXAMPLE 3
53+
```powershell
54+
Grant-PnPEntraIDAppFilePermission -AppId "aa37b89e-75a7-47e3-bdb6-b763851c61b6" -DisplayName "TestApp" -Permissions Owner -List "Documents" -Path "Report.xlsx" -Site https://contoso.sharepoint.com/sites/finance
55+
```
56+
57+
Grants Owner access on the specified file in the Documents library of the given site collection.
58+
59+
## PARAMETERS
60+
61+
### -AppId
62+
The app id (client id) of the Entra ID application registration to grant permission for.
63+
64+
```yaml
65+
Type: Guid
66+
Parameter Sets: (All)
67+
68+
Required: True
69+
Position: Named
70+
Default value: None
71+
Accept pipeline input: False
72+
Accept wildcard characters: False
73+
```
74+
75+
### -Connection
76+
Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
77+
78+
```yaml
79+
Type: PnPConnection
80+
Parameter Sets: (All)
81+
82+
Required: False
83+
Position: Named
84+
Default value: None
85+
Accept pipeline input: False
86+
Accept wildcard characters: False
87+
```
88+
89+
### -DisplayName
90+
The display name to associate with the permission. Used for visual reference only; does not need to match the application name in Entra ID.
91+
92+
```yaml
93+
Type: String
94+
Parameter Sets: (All)
95+
96+
Required: True
97+
Position: Named
98+
Default value: None
99+
Accept pipeline input: False
100+
Accept wildcard characters: False
101+
```
102+
103+
### -FileId
104+
The Graph drive item ID of the file. Use this as an alternative to `-Path` when you already know the drive item ID. Mutually exclusive with `-Path`.
105+
106+
```yaml
107+
Type: String
108+
Parameter Sets: (All)
109+
110+
Required: False
111+
Position: Named
112+
Default value: None
113+
Accept pipeline input: False
114+
Accept wildcard characters: False
115+
```
116+
117+
### -List
118+
The document library containing the file. Accepts a list GUID or display name.
119+
120+
```yaml
121+
Type: String
122+
Parameter Sets: (All)
123+
124+
Required: True
125+
Position: Named
126+
Default value: None
127+
Accept pipeline input: False
128+
Accept wildcard characters: False
129+
```
130+
131+
### -Path
132+
The path to the file relative to the document library root (e.g. `Folder/SubFolder/file.docx` or just `file.docx` for a file at the root). Mutually exclusive with `-FileId`.
133+
134+
```yaml
135+
Type: String
136+
Parameter Sets: (All)
137+
138+
Required: False
139+
Position: Named
140+
Default value: None
141+
Accept pipeline input: False
142+
Accept wildcard characters: False
143+
```
144+
145+
### -Permissions
146+
The permissions to grant for the Entra ID application registration. Can be Read, Write, or Owner.
147+
148+
```yaml
149+
Type: String
150+
Parameter Sets: (All)
151+
152+
Required: True
153+
Accepted values: Read, Write, Owner
154+
Position: Named
155+
Default value: None
156+
Accept pipeline input: False
157+
Accept wildcard characters: False
158+
```
159+
160+
### -Site
161+
Optional url of a site to grant the permissions on. Defaults to the currently connected site.
162+
163+
```yaml
164+
Type: SitePipeBind
165+
Parameter Sets: (All)
166+
167+
Required: False
168+
Position: Named
169+
Default value: Currently connected site
170+
Accept pipeline input: False
171+
Accept wildcard characters: False
172+
```
173+
174+
## RELATED LINKS
175+
176+
[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

0 commit comments

Comments
 (0)