Today, I am continuing in my How to series of posts. According to the stats, they have been quite popular, so I will keep them coming. We are going to talk about how to create a SharePoint security group. A group (represented by SPGroup) is an internal collection of users (or Active Directory) groups that you can then assign a permission level to on a given site. You can do this through the web interface but in the case where you are programmatically provisioning sites, you will need code to set who is allowed to use it.
Creating a group is pretty simple, but before you start you need to make sure that the group doesn't already exist. Of course there is no exists method in any of the SharePoint collections, so you may want to use the try/catch technique. Once you have established that the group does not exists, you need to decide who is going to be the owner of the group. The owner of the group must be a member of the site you are using before you try to create a group. Luckily the EnsureUser method makes adding this user easy. Assume below that currentSite is an SPWeb object. This could be for a specific subsite or perhaps RootWeb on your site collection.
The EnsureUser method adds the user to the site if it doesn't exist. If it does exist, it just returns without error. We use the SiteGroups collection on the SPWeb object to add the group to the site.
currentSite.SiteGroups.Add("My Custom Group", currentSite.SiteUsers[@"DOMAIN\OWNER"],
currentSite.SiteUsers[@"DOMAIN\OWNER"], "My Custom Group Description");
The Add method takes four parameters. The first parameter is the group name. The second parameter is the owner of the group. Note that it requires an SPMember object (SPUser inherits from SPMember) not a string with an Active Directory account. This is why we have to execute the EnsureUser method above. The third parameter is a default user. Honestly, I have no idea what this is for. It's not something you have to specify when creating a group using the UI, so I usually just pass the owner. The last parameter is a description.
The next thing we want to do is add users to the group. To do that, we just get a reference to our newly created group and call the AddUser method. We would call this multiple times if we were adding more than one user.
currentSite.SiteGroups["My Custom Group"].AddUser(@"DOMAIN\USER1", string.Empty, "User 1", string.Empty);
The first parameter is the login name. The second is an E-mail address. The third is the user's actual name and the last parameter is for notes. If I don't know all of the values for the parameters, I just pass an empty string (I believe null causes an exception).
The last thing we need to do is set the permissions on the group (i.e.: does this group have Read or Contribute access). The way the API does it may not seem straight forward at first. We have to create a SPRoleAssignment object by passing it our new group. We then add a role definition binding to that SPRoleAssignment object. We then add that SPRoleAssignemnt object to the RoleAssignments collection on the SPWeb object.
SPRoleAssignment roleAssignment = new SPRoleAssignment(currentSite.SiteGroups["My Custom Group"]);
In this case, we are setting Contribute access for this group. You could also specify a custom permission level here as well. Note, the last statement we must execute is the Update method on the SPWeb object. Don't forget this otherwise your changes would not be saved.