Migrating SharePoint Groups and Permissions using PnP PowerShell

When migrating SharePoint sites, it is crucial to transfer groups and permissions to ensure users maintain the same access levels. Using PnP PowerShell, we can export groups and permissions from one SharePoint site and import them into another.

What You’ll Learn

Exporting SharePoint groups and permissions
Migrating groups to a new SharePoint site
Restoring permissions on lists, libraries, and site collections
Automating the migration process

---

Step 1: Install & Connect to SharePoint Online

Ensure PnP PowerShell is installed:

Install-Module -Name PnP.PowerShell -Scope CurrentUser -Force

Connect to the source SharePoint site:

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

Successfully connected to the source site!

---

Step 2: Export SharePoint Groups and Permissions

The following script retrieves SharePoint groups and their permissions and saves them to a CSV file.

Save this script as C:\Migration\ExportPermissions.ps1

# Define Variables
$SourceSite = "https://yourtenant.sharepoint.com/sites/SourceSite"
$ExportPath = "C:\Migration\SharePointGroups.csv"

# Connect to SharePoint Online
Connect-PnPOnline -Url $SourceSite -Interactive

# Get all SharePoint groups
$Groups = Get-PnPGroup

# Export groups and their roles to CSV
$GroupsData = @()

foreach ($Group in $Groups) {
    $Roles = Get-PnPGroupPermissions -Identity $Group.Id
    $Permissions = ($Roles | ForEach-Object { $_.Name }) -join ", "

    $GroupsData += [PSCustomObject]@{
        GroupName   = $Group.Title
        GroupId     = $Group.Id
        Permissions = $Permissions
    }
}

# Save to CSV
$GroupsData | Export-Csv -Path $ExportPath -NoTypeInformation

Write-Host "✅ SharePoint groups and permissions exported successfully to $ExportPath"

All groups and permissions are now saved in CSV format!

---

Step 3: Import Groups into a New SharePoint Site

Now, let’s import groups into a destination SharePoint site.

Save this script as C:\Migration\ImportPermissions.ps1

# Define Variables
$DestinationSite = "https://yourtenant.sharepoint.com/sites/DestinationSite"
$ImportPath = "C:\Migration\SharePointGroups.csv"

# Connect to SharePoint Online
Connect-PnPOnline -Url $DestinationSite -Interactive

# Read exported groups
$Groups = Import-Csv -Path $ImportPath

foreach ($Group in $Groups) {
    # Create the group if it doesn't exist
    $ExistingGroup = Get-PnPGroup | Where-Object { $_.Title -eq $Group.GroupName }
    if (-not $ExistingGroup) {
        New-PnPGroup -Title $Group.GroupName -Owner "admin@yourtenant.onmicrosoft.com"
        Write-Host "✅ Created group: $($Group.GroupName)"
    }

    # Assign permissions to the group
    $Permissions = $Group.Permissions -split ", "
    foreach ($Permission in $Permissions) {
        Set-PnPGroupPermissions -Identity $Group.GroupName -AddRole $Permission
    }

    Write-Host "✅ Assigned permissions to group: $($Group.GroupName)"
}

Write-Host "✅ SharePoint groups and permissions imported successfully!"

✅ Groups and permissions have been successfully migrated!

---

Step 4: Migrate Permissions for Lists & Libraries

After migrating groups, ensure lists and libraries maintain their permissions.

Use this script to migrate list permissions:

# Define Variables
$SourceSite = "https://yourtenant.sharepoint.com/sites/SourceSite"
$DestinationSite = "https://yourtenant.sharepoint.com/sites/DestinationSite"
$ExportPath = "C:\Migration\ListPermissions.csv"

# Connect to the Source SharePoint site
Connect-PnPOnline -Url $SourceSite -Interactive

# Export List Permissions
$ListPermissions = @()

$Lists = Get-PnPList
foreach ($List in $Lists) {
    $Roles = Get-PnPListPermission -List $List.Title
    foreach ($Role in $Roles) {
        $ListPermissions += [PSCustomObject]@{
            ListName    = $List.Title
            GroupName   = $Role.PrincipalName
            Permission  = $Role.RoleDefinitionBindings
        }
    }
}

# Save to CSV
$ListPermissions | Export-Csv -Path $ExportPath -NoTypeInformation

Write-Host "✅ List permissions exported to $ExportPath"

Now, import list permissions into the destination site:

# Define Variables
$DestinationSite = "https://yourtenant.sharepoint.com/sites/DestinationSite"
$ImportPath = "C:\Migration\ListPermissions.csv"

# Connect to the Destination SharePoint site
Connect-PnPOnline -Url $DestinationSite -Interactive

# Read exported list permissions
$ListPermissions = Import-Csv -Path $ImportPath

foreach ($Item in $ListPermissions) {
    $ListName = $Item.ListName
    $GroupName = $Item.GroupName
    $Permission = $Item.Permission

    # Assign permissions
    Set-PnPListPermission -List $ListName -Identity $GroupName -AddRole $Permission

    Write-Host "✅ Assigned $Permission to $GroupName on $ListName"
}

Write-Host "✅ List permissions successfully migrated!"

Lists and libraries now have the correct permissions!

---

Step 5: Automate the Migration Process

To automate migrations, schedule this PowerShell script using Task Scheduler:

1️⃣ Open Windows Task Scheduler
2️⃣ Create a New Task → Set it to run the script at a specific time.
3️⃣ Use this PowerShell command:

powershell.exe -ExecutionPolicy Bypass -File "C:\Migration\ImportPermissions.ps1"

Now, SharePoint groups and permissions migrate automatically!