Client Side Object Model (CSOM) List List Item Permission PnP PowerShell PowerShell SharePoint SharePoint Online 

SharePoint Online: How to Break Permission Inheritance using PowerShell?

Salaudeen Rajack 9 Comments , , ,

Requirement: Grant permissions at list or library level to users and groups in SharePoint Online. The particular user group has read access at the site level, and the requirement is to provide edit access rights on specified lists and libraries.

Break permission inheritance in SharePoint Online:

When you provide permissions at the site collection, any securable object under the hierarchy, such as sub-sites, lists, libraries, folders, documents, and items, inherits permissions from its parent. However, there are situations where you want to provide granular permission to any of these securable objects by assigning unique permissions.

Providing unique permissions at the list or item level consists of two steps: As a first step, stop inheriting permissions from the parent and then add permissions to users and/or groups. Here is how to break permission inheritance in SharePoint Online:

  1. Navigate to the SharePoint library where your documents are stored.
  2. Select the document >> Click on “Shared With” under the Manage group in the ribbon.
  3. On the permissions page, if the list is inheriting permissions from the parent, we have to break the permission inheritance by clicking the “Stop inheriting Permissions” button. Confirm the prompt once.
    sharepoint online stop inheriting permissions using PowerShell

Now, you can add or remove users to the particular list or list item permissions by clicking the Grant Permissions button from the Grant group.

Once you stop inheriting permissions – All users & groups are copied from the parent object to the child object. From this point, Any future permission changes made to the parent object no longer affect the child!

SharePoint Online unique permissions limit: The recommended limit is to have 5000 unique permissions, But the maximum number of unique permissions supported is 50,000.

PowerShell to Break Permission Inheritance for a List Item:

Here is the PowerShell for SharePoint Online to stop inheriting permissions from the parent.

#Load SharePoint CSOM Assemblies
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"

#Config Parameters
$SiteURL= "https://crescent.sharepoint.com/sites/projects"
$ListName="Projects"
$ItemID=1

#Setup Credentials to connect
$Cred = Get-Credential
$Cred = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.UserName,$Cred.Password)

#Setup the context
$Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteURL)
$Ctx.Credentials = $Cred
  
#Get the List and Item
$List=$Ctx.web.Lists.GetByTitle($ListName)
$Item=$List.GetItemByID($ItemID)

#stop inheriting permissions sharepoint online powershell
$Item.BreakRoleInheritance($True, $True)
$ctx.ExecuteQuery()

Similarly, you can break inheritance for all items in a List using PowerShell as:

#Load SharePoint Online Assemblies
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"

#Variables for Processing
$SiteURL = "https://Crescent.sharepoint.com/Sales"
$ListName = "Documents"

#Setup Credentials to connect
$Cred = Get-Credential
$Cred = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.UserName,$Cred.Password)
 
Try {
    #Setup the context
    $Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteURL)
    $Ctx.Credentials = $Cred
     
    #Get the List
    $List=$Ctx.Web.Lists.GetByTitle($ListName)
    $Ctx.Load($List)
    $Ctx.ExecuteQuery()
        
    #Get All List Items
    $Query = New-Object Microsoft.SharePoint.Client.CamlQuery
    $Query.ViewXml ="<View Scope='RecursiveAll' />"
    $ListItems = $List.GetItems($Query)
    $Ctx.Load($ListItems)
    $Ctx.ExecuteQuery()

    #Loop through each list item
    For($i=0;$i -lt $ListItems.Count;$i++)
    {        
        #Break Inheritance copying permissions from parent
        $ListItems[$i].BreakRoleInheritance($True, $False)
    } 
    $Ctx.ExecuteQuery() 
    write-host  -f Green "Permission Inheritance Broken for All Items in the List '$ListName'"
}
Catch {
    write-host -f Red "Error:" $_.Exception.Message
}

SharePoint Online: Stop Inheriting Permissions using PowerShell

Let’s add some error handling to this script and break the permission inheritance of a list.

#Load SharePoint CSOM Assemblies
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.dll"
Add-Type -Path "C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\ISAPI\Microsoft.SharePoint.Client.Runtime.dll"

#Config Parameters
$SiteURL= "https://crescent.sharepoint.com/sites/Marketing/"
$ListName="Documents"

