Demystified : Breaking the Role Inheritance of a SecurableObject with CSOM

Managing permissions is a very important aspect of SharePoint. As there are so many techniques to authenticate a user to a SharePoint application, the permissions part takes care of the authorization. There are so many articles that discuss the permissions levels, groups etc to a great extent.

In this post I’m going to discuss the following things.

• Code snippet to break role inheritance of a Securable Object – In current example a list
• Analyzing the code with User Interface

   
public static void AssignUniquePermissions(string ctxUrl,string listTitle)
{
	ClientContext ctx = new ClientContext(ctxUrl);
	List targetList = ctx.Web.Lists.GetByTitle("listTitle");
	ctx.Load(targetList);
	
	// the below line of code breaks the Permission Inheritane
	// The below piece of code is equivalent to...
	targetList.BreakRoleInheritance(true,false);

	/* PermissionKind => is an Enum type that represents 
        all the permissions available */
	/* BasePermissions => is a class to which we set the Selected 
        Permissions. Later we use 'BasePermissions' object in creating 
        the 'RoleDefinition' */
	BasePermissions permissions = new BasePermissions();
	permissions.Set(PermissionKind.ViewListItems);
	permissions.Set(PermissionKind.AddListItems);
	permissions.Set(PermissionKind.EditListItems);
	permissions.Set(PermissionKind.DeleteListItems);


	/* Create a new role definition => Creating a Permission Level 
        @ /_layouts/addrole.aspx of site collection. */
        //The below piece of code is equivalent to...
	RoleDefinitionCreationInformation roleDefInfo = new RoleDefinitionCreationInformation();
	// Permission Level Name
	roleDefInfo.Name = "ExampleEditListItems1";
	roleDefInfo.Description = "Allows a user to manage list items";
	roleDefInfo.BasePermissions = permissions;
	/* Adds RoleDefinition => Adds Permission Level 
        @ /_layouts/role.aspx */
	RoleDefinition roleDef = ctx.Site.RootWeb.RoleDefinitions.Add(roleDefInfo);

	// Creating another RoleDefinition
	BasePermissions permissions2 = new BasePermissions();
	permissions2.Set(PermissionKind.ApproveItems);
	RoleDefinitionCreationInformation roleDefInfo2 = new RoleDefinitionCreationInformation();
	// Permission Level Name
	roleDefInfo2.Name = "ExampleEditListItems2";
	roleDefInfo2.Description = "Allows a user to Approve Items";
	roleDefInfo2.BasePermissions = permissions2;
	RoleDefinition roleDef2 = ctx.Site.RootWeb.RoleDefinitions.Add(roleDefInfo2);

	/* The permissions we are assigning to the User/Group
	Equivalent to 'Grant User Permissions Directly
        (in this example) by selecting multiple permission 
        levels */
        // The below piece of code is equivalent To..
	RoleDefinitionBindingCollection permissionLevelsCollection = new RoleDefinitionBindingCollection(ctx);
	// Add the role to the collection.
	permissionLevelsCollection.Add(roleDef);
	permissionLevelsCollection.Add(roleDef2);

	// User user = ctx.Web.EnsureUser("Domain\\userId"); (or)
	Group group = ctx.Web.SiteGroups.GetById(12);

	/* The page that contains all the Permissions. => 
        @ _layouts/user.aspx of the corresponding securable object */
	RoleAssignmentCollection roleAssignmentCollection = targetList.RoleAssignments;
	RoleAssignment roleAssignment = roleAssignmentCollection.Add(group, permissionLevelsCollection);

	ctx.ExecuteQuery();
	Console.WriteLine("Done!!");
	Console.ReadKey();
}

targetList.BreakRoleInheritance(true,false);

This above line of code is equivalent to clicking on the ‘Stop Inheriting Permissions’ option in the ribbon

What is the difference between BreakRoleInheritance(true,true/false)?
This function breaks the role inheritance of the SecurableObject on which we are calling the function in both cases.
The second parameter(true/false) acts on the Child objects of the SecurableObject on which we called the function.
true: It makes the children of the current SecurableObject inherit RoleAssignments from the current SecurableObject even though they have UniqueRoleAssignments on them.
false: It allows the children of the current SecurableObject have their own RoleAssignments(UniqueRoleAssignments) if they have any.
Back To Code

Creating a RoleDefinition:

Creating a RoleDefinition is equivalent to creating a new permission level from the SharePoint UI @ ‘addrole.aspx’ of the root web

// Adds the permission level to the collection of permission levels at the root web level
RoleDefinition roleDef = ctx.Site.RootWeb.RoleDefinitions.Add(roleDefInfo); 

Everything I mentioned in the below image happens only after executing the query.
You find this info when you click on the Permission Level created @
~siteCollectionUrl/_layouts/editrole.aspx?role=ExampleEditListItems1

Back To The Code

Granting Permissions To a User Or Group:

Adding RoleDefinition Objs to RoleDefinitionBindingCollection obj is equivalent to
select the multiple permission checkboxes as shown in the below image.

	permissionLevelsCollection.Add(roleDef);
	permissionLevelsCollection.Add(roleDef2);

	// if we want to grant permissions to a user
	User user = ctx.Web.EnsureUser("Domain\\userId");
	(or)
	// if we want to grant permissions to a Group
	// The group id '12' represents 'TestGroup1' as shown in the above image
	Group group = ctx.Web.SiteGroups.GetById(12);
	
	// This line of code grants permissions to the Group
	RoleAssignment roleAssignment = roleAssignmentCollection.Add(group, permissionLevelsCollection);
	// This line of code grants permissions to the User
	RoleAssignment roleAssignment = roleAssignmentCollection.Add(user, permissionLevelsCollection);