In this post, I am going to show you how to find everything in a SharePoint site that does not inherit its permissions, and who can actually get at it. There is a full script at the end if you just want to run something.
Broken inheritance is where oversharing hides. A site can look tidy at the top and still have one folder shared with everyone, because somebody clicked Share eighteen months ago. Nothing in the interface shows you all of them at once.
Run against a real site on PnP.PowerShell 2.12.0. Output below is what came back.
Permissions break at four levels
Site, list, folder and item. You have to check all four, and the checks are different at each.
The site
$web = Get-PnPWeb
Get-PnPProperty -ClientObject $web -Property HasUniqueRoleAssignments
$web.HasUniqueRoleAssignmentsTrueDo not panic at that. The top web of a site collection has nothing above it to inherit from, so it always reports True. It only means something on a subsite.
The important thing to note is Get-PnPProperty. Most permission properties are not loaded when you fetch an object – you have to ask for them separately. Skip that line and HasUniqueRoleAssignments comes back empty rather than throwing, which is worse, because your report quietly finds nothing.
Lists and libraries
Get-PnPList | Where-Object { -not $_.Hidden } | ForEach-Object {
[pscustomobject]@{
List = $_.Title
Unique = Get-PnPProperty -ClientObject $_ -Property HasUniqueRoleAssignments
}
}List Unique
---- ------
Departments False
Documents False
Events False
Project Documents False
Projects False
Site Pages False
Style Library FalseItems, and why this is the slow part
Get-PnPListItem -List 'Projects' -PageSize 500 | ForEach-Object {
$unique = Get-PnPProperty -ClientObject $_ -Property HasUniqueRoleAssignments
if ($unique) { [pscustomobject]@{ Id = $_.Id; Title = $_['Title'] } }
}Id Title
-- -----
3 Project 03That took 6.2 seconds for 25 items.
Each item is a separate round trip to the server. There is no bulk way to ask. So a 10,000 item library is roughly forty minutes, and a large tenant is an overnight job. That is not a fault in the script, it is how the API works, and it is why you should scope these reports to a site rather than pointing them at everything and hoping.
Folders, and the one that breaks your script
The obvious way to check folders looks like this, and it does not work:
Get-PnPFolderItem -FolderSiteRelativeUrl 'Project Documents' -ItemType Folder | ForEach-Object {
$folderItem = Get-PnPProperty -ClientObject $_ -Property ListItemAllFields
Get-PnPProperty -ClientObject $folderItem -Property HasUniqueRoleAssignments
}Object reference not set to an instance of an object on server.
The object is associated with property ListItemAllFields.The culprit is Forms. Every document library has one, SharePoint made it, it holds the library’s form pages, and it is not backed by a list item at all. So asking it about ListItemAllFields returns nothing and the next line falls over.
Note the error does not tell you which folder caused it. You get an object reference exception on a folder you did not create and never see in the browser.
Ask the list for its folders instead:
Get-PnPListItem -List 'Project Documents' -PageSize 500 |
Where-Object { $_.FileSystemObjectType -eq 'Folder' } |
ForEach-Object {
[pscustomobject]@{
Folder = $_['FileLeafRef']
Unique = Get-PnPProperty -ClientObject $_ -Property HasUniqueRoleAssignments
}
}Folder Unique
------ ------
Contracts False
Reports False
Archive True
2024 False
2025 FalseForms never appears, because it is not a list item. Problem gone rather than worked around.
Who actually has access
Knowing something is broken is half of it. You want to know who that let in:
Get-PnPListItemPermission -List 'Projects' -Identity 3HasUniqueRoleAssignments Permissions
------------------------ -----------
True {PowerShell Demo Owners, PowerShell Demo Visitors, PowerShell Demo Members}For the permission levels as well as the names, walk the role assignments:
$item = Get-PnPListItem -List 'Projects' -Id 3
$assignments = Get-PnPProperty -ClientObject $item -Property RoleAssignments
$rows = foreach ($ra in $assignments) {
$member = Get-PnPProperty -ClientObject $ra -Property Member
$roles = Get-PnPProperty -ClientObject $ra -Property RoleDefinitionBindings
[pscustomobject]@{
Principal = $member.Title
Type = $member.PrincipalType
Roles = ($roles | ForEach-Object { $_.Name }) -join ', '
}
}
$rows | Format-Table -AutoSizePrincipal Type Roles
--------- ---- -----
PowerShell Demo Owners SharePointGroup Full Control
PowerShell Demo Visitors SharePointGroup Read
PowerShell Demo Members SharePointGroup EditThe one to watch there is $rows = foreach. A foreach statement cannot be piped – only the ForEach-Object cmdlet can. Put a pipe straight after the closing brace and you get “An empty pipe element is not allowed”, which does not obviously point at the mistake you made.
A warning about fixing what you find
While writing this I tried to break inheritance on purpose to have something to detect:
Set-PnPListItemPermission -List 'Projects' -Identity 3 -InheritPermissions:$falseIt reported success. It did nothing at all.
-InheritPermissions restores inheritance. There is no switch that breaks it, and passing $false is a silent no-op. If you write a script to lock something down that way, you get a green light and no change. Use the CSOM method instead:
$item = Get-PnPListItem -List 'Projects' -Id 3
$item.BreakRoleInheritance($true, $false)
Invoke-PnPQueryFirst argument keeps the existing permissions so you do not lock yourself out, second clears sub-scopes.
The whole script
Parameters instead of hardcoded URLs, progress while it runs, and a CSV if you want one:
[CmdletBinding()]
param(
[Parameter(Mandatory)] [string] $SiteUrl,
[Parameter(Mandatory)] [string] $ClientId,
[string] $OutputCsv,
[int] $MaxItems = 5000
)
$ErrorActionPreference = 'Stop'
Connect-PnPOnline -Url $SiteUrl -ClientId $ClientId -Interactive
$results = [System.Collections.Generic.List[object]]::new()
function Get-AccessSummary {
param($ClientObject)
try {
$assignments = Get-PnPProperty -ClientObject $ClientObject -Property RoleAssignments
$parts = foreach ($ra in $assignments) {
$member = Get-PnPProperty -ClientObject $ra -Property Member
$roles = Get-PnPProperty -ClientObject $ra -Property RoleDefinitionBindings
"$($member.Title) [$(($roles | ForEach-Object { $_.Name }) -join '/')]"
}
return ($parts -join '; ')
}
catch { return "could not read: $($_.Exception.Message)" }
}
Write-Host "Checking site..." -ForegroundColor Cyan
$web = Get-PnPWeb
$null = Get-PnPProperty -ClientObject $web -Property HasUniqueRoleAssignments
if ($web.HasUniqueRoleAssignments) {
$results.Add([pscustomobject]@{
Scope = 'Site'; Name = $web.Title
Path = $web.ServerRelativeUrl; Access = Get-AccessSummary $web
})
}
$lists = Get-PnPList | Where-Object { -not $_.Hidden }
$listNumber = 0
foreach ($list in $lists) {
$listNumber++
Write-Progress -Activity 'Scanning for broken inheritance' `
-Status "$($list.Title) ($listNumber of $($lists.Count))" `
-PercentComplete (($listNumber / $lists.Count) * 100)
$null = Get-PnPProperty -ClientObject $list -Property HasUniqueRoleAssignments
if ($list.HasUniqueRoleAssignments) {
$results.Add([pscustomobject]@{
Scope = 'List'; Name = $list.Title
Path = $list.RootFolder.ServerRelativeUrl; Access = Get-AccessSummary $list
})
}
if ($list.ItemCount -eq 0) { continue }
if ($list.ItemCount -gt $MaxItems) {
Write-Warning "Skipping items in '$($list.Title)' - $($list.ItemCount) exceeds -MaxItems $MaxItems."
continue
}
# Asking the list for its items also gives us folders, and avoids
# Get-PnPFolderItem returning the system Forms folder, which has no
# backing list item and throws when you ask about its permissions.
foreach ($item in Get-PnPListItem -List $list -PageSize 500) {
$null = Get-PnPProperty -ClientObject $item -Property HasUniqueRoleAssignments
if (-not $item.HasUniqueRoleAssignments) { continue }
$isFolder = $item.FileSystemObjectType -eq 'Folder'
$results.Add([pscustomobject]@{
Scope = if ($isFolder) { 'Folder' } else { 'Item' }
Name = if ($isFolder) { $item['FileLeafRef'] } else { $item['Title'] }
Path = $item['FileRef']
Access = Get-AccessSummary $item
})
}
}
Write-Progress -Activity 'Scanning for broken inheritance' -Completed
if ($results.Count -eq 0) {
Write-Host "`nNothing found. Everything in this site inherits its permissions." -ForegroundColor Green
Disconnect-PnPOnline
return
}
Write-Host "`nFound $($results.Count) object(s) with unique permissions.`n" -ForegroundColor Yellow
if ($OutputCsv) {
$results | Export-Csv -Path $OutputCsv -NoTypeInformation -Encoding UTF8
Write-Host "Written to $OutputCsv" -ForegroundColor Green
} else {
$results | Format-Table Scope, Name, Path -AutoSize
$results | Format-List Scope, Name, Access
}
Disconnect-PnPOnlineSave it as Get-BrokenInheritance.ps1 and run it:
.\Get-BrokenInheritance.ps1 `
-SiteUrl "https://contoso.sharepoint.com/sites/Demo" `
-ClientId "11111111-2222-3333-4444-555555555555" `
-OutputCsv .\permissions.csvChecking site...
Found 3 object(s) with unique permissions.
Scope Name Path
----- ---- ----
Site PowerShell Demo /sites/Demo
Folder Archive /sites/Demo/Project Documents/Archive
Item Project 03 /sites/Demo/Lists/Projects/3_.000
Scope : Folder
Name : Archive
Access : Demo Owners [Full Control]; Demo Visitors [Read]; Demo Members [Edit]If a site is clean it tells you so rather than printing an empty table and leaving you wondering whether it worked or you mistyped the URL 🙂