IntroductionThis is a collection of PowerShell methods to automate SharePoint user and group reconfigurations. Topics in this posting include:
- Remove a SharePoint web user group's permission level
- Cleanup Usernames after migration
- Configure primary and secondary site collection administrators
- Add additional Site Collection Administrators
- Add an Active Directory user group as a site collection administrator
- Remove all users from SharePoint web's user group
Remove a SharePoint web user group's permission levelTo interact with SharePoint users and groups and their permission levels for a specific web in your web application, you need to work with four objects:
- SPWeb: this is the object that contains all of the members associated with a specific web in your web application.
- RoleDefinitions: this a property of the SPWeb object and contains a collection of permission levels, such Full Control, Design, Contribute and Read, that you have defined for the web application.
- RoleAssignments: this is a property of the SPWeb object and contains a collection of SharePoint users and groups that have been assigned a permission level to the web.
- RoleDefinitionBindings: this is a property of the RoleAssignments object and contains a collection of the actual associations, or bindings, between a role definition and an SPWeb user or group member.
$Web = Get-SPWeb "htp://contoso.com/web1"Interrogate the web object to see all of that web's current role assignments:
$Web.RoleAssignmentsIf this web was created using default settings, it would include these assignments: Web1 Owners (Full Control), Web1 Members (Contribute), and Web1 Visitors (Read). Let's say, for example, that the role assignment that needs to be modified is the third in this collection, or Web1 Visitors. Then, to do this, we need to get an instance of that assignment, which you can do via its index in the collection:
$ra= $Web.RoleAssignments["2"]You could execute this by itself to see what's included in this object. So, executing:
$Web.RoleAssignments["2"]gets you something like this:
$rd = $ra.Parent.RoleDefinitions["Read"]We now have an instance of the group's assignment, $ra, as it exists within Web1, and we have an instance of that group's permission level definition, $rd, as it exists within Web1. We can now remove the instance of the particular permission level, or role definition, that we want to remove from the group's role assignments. This is done like so:
$ra.RoleDefinitionBindings.Remove($rd)The next step is to update the group with this change:
$ra.Update()And now you're done. It really is that easy. Here's what the total script would look like for removing the Read permission from the Web1 Visitors group:
Note that since this is the only permission that this group is configured with, this effectively removes Web1 Visitors from the list of SharePoint groups configured for this web. This is in fact how you remove a SharePoint user group from a web.
Now take the more general case, where a web's user group, call it Web1 Members, has previously been assigned a number of different permission levels, say Design, Manage Hierarchy and Approve, in addition to its standard permission level of Contribute. You want to remove all the non-standard permission levels to get this user group back to what it should be. The script for this would be:
Cleanup Usernames after migrationI use this script to clean up usernames after migrating the content database to 2013 and upgrading to claims. These usernames had a variety of special characters and domain prefixes that needed to be removed. This script doesn't do the mapping of these usernames to Active Directory. All it does is interrogate the SiteUsers collection of usernames and modify the DisplayName property of each one. This script works with these two SharePoint objects:
Configure primary and secondary site collection administratorsI use this script to automate configuration of the primary and secondary site collection administrators. I developed this script to automate the migration of a SharePoint Server 2007 Enterprise farm, employing Active Directory Lightweight Directory Services (AD LDS) authentication to SharePoint Server 2013 employing standard AD authentication. This script uses a single SharePoint object; SPUser, specifically configuring the -Owner and -SecondaryContact properties of the object.
Add additional Site Collection AdministratorsThe following script adds additional site collection administrators (SCA). These are the SCAs that you would normally add by using the Site Settings capabilities of the site collection (go: Settings > Site Settings > Go to top level site settings > User and Permissions > Site collection administrators). These can also be added by setting the SPUser object's IsSiteAdmin property, which the following script presents. Note the claims authentication formatting.
Add an Active Directory user group as a site collection administratorOne thing I found useful in administration was to move from assigning site collection administrator privileges individually to assigning this permission to a user group. You can of course do this using the Site Settings capabilities. You can also do this via PowerShell and again using the site collection's SPUser object. However, there is one caveat: you need to use the AD group's SID, not its display name. For example, consider a user group containing system administrators., DOMAIN\SysAdmins, with SID s-1-2-34-1234567890-1234567890-1234567890-1234. Then, accounting for claims authentication, its SharePoint identity would be
and the script would be:
Remove all users from SharePoint web's user groupConsider that you have particular user group in a web, call it Web1, and a user group, Web1 Members, containing a number of SharePoint users, and that you would like to completely empty Web1 Members of all users so as to replace them with a single Active Directory group, DOMAIN\Web1-Users. This was the challenge I faced when migrating a legacy 2007 farm and wanting to implement this in an automated way so as to ensure maximum repeatability. The below script does this.
It employs just two key SharePoint objects: SPWeb and SPUser. To remove all users from a group, the script first obtains an instance of the particular group from the SPWeb's group collection, SiteGroups. Each member of this collection in turn contains a collection of its users that you can access via the group's Users collection. After obtaining an instance of a user in this group, the group's RemoveUser method is used to remove the user from the group. Once all the SharePoint users have been removed from this group, it remains to add a single AD group to complete the migration to a full AD user group approach.
Adding an Active Directory user group to a SharePoint user group requires the use of a single object, SPWeb, and a method that you may not be familiar with, EnsureUser, which get's an instance of the user.
The EnsureUser method get's an instance of the user among the web's user collection or it add's the AD user to the web's user collection. Contrast this with Get-SPUser, which requires that the user already be a member of the farm's user collection or otherwise it fails. Note that in this case, the EnsureUser method engages an Active Directory group the same as an Active Directory user.This script first gets an instance of the SharePoint web group that you want to work on. It then creates an instance of the Active Directory "user" (in this case, group) that you want to add. I then uses the group instance's AddUser method to add the "user" to the SharePoint group. Note how the method is named. Here's the complete script:
- SPWeb.RoleAssignments Property
- SPWeb.RoleDefinitions property
- SPRoleAssignment.RoleDefinitionBindings property
- Capitalizing First Letter of Every Word with Powershell 2
- Active Directory Lightweight Directory Services
- These methods were discovered through trial and error and exploring the SharePoint object model (OM) using Get-Member.