Applying item-level permissions in SharePoint Online ensures that only specific users or groups can access certain list items. PnP PowerShell simplifies managing these permissions efficiently.
What You’ll Learn:
✔️ How to connect to SharePoint Online
✔️ How to break inheritance on a list item
✔️ How to grant specific permissions to users/groups
✔️ How to remove user permissions from a list item
✔️ How to restore inherited permissions
Prerequisites
Before proceeding, ensure that:
PnP PowerShell is installed
You have SharePoint Online permissions
You know the list name and item ID
Step 1: Install and Import PnP PowerShell
If not already installed, install PnP PowerShell:
Install-Module -Name PnP.PowerShell -Scope CurrentUser -AllowClobber -Force
Then, import the module:
Import-Module PnP.PowerShell
PnP PowerShell is ready!
Step 2: Connect to SharePoint Online
To connect to your SharePoint site, use:
# Connect to SharePoint Online
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/yoursite" -Interactive
🔹 Replace "yourtenant" with your tenant name
🔹 Replace "yoursite" with the actual site name
Connected successfully!
Step 3: Break Inheritance on a List Item
By default, SharePoint list items inherit permissions from the list. To apply unique permissions, we must break inheritance:
# Define variables
$listName = "Project Tasks"
$itemId = 5 # Change to your item ID
# Break inheritance (without copying current permissions)
Set-PnPListItemPermission -List $listName -Identity $itemId -BreakInheritance -CopyRoleAssignments:$false -ClearSubscopes:$true
Write-Host "Inheritance broken for item ID $itemId"
🔹 -CopyRoleAssignments:$false → Prevents copying existing permissions
🔹 -ClearSubscopes:$true → Ensures no nested permissions exist
Item permissions are now unique!
Step 4: Grant Permissions to a User or Group
To assign permissions (e.g., Read, Contribute, Full Control) to a user or group:
# Define variables
$user = "user@yourtenant.onmicrosoft.com" # Change to the user's email
$role = "Contribute" # Change to "Read", "Edit", "Full Control" etc.
# Grant permissions
Grant-PnPListItemPermission -List $listName -Identity $itemId -User $user -Role $role
Write-Host "Granted $role permission to $user on item ID $itemId"
Valid permission roles:
- Read → View only
- Edit → Edit but not manage permissions
- Contribute → Edit & delete items
- Full Control → All permissions
Permissions assigned!
Step 5: Remove User Permissions from a List Item
To remove a user’s access from the list item:
# Define variables
$user = "user@yourtenant.onmicrosoft.com" # Change to the user's email
# Remove user permissions
Remove-PnPListItemPermission -List $listName -Identity $itemId -User $user
Write-Host "Removed $user's access from item ID $itemId"
User access removed!
Step 6: Restore Inherited Permissions
To reset item-level permissions and restore inheritance:
# Restore inherited permissions
Set-PnPListItemPermission -List $listName -Identity $itemId -ResetInheritance
Write-Host "Inheritance restored for item ID $itemId"
Item now follows list-level permissions!
Step 7: Apply Bulk Item-Level Permissions
To apply permissions to multiple items at once:
# Define variables
$listName = "Project Tasks"
$role = "Edit"
$user = "user@yourtenant.onmicrosoft.com"
# Get all items and apply permissions
$items = Get-PnPListItem -List $listName
foreach ($item in $items) {
$itemId = $item.Id
Set-PnPListItemPermission -List $listName -Identity $itemId -BreakInheritance -CopyRoleAssignments:$false -ClearSubscopes:$true
Grant-PnPListItemPermission -List $listName -Identity $itemId -User $user -Role $role
Write-Host "Applied permissions to item ID $itemId"
}
Write-Host "Bulk permissions applied successfully!"
Permissions applied to all list items!
Common Errors & Solutions
| Error | Cause | Solution |
|---|---|---|
Access Denied | Insufficient permissions | Ensure you have Full Control on the list |
Cannot find list | Incorrect list name | Verify the list name using Get-PnPList |
Invalid User | Email format is incorrect | Use Get-PnPUser to validate users |