How to: Break Role Assignment Inheritance Using JavaScript

Applies to: SharePoint Foundation 2010

You can break the security inheritance of a website, list, or list item through the BreakRoleInheritance method of the object so that role assignments on the parent object no longer apply to the child object, for example, so that role assignments on a list no longer apply to a list item. For websites and lists, this method passes two Boolean parameters, copyRoleAssignments and clearSubScopes. The first parameter specifies whether to maintain the current role assignments already inherited from the parent site collection or website, and the second parameter specifies whether to clear unique permissions of child objects so that they will subsequently inherit permissions from the parent website or list. If the copyRoleAssignments parameter is set to false, the current user who runs the code acquires full control of the object. The ResetRoleInheritance method of the website, list, or list item restores role assignment inheritance of the parent object to the child object.

Breaking the Security Inheritance of a List Using ECMAScript (JavaScript, JScript)

The following example shows how to break the security of a list by using the breakRoleInheritance(copyRoleAssignments, clearSubscopes) function of the List object. After running the example, subsequent role assignments made at website level will have no effect on role assignments within the list. The example breaks the inheritance of the Announcements list but maintains current role assignments without breaking unique role assignments on individual items within the list.

var siteUrl = '/sites/MySiteCollection';

function breakSecurityInheritance() {

    var clientContext = new SP.ClientContext(siteUrl);
    this.oList = clientContext.get_web().get_lists().getByTitle('Announcements');

    oList.breakRoleInheritance(true, false);

    clientContext.load(oList);

    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded(sender, args) {

        alert(this.oList.get_title() + ' role inheritance broken.');
}

function onQueryFailed(sender, args) {

        alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

Breaking the Security Inheritance of a Document and Adding a User as Reader

The breakRoleInheritance(copyRoleAssignments) function of the ListItem object passes only one Boolean parameter, which specifies whether to preserve the role assignments of the parent list. The following example breaks the security inheritance of a single item within a list and adds a specified user as a reader for the item. Since the copyRoleAssignments parameter is set to false, the current user who runs the code is given full control of the item.

var siteUrl = '/sites/MySiteCollection';

function breakSecurityInheritanceAddUser() {

    var clientContext = new SP.ClientContext(siteUrl);
    var oList = clientContext.get_web().get_lists().getByTitle('MyList');

    var itemId = 4;
    this.oListItem = oList.get_items().getById(itemId);

    oListItem.breakRoleInheritance(false);

    this.oUser = clientContext.get_web().get_siteUsers().getByLoginName('DOMAIN\\alias');

    var collRoleDefinitionBinding = SP.RoleDefinitionBindingCollection.newObject(clientContext);

    collRoleDefinitionBinding.add(clientContext.get_web().get_roleDefinitions().getByType(SP.RoleType.reader));

    oListItem.get_roleAssignments().add(oUser, collRoleDefinitionBinding);

    clientContext.load(oUser);
    clientContext.load(oListItem);

    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded(sender, args) {

    alert('Role inheritance broken for item ' + 
        this.oListItem.get_item('Title') + 
        ' and new role assignment for ' + 
        this.oUser.get_loginName());
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

Breaking the Security Inheritance of a Document and Changing the Permissions of a User

The following example breaks the security inheritance of an item within a list but preserves the current role assignments on the item. The example assigns Reader permissions to a specified user within the site collection. The example uses the getByLoginName(loginName) function to retrieve the user from the collection of users within the site collection.

var siteUrl = '/sites/MySiteCollection';

function breakSecurityInheritanceChangeUser() {

    var clientContext = new SP.ClientContext(siteUrl);
    var oList = clientContext.get_web().get_lists().getByTitle('MyList');

    var itemId = 5;
    this.oListItem = oList.get_items().getById(itemId);

    oListItem.breakRoleInheritance(true);

    this.oUser = clientContext.get_web().get_siteUsers().getByLoginName('DOMAIN\\alias');

    oListItem.get_roleAssignments().getByPrincipal(oUser).deleteObject();

    var collRoleDefinitionBinding = SP.RoleDefinitionBindingCollection.newObject(clientContext);

    collRoleDefinitionBinding.add(clientContext.get_web().get_roleDefinitions().getByType(SP.RoleType.administrator));

    oListItem.get_roleAssignments().add(oUser, collRoleDefinitionBinding);

    clientContext.load(oUser);
    clientContext.load(oListItem);        

    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded(sender, args) {

    alert('Role inheritance broken for item ' + 
        this.oListItem.get_item('Title') + 
        ' and new role assignment for ' + 
        this.oUser.get_loginName());
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

See Also

Concepts

How to: Work with Users and Groups Using JavaScript

How to: Work with Roles Using JavaScript

Authorization, Users, and Groups

Data Retrieval Overview

SharePoint 2010 Client Object Model Guidelines

Common Programming Tasks in the JavaScript Object Model

Other Resources

JavaScript Class Library