Creating and Managing Permission Levels using PnP PowerShell

In SharePoint Online, permission levels control what actions users and groups can perform on a site, list, or library. Using PnP PowerShell, you can efficiently create, modify, and manage custom permission levels for better security and access control.

This guide covers:
✔️ Creating a custom permission level
✔️ Assigning permissions to a level
✔️ Modifying an existing permission level
✔️ Removing a custom permission level

Prerequisites

Before proceeding, ensure:
PnP PowerShell is installed
You have SharePoint Admin or Site Collection Admin rights
You have the site URL where you want to manage permissions

Step 1: Install and Import PnP PowerShell

If PnP PowerShell is not installed, run:

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

Then, import the module:

Import-Module PnP.PowerShell

PnP PowerShell is ready!

Step 2: Connect to SharePoint Online

Use the following command to connect to your SharePoint Online site:

Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/yoursite" -Interactive

Replace "yourtenant" with your SharePoint tenant name
Replace "yoursite" with your actual site name

Connected successfully!

Step 3: Create a Custom Permission Level

To create a new permission level, define its name and permissions:

# Define variables
$permLevelName = "Custom Read-Only"
$permLevelDesc = "Custom permission level with read-only access"

# Define base permissions
$permissions = @(
    "ViewListItems", "OpenItems", "ViewVersions",
    "CreateAlerts", "ViewPages"
)

# Create the permission level
Add-PnPRoleDefinition -RoleName $permLevelName -Description $permLevelDesc -BasePermissions $permissions

This creates a Custom Read-Only permission level allowing users to view items but not edit them.

Custom permission level created!

Step 4: Assign the Custom Permission Level to a SharePoint Group

Once created, assign the permission level to a SharePoint group:

# Define variables
$groupName = "Custom Read-Only Users"

# Assign permission level to the group
Set-PnPGroupPermissions -Identity $groupName -AddRole $permLevelName

Replace "Custom Read-Only Users" with the actual SharePoint group name.

Permission level assigned successfully!

Step 5: Modify an Existing Permission Level

To modify a permission level, remove existing permissions and add new ones:

# Define new permissions
$updatedPermissions = @(
    "ViewListItems", "OpenItems", "ViewVersions",
    "CreateAlerts", "ViewPages", "UseRemoteAPIs"
)

# Update the permission level
Set-PnPRoleDefinition -RoleName $permLevelName -BasePermissions $updatedPermissions

🔹 This adds UseRemoteAPIs permission to the Custom Read-Only level.

Permission level updated successfully!

Step 6: Remove a Custom Permission Level

To delete a custom permission level:

# Define permission level name
$permLevelName = "Custom Read-Only"

# Remove the permission level
Remove-PnPRoleDefinition -RoleName $permLevelName

This removes the Custom Read-Only permission level.

Custom permission level deleted!

Step 7: Verify Assigned Permission Levels

To check existing permission levels:

Get-PnPRoleDefinition

To check the permissions assigned to a specific level:

Get-PnPRoleDefinition -Identity "Custom Read-Only"

Permission levels verified!

Common Errors & Solutions

Error	Cause	Solution
`Access Denied`	Insufficient permissions	Ensure you are a SharePoint Admin
`Permission level already exists`	Name conflict	Use a different permission level name
`Group not found`	Incorrect SharePoint group name	Verify the group name
`Cannot modify built-in permission levels`	System restriction	Only custom levels can be modified