#Setup Credentials to connect
$Cred = Get-Credential
$Cred = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.UserName,$Cred.Password)

Try {  
    #Setup the context
    $Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteURL)
    $Ctx.Credentials = $Cred
  
    #Get the List
    $List=$Ctx.web.Lists.GetByTitle($ListName)
    $Ctx.load($List)
    $List.Retrieve("HasUniqueRoleAssignments")
    $Ctx.ExecuteQuery()

    #Check if list is inheriting permissions; Break permissions of the list, if its inherited
    if($List.HasUniqueRoleAssignments -eq $False)
    {
        #sharepoint online break inheritance powershell 
        $List.BreakRoleInheritance($True,$True) #keep existing list permissions & Item level permissions
        $Ctx.ExecuteQuery()
        Write-host -f Green "Permission inheritance broken successfully!"
    }
    else
    {
        Write-Host -f Yellow "List is already using Unique permissions!"
    }
}
Catch {
    write-host -f Red "Error Granting Permissions!" $_.Exception.Message
}

To reset unique permissions and restore from the parent, you can use: SharePoint Online: PowerShell to Inherit Permissions

PnP PowerShell to Break Permission Inheritance of a List

Here is how to break inheritance in SharePoint Online using PowerShell PnP: 

#Config Variables
$SiteURL = "https://Crescent.sharepoint.com/sites/marketing"
$ListName ="Documents"

#Get Credentials to connect
$Cred = Get-Credential

Try {
    #Connect to PnP Online
    Connect-PnPOnline -Url $SiteURL -Credentials $Cred
    
    #Try to Get the List
    $List = Get-PnPList -Identity $ListName

    If($List)
    {
        #Break Permission Inheritance of the List
        Set-PnPList -Identity $ListName -BreakRoleInheritance -CopyRoleAssignments 
        Write-Host -f Green "Permission Inheritance Broken for List!"
    }
    Else
    {    
        Write-Host -f Yellow "Could not Find List '$ListName'"
    }    
}
catch {
    write-host "Error: $($_.Exception.Message)" -foregroundcolor Red
}

This script uses the “CopyRoleAssignments” switch to copy permissions from the parent. You can use “ClearSubscopes” to clear permissions!

Related Posts:

Salaudeen Rajack

Salaudeen Rajack - Information Technology Expert with Two decades of hands-on experience, specializing in SharePoint, PowerShell, Microsoft 365, and related products. Passionate about sharing the deep technical knowledge and experience to help others, through the real-world articles!

9 thoughts on “SharePoint Online: How to Break Permission Inheritance using PowerShell?”

  • Hello,

    Thank you for this article.
    May I ask if the above PS command works on a SharePoint list that has 8000 items?

    Thank you

    Reply

    • In larger lists, breaking inheritance will be a problem! As a workaround, move the items to a different list, break the permissions, and move them back.

      Reply

  • Rajack,
    I’m in a similar situation and was curious if it would now be possible to run this task in batches a la:
    https://www.sharepointdiary.com/2016/12/sharepoint-online-get-all-items-from-large-lists-powershell-csom.html

    Your help is greatly appreciated!

    Reply

  • Hi is there a way to break this inheritance on just some number of folders. For example I have a library and in that library i only want to break inheritance on lets say 3 folders deep but nothing below that so is that possible?

    Reply

  • Hi Salaudeen ,

    Any idea on how to break inheritance of large lists – list having more than 100K documents?

    Current script fails with list view threshold exceeded error.

    Reply

    • Yes! As of today: Moving documents/deleting-restoring to bring the count < 100,000 and then break the permission inheritance is the only solution.

      Reply

  • Hi Salaudeen,

    Thanks for great article.

    This works fine if we have small number of items in a list. However if a list contains more than 100K items, then this fails with list view threshold exceeded error.

    Any suggestion on how to break large list inheritance i.e. list having more than 100K items?

    Thanks in advance 🙂

    Reply

    • The only workaround as of today is: Reduce the number of items in the folder or library that you want to break permission inheritance. You can move some items out first, break permissions, and then move them back. (Or Delete items, break permissions and then restore them back from recycle bin).

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *