SharePoint Online: Create a Custom Permission Level using PowerShell

Requirement: Create a new permission level in the SharePoint Online site collection for “Contribute without delete” permissions.

SharePoint Online Permission Levels:

SharePoint Permission levels are a set of actions users can perform in SharePoint, packaged as a group, to make permission management easier. So, Instead of providing individual permissions to users and groups, you pick a permission level and assign it to the new user. (or even add the user to a group that has a specific permission level associated). There are default permission levels included in SharePoint, such as:

  • Full Control – For Site collection owners. This permission level includes all available permissions and grants assigned users admin-level access to the site and all its resources.
  • Design – The Design permission level provides the ability to manage lists, libraries, and pages within a SharePoint site, as well as approve content and manage the site’s look and feel.
  • Manage Hierarchy – This Lets you create and manage subsites in addition to edit rights.
  • Edit – Assigned to site members. Enables associated users to create and manage lists and libraries and their content.
  • Approve – The Approve permission level grants the ability to edit and approve pages, list items, and documents when content is configured to require approval.
  • Contribute – This permission level provides the ability to view, add, update, and delete list items and documents. 
  • Read – The Read permission level provides read-only access to site resources. They can view pages, list items, and download documents. The visitors group is granted read permissions by default in a typical team site.
  • Limited Access: This permission can’t be manually set. It is assigned by SharePoint automatically when access is granted to the least level object without giving access to the parent.
  • View Only – View Only permission is similar to read. It lets users view files, but users cannot download them.
Never edit or delete any OOTB permission levels in SharePoint! If needed, you can copy any existing permission levels and make amendments to it!

How to create a permission level in SharePoint Online?

Creating a new permission level in SharePoint Online is a simple process that can be completed in just a few clicks. Assuming you have “Full control” or “Manage Permissions” access rights, Let me show you how to create permission levels in SharePoint Online by walking you through the steps of creating a new permission level. The “Contribute without delete” permission level is often required in real-world scenarios. Let’s say, You want your users to be able to add files to the library but not delete files from the library. To achieve this, we can simply copy the “Contribute” permission level and take off the “Delete Items” permission from it! To create a new permission level in SharePoint Online, follow these steps:

  1. Go to the SharePoint site >> Click on Settings >> Site Permissions >> Advanced Permissions Settings. (In classic sites, You can click on Site Settings >> Site Permissions).
  2. Click on the Permission Levels button from the ribbon.

This takes you to the page which lists all default permission levels available in SharePoint with their corresponding description. Now you can either add a Permission Level or click on any existing permission level, Copy and then edit the new permission level to fill your requirements.

sharepoint online powershell create permission level
Do not change any default permission levels such as “Full Control” or “Contribute”.

Assign Permission Level to Users and Groups

Once the permission level is ready, you can edit permissions by clicking on the “Edit user Permissions” button to assign the new permission level. This applies to any type of SharePoint site such as Team site/Group connected/Non-Microsoft 365 group connected/Communication sites.

  1. Navigate to the home page of the site >> Click on the Settings gear icon >> Site Permissions >> Click on Advanced permissions settings
  2. Break the permission inheritance if needed, Select any existing users, SharePoint groups, or security groups by clicking on the “Edit user Permissions” button
  3. Set the permission level for the user at the site level by selecting the respective checkbox.
    edit user permissions

You can also set the permissions for a specific list or document library from list settings/document library settings.

Please note that custom permission levels can only be created at the site collection level, so if you need to create a unique permission level for another site, you will need to create it again there. Permission levels created at the site collection level propagate to the subsites.

SharePoint Online PowerShell to Create a Permission Level

Let’s automate the above steps to create a custom permission level using PowerShell. Here is how to create a custom permission level in SharePoint Online using PowerShell:

#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"
  
##Variables for Processing
$SiteUrl = "https://crescent.sharepoint.com"
$SourcePermissionLevelName ="Contribute"
$TargetPermissionLevelName ="Contribute Without Delete"

