Auditing SharePoint Online Permissions using PnP PowerShell

1. Introduction

Auditing SharePoint Online permissions ensures that only authorized users have access to sensitive data. Using PnP PowerShell, we can extract permissions for SharePoint sites, lists, libraries, and specific users.

With this guide, you’ll learn how to:
Audit SharePoint Online permissions using PnP PowerShell
Retrieve permission details for sites, lists, and libraries
Export audit results to a CSV file
Automate periodic permission audits

---

2. Prerequisites

Before you begin, ensure you have:

• PnP PowerShell installed
  If not, install it using:Install-Module -Name PnP.PowerShell -Scope CurrentUser -Force
• SharePoint Admin or Site Collection Admin permissions
• The URL of the SharePoint Online site you want to audit

---

3. Connecting to SharePoint Online

Before retrieving permissions, establish a secure connection to SharePoint Online.

Step 1: Connect to SharePoint Online

$SiteURL = "https://yourtenant.sharepoint.com/sites/YourSite"
Connect-PnPOnline -Url $SiteURL -Interactive

• Replace "yourtenant" with your SharePoint tenant name.
• Replace "YourSite" with your actual site name.

This will prompt you to log in with your Microsoft 365 credentials.

---

4. Retrieving Permissions for SharePoint Sites

To list all users and groups with access to a SharePoint site:

$SitePermissions = Get-PnPSitePermission
$SitePermissions | Select-Object PrincipalName, Rights

• This retrieves all groups and users along with their permission levels.

Check Site Administrators

$Admins = Get-PnPSiteCollectionAdmin
$Admins | Select-Object Title, Email

• This retrieves all site collection administrators.

---

5. Auditing Permissions for Lists and Libraries

To check who has access to a specific document library or list, use:

Retrieve All Lists in a Site

$Lists = Get-PnPList
$Lists | Select-Object Title, Hidden, HasUniqueRoleAssignments

• This lists all libraries and lists, and whether they inherit permissions.

Check Permissions for a Specific List/Library

$ListTitle = "Documents"
$ListPermissions = Get-PnPList -Identity $ListTitle | Get-PnPListPermission
$ListPermissions | Select-Object PrincipalName, Rights

• Replace "Documents" with your list/library name.
• This retrieves who has access and their permission levels.

---

6. Exporting Permissions Report to CSV

To generate an audit report of all site, list, and library permissions:

Step 1: Define the Site URL

$SiteURL = "https://yourtenant.sharepoint.com/sites/YourSite"
Connect-PnPOnline -Url $SiteURL -Interactive

Step 2: Collect Site Permissions

$Permissions = Get-PnPSitePermission | Select-Object PrincipalName, Rights
$Permissions | Export-Csv -Path "C:\Reports\SitePermissions.csv" -NoTypeInformation
Write-Host "Site Permissions Exported Successfully!"

Step 3: Collect List & Library Permissions

$Lists = Get-PnPList
$Results = @()

foreach ($List in $Lists) {
    $ListPermissions = Get-PnPListPermission -Identity $List.Title
    foreach ($Permission in $ListPermissions) {
        $Results += [PSCustomObject]@{
            ListName = $List.Title
            Principal = $Permission.PrincipalName
            Permissions = $Permission.Rights
        }
    }
}

$Results | Export-Csv -Path "C:\Reports\ListPermissions.csv" -NoTypeInformation
Write-Host "List & Library Permissions Exported Successfully!"

This script:
Retrieves all lists and libraries
Extracts user/group permissions
Exports the data to CSV for further analysis

---

7. Automating the Permission Audit Process

To schedule automated audits, create a PowerShell script (Audit-SharePointPermissions.ps1) and run it periodically using Task Scheduler.

Step 1: Save the Script

$SiteURL = "https://yourtenant.sharepoint.com/sites/YourSite"
Connect-PnPOnline -Url $SiteURL -Interactive

# Get Site Permissions
$SitePermissions = Get-PnPSitePermission | Select-Object PrincipalName, Rights
$SitePermissions | Export-Csv -Path "C:\Reports\SitePermissions.csv" -NoTypeInformation

# Get List Permissions
$Lists = Get-PnPList
$Results = @()

foreach ($List in $Lists) {
    $ListPermissions = Get-PnPListPermission -Identity $List.Title
    foreach ($Permission in $ListPermissions) {
        $Results += [PSCustomObject]@{
            ListName = $List.Title
            Principal = $Permission.PrincipalName
            Permissions = $Permission.Rights
        }
    }
}

$Results | Export-Csv -Path "C:\Reports\ListPermissions.csv" -NoTypeInformation
Write-Host "SharePoint Permission Audit Completed Successfully!"

Step 2: Schedule a Task

1. Open Task Scheduler.
2. Click Create Basic Task.
3. Choose a Trigger (e.g., weekly or monthly).
4. Select Action > Start a Program.
5. Set Program/Script to powershell.exe.
6. In Add Arguments, enter: -File "C:\Path\To\Audit-SharePointPermissions.ps1"
7. Click Finish and enable the task.

Now, SharePoint permissions will be automatically audited and saved as a report.