SharePoint Online: How to Break Permission Inheritance using PowerShell?

Requirement: Grant permissions at list or library level to users and groups in SharePoint online. The particular user group has read access at 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, and libraries, folders, documents & items inherit their permissions from their 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:

  • Navigate to the SharePoint library where your documents are stored
  • Select the document >> Click on “Shared With” under Manage group in the ribbon
  • 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 Grant Permissions button from 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 affects the child!

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://crescenttech.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 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 {

    #Helper function to get nongeneric properties of the Object in CSOM   
    Function Invoke-LoadMethod() {
    param( [Microsoft.SharePoint.Client.ClientObject]$Object, [string]$PropertyName ) 
       $ctx = $Object.Context
       $load = [Microsoft.SharePoint.Client.ClientContext].GetMethod("Load") 
       $type = $Object.GetType()
       $clientLoad = $load.MakeGenericMethod($type)

       $Parameter = [System.Linq.Expressions.Expression]::Parameter(($type), $type.Name)
       $Expression = [System.Linq.Expressions.Expression]::Lambda(
                [System.Linq.Expressions.Expression]::Convert([System.Linq.Expressions.Expression]::PropertyOrField($Parameter,$PropertyName),
                [System.Object] ), $($Parameter))

       $ExpressionArray = [System.Array]::CreateInstance($Expression.GetType(), 1)
       $ExpressionArray.SetValue($Expression, 0)
       $clientLoad.Invoke($ctx,@($Object,$ExpressionArray))
    }
  
    #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)
    Invoke-LoadMethod -Object $List -PropertyName "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 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://crescenttech.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 “CopyRoleAssignments” switch to copy permissions from the parent. You can use “ClearSubscopes” to clear permissions!

Related Posts:

Salaudeen Rajack

Information Technology Professional with Two decades of SharePoint Experience.

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

  • December 20, 2020 at 7:01 AM

    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
  • December 20, 2020 at 7:00 AM

    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

Leave a Reply