Try {
    #Get Credentials to connect
    $Cred = Get-Credential
    $Credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($Cred.Username, $Cred.Password)

    #Setup the context
    $Ctx = New-Object Microsoft.SharePoint.Client.ClientContext($SiteUrl)
    $Ctx.Credentials = $Credentials
    $Web = $Ctx.Web

    #Get the source permission level
    $RoleDefinitions = $web.RoleDefinitions
    $Ctx.Load($RoleDefinitions)  
    $SourceRoleDefinition = $RoleDefinitions.GetByName($SourcePermissionLevelName)
    $Ctx.Load($SourceRoleDefinition)
    $Ctx.ExecuteQuery()

    #get base permissions from the source and remove "Delete"
    $TargetBasePermissions = $SourceRoleDefinition.BasePermissions
    $TargetBasePermissions.clear([Microsoft.SharePoint.Client.PermissionKind]::DeleteListItems)

    #check if the given permission level exists already!
    $TargetPermissionLevel = $RoleDefinitions | Where-Object { $_.Name -eq $TargetPermissionLevelName } 
    if($TargetPermissionLevel -eq $null)
    {
        #Create new permission level from source permission level
        $PermissionCreationInfo = New-Object Microsoft.SharePoint.Client.RoleDefinitionCreationInformation
        $PermissionCreationInfo.Name = $TargetPermissionLevelName
        $PermissionCreationInfo.Description = $TargetPermissionLevelName
        $PermissionCreationInfo.BasePermissions = $TargetBasePermissions

        #Add the role definitin to the site
        $TargetPermissionLevel = $Web.RoleDefinitions.Add($PermissionCreationInfo)
        $Ctx.ExecuteQuery() 
 
        Write-host "New Permission Level Created Successfully!" -ForegroundColor Green
    }
    else
    {
        Write-host "Permission Level Already Exists!" -ForegroundColor Red
    }
}
Catch {
    write-host -f Red "Error Creating Permission Level!" $_.Exception.Message
}

This script copies the existing permission level and creates a new permission level. Instead of copying and manipulating an existing permission level, You can also create a new one from scratch.

#Create base Permission set
$Permissions = New-Object Microsoft.SharePoint.Client.BasePermissions
#Add permissions to it
$Permissions.Set([Microsoft.SharePoint.Client.PermissionKind]::ViewListItems)
$Permissions.Set([Microsoft.SharePoint.Client.PermissionKind]::ViewVersions)  

SharePoint Online: PnP PowerShell to Create a Custom Permission Level

Let’s create a new permission level, “Contribute without Delete” by copying the contribute permission level and removing delete capabilities from it using the PnP PowerShell cmdlet Add-PnPRoleDefinition.

#Set Variables
$SiteURL = "https://crescent.sharepoint.com/sites/Marketing"

#Connect to PnP Online
Connect-PnPOnline -Url $SiteURL -Credentials (Get-Credential)

#Get Permission level to copy
$ContributeRole = Get-PnPRoleDefinition -Identity "Contribute"

#Create a custom Permission level and exclude delete from contribute 
Add-PnPRoleDefinition -RoleName "Contribute without Delete" -Clone $ContributeRole -Exclude DeleteListItems, DeleteVersions -Description "Contribute without delete permission"

Similarly, you can copy a permission level and add permissions to it. E.g., Copy Read permission level and add “AddListItems” and “EditListItems” to it.

#Variables
$SiteURL = "https://crescent.sharepoint.com/sites/Retail"

#Connect to PnP Online
Connect-PnPOnline -Url $SiteURL -Interactive

#Create a custom permission level
$BasePermissionLevel = Get-PnPRoleDefinition -Identity "Read"

#Set Parameters for new permission level
$NewPermissionLevel= @{
    Include     = 'EditListItems', 'AddListItems'
    Description = "Read Permissions with Add and Edit List Items"
    RoleName    = "Read with Contribute to List Items"
    Clone       = $BasePermissionLevel
}

#Create new permission level
Add-PnPRoleDefinition @NewPermissionLevel
To get all values of the base permission enumeration, use: [Enum]::GetNames(“Microsoft.SharePoint.Client.PermissionKind”)

Create a Custom Permission Level for All Site Collections in the Tenant

How about creating a custom permission level on all sites in the tenant?

