Manage SharePoint Item Level Permissions using PowerShell

Occasionally we need to grant read permission for some set of users on certain document item and set edit permission to a particular user or group. To achieve this requirement, we need to add explicit permission for the particular list item. In this post I am going to share powershell scripts to add or remove item level permissions using CSOM (Client Object Model) and delete unique permissions from list item. To use CSOM in Powershell, we need to load the required Microsoft SharePoint Online SDK assembly files.

Summary

Find a list item or set of list items

The below powershell commands find a file item by its name, if you want to reset permissions for all list items you can set this caml query : $camlQuery.ViewXml = “<View Scope=’RecursiveAll’ />” and you can also write your own caml query to get different set of list items.

#Add required references to SharePoint client assembly to use CSOM 
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client") 
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime")  

#Proivde your details: SharePoint Site Url, UserName and Password   
$SiteUrl="https://spotenant.sharepoint.com/sites/TestSite" 
$UserName = "[email protected]"
$Password = 'adminpassword'
$SecPwd = $(ConvertTo-SecureString $Password -asplaintext -force)  

#Connecting site web
$ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteUrl)  
$credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($UserName,$SecPwd)  
$ctx.credentials = $credentials 
$ctx.Load($ctx.Web) 
$ctx.ExecuteQuery()

#Find list by Title
$list=$ctx.Web.Lists.GetByTitle("Documents") 
$ctx.Load($list) 
$ctx.ExecuteQuery()

#Find list item by Name
$itemName = "TestFile.txt"; 
$camlQuery = New-Object Microsoft.SharePoint.Client.CamlQuery 
$camlQuery.ViewXml ="<view><query><where><eq><fieldref name='FileLeafRef'><value type='Text'>" + $itemName + "</value></fieldref></eq></where></query></view>" 
# If you want to set permissions for all list items, you can use the below line (caml query to fetch all items) after commenting above line.
# $camlQuery.ViewXml ="<View Scope='RecursiveAll' />"  
$allItems=$list.GetItems($camlQuery) 
$ctx.Load($allItems) 
$ctx.ExecuteQuery()

# You can use the result $allItems in below examples.

Set item level permissions for user and SharePoint group :

By default all list items inherit the permissions from parent list, so to add unique permission for a particular list item, first we need to stop inheriting permissions (break the inheritance) of the particular item.

Add permission for user account:

The below powershell commands remove the unique permissions from the given list item (or list items) and set Contribute permission for the given user account.

# $allItems - You can get the required list items using the commands from above step.
foreach($listItem in $allItems) 
{ 
# Break inherited permissions. By default, the permissions are inherited from the above level.
$listItem.BreakRoleInheritance($false, $false); 
$ctx.Load($listItem)

#Find the given site user account
$editUser = $ctx.Web.EnsureUser("[email protected]") 
$ctx.Load($editUser)
$ctx.ExecuteQuery()

# Providing edit (contribute permission) access to the given site user.
$editAccess = $ctx.Web.RoleDefinitions.GetByName("Contribute")   
$editRole = New-Object Microsoft.SharePoint.Client.RoleDefinitionBindingCollection($ctx)   
$editRole.Add($editAccess)   
$editPermission = $listItem.RoleAssignments.Add($editUser, $editRole)   
$ctx.Load($editPermission) 
$ctx.ExecuteQuery()
Write-Host "Edit permission granted for the user:" $editUser.Title -foregroundcolor Green 
} 

Add permission for group :

You can use the below powershell commands to grant read access for the given sharepoint group.

foreach($listItem in $allItems) 
{ 
$listItem.BreakRoleInheritance($false, $false); 
$ctx.Load($listItem)

#Fecth the SharePoint groups for the site                         
$spGroups=$ctx.Web.SiteGroups 
$ctx.Load($spGroups)         
#Fecth the specific SharePoint group
$readGroup = $spGroups.GetByName("Test Site Visitors"); 
$ctx.Load($readGroup)
$ctx.ExecuteQuery()

# Providing read permission access to the members of the group "Test Site Visitors".    
$readAccess = $ctx.Web.RoleDefinitions.GetByName("Read")   
$readRole = New-Object Microsoft.SharePoint.Client.RoleDefinitionBindingCollection($ctx)   
$readRole.Add($readAccess)           
$readPermission = $listItem.RoleAssignments.Add($readGroup, $readRole)   
$ctx.Load($readPermission)              
$ctx.ExecuteQuery()
Write-Host "Read access granted for the group 'Test Site Visitors'" -foregroundcolor Green 
} 

Remove item level permissions

You can use the below csom based powershell commands to remove unique permissions from a particular SharePoint/SharePoint Online list item.

Remove user permission from list item:

foreach($listItem in $allItems) 
{ 
#Remove permissions for a given user
$spUser = $ctx.Web.EnsureUser("[email protected]") 
$ctx.Load($spUser)
$ctx.Load($listItem.RoleAssignments)
$listItem.RoleAssignments.GetByPrincipal($spUser).DeleteObject()
$ctx.ExecuteQuery()
Write-Host "Permissions removed for the given user:" $spUser.Title -foregroundcolor Green
}

Delete group permission from list item:

foreach($listItem in $allItems) 
{ 
#Remove permissions for a given site group
$spGroups=$ctx.Web.SiteGroups 
$ctx.Load($spGroups)         
$spGroup = $spGroups.GetByName("Test Site Visitors"); 
$ctx.Load($spGroup)
$ctx.Load($listItem.RoleAssignments)
$listItem.RoleAssignments.GetByPrincipal($spGroup).DeleteObject()
$ctx.ExecuteQuery()
Write-Host "Permissions removed for the given group:" $spGroup.Title -foregroundcolor Green
}

Delete all unique permissions

You can use the following powershell commands to remove all the explicit permissions from a list item and reset broken inheritance (recover inheritance).

foreach($listItem in $allItems) 
{ 
$listItem.ResetRoleInheritance()
$ctx.ExecuteQuery()
Write-Host "Unique permissions removed successfully and inheritance recovered." -foregroundcolor Green 
}

Advertisement

Leave a Comment