Break Inheritance And Add Role Permissions Using REST API In SharePoint

When a new SharePoint object is created, by default, Permission inheritance occurs. All SharePoint objects will be created within the context of a hierarchical tree. Unless the inheritance structure is broken, all SharePoint objects inherit permissions from its parent in the hierarchy.

Permission inheritance enables user to make the assignment of permission just once, and have that permission trickle down to all sites, lists, libraries, folders and items that inherit permissions from its parent. This can reduce the time administrators and site owners usually spent in managing the site permissions. However as part of security management there are scenarios where we need to implement unique permissions to a particular site or list.

We can implement this from UI directly. In order to do that we can navigate to the permissions management section of the Library/List Library. Settings -> Permissions for this Document Library.

Clicking on Stop Inheriting Permissions will grant unique permissions to the document library.

In one of my project engagements, I however had to implement this using REST API and add Role Permissions (Full Control, Edit etc.) to the uniquely secured group within the library.

Let’s see how we can do it.

Goal: Break Inheritance of default Share Point Document Library named ‘Documents’ and assign Full Control permissions to SP2016 Members (Currently it inherits Edit permissions from Parent )

Firstly, let’s break the inheritance using the BreakRoleInheritance method of REST API.

Say if my site had the URL: http://c293106922:1500, then the breakroleinheritance rest URL will look like:

http://c293106922:1500/_api/web/lists/getByTitle('Documents')/breakroleinheritance(copyRoleAssignments=true, clearSubscopes=true)

If I try to access the above Rest API from the browser it will give me the following error:

It states clearly that we cannot use GET to issue the rest call. Let’s create the REST header, REST end point and issue a POST request.

The entire rest call to break inheritance will look like the following code snippet:

//Create the REST header  
var headers = {  
        "Accept": "application/json;odata=verbose",  
        "content-Type": "application/json;odata=verbose",  
        "X-RequestDigest": jQuery("#__REQUESTDIGEST").val()  
}  
  
 //Create the REST end point URL  
var endPointUrl = "http://c293106922:1500/" + "_api/web/lists/getByTitle('Documents')/breakroleinheritance(copyRoleAssignments=true, clearSubscopes=true)";  
  
//Issue the REST Call  
var call = jQuery.ajax({  
      url: endPointUrl,  
      type: "POST",  
      headers: headers,  
      dataType: 'json',success: function (data) {  
           alert(‘Inheritance Broken Successfully !');  
            
        },  
        error: function (error) {  
            alert(JSON.stringify(error));  
        }  
    });

Once the breakroleinheritance call is issued the child’s inheritance will lost and it will not have unique permissions.

Now let’s see how to assign Full Control permissions to the existing group SP2016 Test Members in the List using the method addroleassignment of REST API.

The rest API for this will look like: “http://c293106922:1500/_api/web/lists/getByTitle('Document')/roleassignments/addroleassignment(principalid=20,roleDefId=1073741828)“

There are two parameters whose values we need to know to issue the REST call.

1. Principalid
2. RoleDefid

Here Pricipalid is the id of the user/group to which we are going to assign Role Permissions.

This id can be obtained from browser by issuing a GET request as below:

http://c293106922:1500/_api/web /siteusers - to get the id of a user
http://c293106922:1500/_api/web /sitegroups - to get the id of a group

So our group SP2016 has an id of 8.

The second parameter is the RoleDefid which is the id of the Role Permission (Full Control, Edit, etc.)

We can get the id of the Role permission using the following GET request in the browser.

http://c293106922:1500/_api/web/roledefinitions

Thus full control has the id of : 1073741829.

Now we are all set to issue a POST REST call to add the Full Control Role Permission to SP2016 Test Members group.

var headers = {  
    "Accept": "application/json;odata=verbose",  
    "content-Type": "application/json;odata=verbose",  
    "X-RequestDigest": jQuery("#__REQUESTDIGEST").val()  
}  
var endPointUrlRoleAssignment = "http://c293106922:1500/" + "_api/web/lists/getByTitle('Documents')/roleassignments/addroleassignment(principalid=8,roleDefId=1073741829)";  
var call = jQuery.ajax(  
{  
    url: endPointUrlRoleAssignment,  
    type: "POST",  
    headers: headers,  
    dataType: 'json',  
    success: function (data)  
    {  
        alert(Role Permission Added successfully!');  
    },  
    error: function (error)  
    {  
        alert(JSON.stringify(error));  
    }  
});

Upon successful completion we can see the extra role permission added to our group:

The complete REST call for breaking inheritance and then adding Role assignments is as below:

Here role assignment REST call is issued from the success method of the Break Role Inheritance Ajax call, so that both happen sequentially.

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>  
<script type="text/javascript">  
$(document).ready(function ()  
  
//Create REST header  
var headers = {  
        "Accept": "application/json;odata=verbose",  
        "content-Type": "application/json;odata=verbose",  
        "X-RequestDigest": jQuery("#__REQUESTDIGEST").val()  
    }  
    //Create breakinheritance REST url  
var endPointUrl = ”http: //c293106922:1500/" + "_api/web/lists/getByTitle('Documents')/breakroleinheritance(copyRoleAssignments=true, clearSubscopes=true)";  
    //Issue the REST call  
    var call = jQuery.ajax(  
        {  
            url: endPointUrl,  
            type: "POST",  
            headers: headers,  
            dataType: 'json',  
            success: function (data)  
            {  
                alert(‘Inheritance Broken Successfully!');  
                        //Add Role Permissions   
                        var endPointUrlRoleAssignment = "http://c293106922:1500/" + "_api/web/lists/getByTitle('Documents')/roleassignments/addroleassignment(principalid=8,roleDefId=1073741829)";  
                        var call = jQuery.ajax(  
                        {  
                            url: endPointUrlRoleAssignment,  
                            type: "POST",  
                            headers: headers,  
                            dataType: 'json',  
                            success: function (data)  
                            {  
                                alert('Role Permission Added successfully !');  
                            },  
                            error: function (error)  
                            {  
                                alert(JSON.stringify(error));  
                            }  
                        });  
                    },  
                    error: function (error)  
                    {  
                        alert(JSON.stringify(error));  
                    }  
            });  
    });  
</script> 

Thus we have seen how to break Inheritance in SharePoint and add Role permissions to a security object using REST API. MSDN offers sparse documentation for this API. This has been tested with Share Point 2013 and 2016 Preview.