#Parameters
$Domain =  "CrescentIntranet" #Domain Name in SharePoint Online. E.g. https://Crescent.sharepoint.com
$NewPermissionLevelName = "Contribute without Delete"
$BasePermissionLevelName = "Contribute"
   
#Frame Tenant URL and Tenant Admin URL
$TenantURL = "https://$Domain.SharePoint.com"
$TenantAdminURL = "https://$Domain-Admin.SharePoint.com"

#Get Credentials to connect
$Cred = Get-Credential

#Connect to Admin Center
Connect-PnPOnline -Url $TenantAdminURL -Credentials $Cred
   
#Get All Site collections - Filter BOT and MySite Host
$Sites = Get-PnPTenantSite -Filter "Url -like '$TenantURL'"
  
#Iterate through all site collections
$Sites | ForEach-Object {
    #Connect to each site collection
    Connect-PnPOnline -Url $_.URL -Credentials $Cred
 
    #check if the given permission level exists already!
    $NewPermissionLevel = Get-PnPRoleDefinition | Where-Object { $_.Name -eq $NewPermissionLevelName } 
    If($NewPermissionLevel -eq $null)
    {
        #Get Permission level to copy
        $BaseRoleDefinition = Get-PnPRoleDefinition -Identity $BasePermissionLevelName
 
        #Create a custom Permission level and exclude delete from contribute 
        Add-PnPRoleDefinition -RoleName $NewPermissionLevelName -Clone $BaseRoleDefinition -Exclude DeleteListItems, DeleteVersions -Description "Contribute without delete permission" | Out-Null
        Write-host "Created Permission Level at $($_.URL)" -f Green
    }
    Else
    {
        Write-host "Permission Level Already Exists at $($_.URL)" -ForegroundColor Yellow
    }
}

Last but not least: What is the difference between edit and contribute permission in SharePoint Online? Users with “Edit” Permissions can add, edit and delete lists and Libraries in SharePoint. However, the Contribute permission is limited to contributing items and files (Add, Edit and Delete) to existing lists and libraries without being able to add, edit and delete lists and Libraries.

To update an existing permission level in SharePoint Online, use: How to Edit permission levels in SharePoint Online?

How to give folder-level permission in SharePoint Online?

To provide permission to a folder in SharePoint Online: Click on “Manage access” from the menu of the folder >> Click on the “Advanced” link >> Stop Inhering Permissions If the folder is inheriting permissions from its parent >> Click on the “Grant Permission” button to add users to the folder. Enter the names of the users and groups and click on the “Share” button to add permission to the folder.
More info: Set Folder Level Permissions in SharePoint Online

SharePoint Online view only permission level missing?

Activate the “SharePoint Server Enterprise Site Collection features” at the site collection and site levels.
More info: “View Only” Permission missing in SharePoint Online? Here is the fix!

Salaudeen Rajack

Salaudeen Rajack - Information Technology Expert with Two-decades of hands-on experience, specializing in SharePoint, PowerShell, Microsoft 365, and related products. He has held various positions including SharePoint Architect, Administrator, Developer and consultant, has helped many organizations to implement and optimize SharePoint solutions. Known for his deep technical expertise, He's passionate about sharing the knowledge and insights to help others, through the real-world articles!

9 thoughts on “SharePoint Online: Create a Custom Permission Level using PowerShell

  • Hi, thank you for your article.
    Is this possible via the SharePoint REST api or even better via Microsoft graph?

    Reply
  • Are you able to set permission level to give full design rights to just one page on a site but not the rest of the site?

    Reply
    • Break the permission inheritance of the page and grant permissions to necessary users.

      Reply
  • Can we set permission levels just within one page on the site to give full deign rights just to that one page on the site

    Reply
    • You can Break the permission inheritance of the page and assign “Full Control” to it.

      Reply
  • Hi

    You’ve shown how to create a permission level thru the administrator UI but also how to do it with a powershell script. Are these just two alternative ways of doing the same thing?

    Reply
    • Yes, Its just two ways to do the same! When you need to automate-repeat use PowerShell.

      Reply
  • Hi!

    Is it possible to create a sharepoint permission level that can contribute but only view own files in a document library?

    Thanks!
    Hayley

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *