SharePoint Account Management using SPUserUtil - Part 0 - Removing Accounts - Keith Richie - Site Home

SharePoint Account Management using SPUserUtil - Part 0 - Removing Accounts

SPUserUtil will mean either WSSUserUtil or SPSUserUtil respectively (WSSUserUtil is used to administer Windows SharePoint Sites on a standalone WSS Farm/Virtual server OR Windows SharePoint sites in the same virtual server of a SharePoint Portal Server 2003 site.) SPSUserUtil is a superset of WSSUserUtil, designed for working on SharePoint Portal Server Areas.

There are many ways to remove an NT account resource (User or Security Group) from a SharePoint resource. You remove an account resource at the web level, or the site collection level.

Considerations

Consider an account resource which only permissions on one web within a site collection. In this scenario if the account resource only had permissions on one single web in the site collection, it's easy to just navigate to that one web and remove it.

If the account resource had permissions on a lot of webs in the site collection, you can just visit the siteusrs.aspx page for the site collection and remove it from there. When you do this, it completely removes the account resource from the site collection as a whole, thus removing all references to the resource on any web they exist on.

If you don't want to just mass remove the resource from the site collection in whole, but only want to remove a resource from multiple webs in a site collection, you have to visit each web and remove the resource manually for each one.

I'll detail each of these OOB (Out of Box) methods further down, then detail how to do the same process (which I believe is easier) using SPUserUtil

It's not a bug :)

When an account resource is deleted from Active Directory or NT, SharePoint does not automatically remove the account resource information from it's sites and webs. This is not a SharePoint problem, as the same issue exists on any other NTFS resource. For example, a folder on your PC, or a file share on the network.

For the most part, most administrators don't worry too much about cleaning up dead account resources from NTFS resources, as those accounts ARE deleted from AD, and can never compromise security...They're just (for the lack of better words) orphaned ACE's on the resource.

When you do decide to remove the account resource, it's pretty easy to just bring up the resources properties dialog....Scroll down to the orphaned ACE, and remove it.

For SharePoint on the other hand, it is quite cumbersome because you have to paginate over, and over, and over, and over until you get to the account resource in question to remove the ACE.

Basic scenario

A user in your enterprise is terminated, or departs on his own free will :) You need to either

Remove the user from SharePoint Sites.
Transfer Ownership of SharePoint sites/webs/etc to another individual or

This post will deal with simply removing the user completely. We'll cover ownership transfer in a future post.

Leaving the user information on the sites doesn't necessarily present a problem, but it can be an administrative headache. I have seen a few reports that when trying to remove users from Portal areas, that it balks because it still tries to do a domain lookup on the user when you're deleting them. If you have a repro of that, you should call Customer Support Services if it is preventing you performing your administrative task.

Out of Box methods for removing users

Removing a single resource from a web through the UI

If you just want to remove an account resource from a web (whether the account resource is deleted or not), you simply need to access the "Manage Users" page for the web in question. The navigation path to this page (for Windows SharePoint Services) is:

From the home page of the site, click "Site Settings" on the top navigation bar
Click "Manage Users"

If you have removed the navigation bar on your site, or you want to just jump right to the page, you can access it by navigating to the users.aspx layouts page directly in your browser. For example:

http://server/sites/asite/asubweb/_layouts/1033/user.aspx

This will take you to the "Manage Users" page for the subweb named "asubweb" underneath the top level site "asite" within the managed path "sites" on the "server" in question.

From this page, you simply select the users/groups you want to remove via the check box next to each resource, then select the "Remove Selected Users" link.

This removes an account resource from this web only. If you need to remove this user from multiple webs, follow the same process noted above for each web.

Removing a single resource from a web using STSADM

You can simplify the process by using STSADM if you have sufficient rights using the deleteuser operation.

stsadm.exe -o deleteuser url http://server/asite/asubweb userlogin DOMAIN1\AUser

This removes an account resource from this web only. If you need to remove this user from multiple webs, follow the same process noted above for each web.

For more information on STSADM operations, see: http://office.microsoft.com/en-us/assistance/HA011608091033.aspx

Removing a single resource from a site collection

Removing a single resource from a web, DOES NOT remove them entirely from the site collection, even if the account resource only had permissions on the single web in the site collection from which you just removed them. For some of the reasons why, see my previous blog post about Using SPUserUtil to synchronize SharePoint user Display Names and Email addresses with the information in Active Directory.

If you want to remove a single resource from an entire site collection (whether the account resource is deleted or not) you simply need to access the "Manage Site Collection Users" page for the site collection in question. The navigation path to this page (for Windows SharePoint Services) is:

From the home page of the site, click "Site Settings" on the top navigation bar
Click "Go to Site Administration"
Click "Go to Top-level Site Administration"
Click "View site collection user information"

If you have removed the navigation bar on your site, or you want to just jump right to the page, you can access it by navigating to the siteusrs.aspx layouts page directly in your browser. For example:

http://server/sites/asite/_layouts/1033/siteusrs.aspx

This will take you to the "Manage Site Collection Users" page for the site collection whose top level site is "asite" within the managed path "sites" on the "server" in question.

From this page, you simply select the users/groups you want to remove via the check box next to each resource, then select the "Remove Selected Users" link.

This removes an account resource from this site collection only. If you need to remove this user from multiple site collections, follow the same process noted above for each site collection.

There is no equivalent STSADM operation (such as seleteuser noted above) to remove a user from the entire site collection

Cumbersome Problem Number 1

This becomes an administrative headache if you have 100's of account resources on your webs or sites, in which case you have to paginate through all these resources on either the users.aspx page or the siteusrs.aspx pages, to get to the resource in question so you can mark them for deletion. You could certainly script it using the deleteuser operation for STSADM, but this does not remove them from the site collection.

Cumbersome Problem Number 2

As noted above, scripting calls to STSADM can still be cumbersome, as you would have to run it on every single web in your entire farm to remove the user from the webs. Since there is no STSADM equivelant for removing users from the entire site collection, you have to manually visit each site collection in your farm (There could be literally 10's of thousands of site collections) to remove the user.

SPUserUtil to the rescue.

With SPUserUtil, you can automate all the above processes easily to help relieve the headache of managing users in SharePoint.

Note: Pay special attention to the new -asuonly and -usermask switches noted below

Removing a single resource from a web or series of webs using SPUserUtil.

If you just want to remove an account resource from a web (whether the account resource is deleted or not), using SPUserUtil, following these steps:

Prepare a SPUserUtil usermap file with a user element which has the loginname= attribute set accordingly.
loginname= should be the NT Login Name as reflected in SharePoint.
I actually recommend running a analyze of the site to get a complete list of all users. You can then use this file as a template.

For example:

WSSUserUtil –o analyze –url http://server/sites/site -usermap users.xml –asu

Note: The –asu switch means Give me All Site Users associated on the site collection, regardless if they have any direct ACE entries on any webs.

This will produce a listing of all users and generate the file users.xml. An additional file, users-webs.xml, will be generated that contains the web hierarchies and the location of user permissions on each web.

Here is an example of the output (Of course, your results will be different :)).

<?xml version="1.0" standalone="no"?>

<!DOCTYPE SPUserUtilUserMapFile>

<users>

<user loginname="MYDOMAIN\margie.murphy" newloginname=""

displayname="Margie Murphy" email="margie.murphy@MYDOMAIN.com"

sid="S-1-5-21-5555555555-555555555-5555555555-1111" />

<user loginname="MYDOMAIN\Administrator" newloginname=""

displayname="" email=""

sid="S-1-5-21-4444444444-555555555-5555555555-500" />

<user loginname="MYPORTALSVR\administrator" newloginname=""

displayname="MYPORTALSVR\administrator" email="administrator@MYDOMAIN.com"

sid="S-1-5-21-3333333333-555555555-5555555555-500" />

</users>

Here is a version prepared to work on a single user account. (Note: the account listed below would NEVER be deleted from my world :))

<?xml version="1.0" standalone="no"?>

<!DOCTYPE SPUserUtilUserMapFile>

<users>

</users>

It's actually much easier than that in the current release of SPUserUtil. With this updated version there is a new usermask switch that will filter down to a specific user. For example:

WSSUserUtil –o analyze –url http://server/sites/site -usermap singleuser.xml -asuonly -usermask "*margie.richie*"

Note: The –asuonly switch means Give me All Site Users associated on the site collection, regardless if they have any direct ACE entries on any webs, and prevents normal web scanning for the user. It implicitly includes the default -asu logic as noted above,

This will generate the file singleuser.xml. An additional file, singleuser-webs.xml, will be generated but it will be completely empty, because we're bypassing the normal web scanning that occurs in an analyze operation. It's a crude but effective way to generate a proper user map file for a single user (or multiple users based on the -usermask).

Note: A future version of this tool will eliminate the need to generate a UserMap file for single user operations. In other words, you'll be able to specify -userlogin to target a specific user without the need to generate the UserMap.

With this file prepared, we can utilize the -o delete operation of SPUserUtil to delete a user from a web, or series of webs

When running the -o delete operation using WSSUserUtil, it will read in and process all the user elements found in the xml file.

For Example:

WSSUserUtil –o delete –url http://server/sites/asite/asubweb -usermap users.xml

Every single user found in the users.xml file will be removed from the web pointed at by the -url switch.
If you want to recursively remove the user from the web and all of it's subwebs, use the -r switch.

For Example:

WSSUserUtil –o delete –url http://server/sites/asite/asubweb -usermap users.xml -r

Every single user found in the users.xml file will be removed from the web pointed at by the -url switch and all of it's sub webs.

Much easier than using the UI or STSADM -o deleteuser for every web.

Removing a single resource from a site collection using SPUserUtil

If you just want to remove an account resource from a site collection (whether the account resource is deleted or not), using SPUserUtil, following these steps:

Prepare you list of users as noted in the previous section
Run SPUserUtil with the -o deletecollection operation using WSSUserUtil, it will read in and process all the user elements found in the xml file.

WSSUserUtil –o deletecollection –url http://server/sites/asite -usermap users.xml

Every single user found in the users.xml file will be removed from the site collection pointed at by the -url switch.
To remove a user from every single site collection on a virtual server:
WSSUserUtil –o deletecollection –url http://server -usermap users.xml -ac

Every single user found in the users.xml file will be removed from every site collection on the virtual server specified using the -url switch.

Purging all those deleted accounts

So you've discovered that a deleted account resource (Either a User or Security Group) currently has permissions on a web or site in your environment and you want to remove them completely. With the above information in hand, the following short list of steps using SPUserUtil should to the trick.

Generate a valid usermap for a single resource or multiple resources
a) Generate a usermap for a single resource

    WSSUserUtil –o analyze –url http://server/sites/site -usermap singleuser.xml -asuonly -usermask "*krichie*"

b) Generate a usermap for alot of resrouces

    Either run an analyze operation:

    WSSUserUtil –o analyze –url http://server/sites/site -asuonly -usermap users.xml

    And trim out the users you don't want to operate on.

c) Or Create and additional <user> element in the UserMap for each account in question.
Run WSSUserUtil with the deletecollection operation and the -ac switch to completely purge the user from ALL site collections on the virtual server.

WSSUserUtil –o deletecollection –url http://server -usermap users.xml -ac
Repeat step 2 for each virtual server

Note: Like SPSiteManager, there WILL be an -allvs switch added in later that will allow you to perform all operations across all virtual servers, etc, in a future version. That would make the process even simpler by executing a command such as the following:

WSSUserUtil –o deletecollection –allvs -usermap users.xml -ac

My next postings will be about Ownership transfers and Adding accounts en-masse, Brahahahahahha (I'm feeling like a mad scientist right now :))

I hope this helps, and let me know if you have any questions!

- Keith

For more information in regards to the Schema of the Various SharePoint Tables, see the Databases section in the SharePoint Products and Technologies SDK at:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/spptsdk/html/SPPTWSSDatabases_SV01072208.asp

For more information in regards to Managing Users and Cross Site Groups in SharePoint
http://office.microsoft.com/en-us/assistance/HA011608091033.aspx

SPUserUtil is contained in the The SharePoint Utility Suite at:
http://www.microsoft.com/sharepoint/downloads/components/detail.asp?a1=724

For More information on the Windows SharePoint Services MigrateUserAccount() API:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/spptsdk/html/tsamSPGlobalAdminMigrateUserAccount_SV01234066.asp

For More information on the SharePoint Portal Server MigrateAccount() API:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/spptsdk/html/mPortalAccountMigManagerMigrateAccount2_SV01187841.asp

For more information on Windows SharePoint Services and SharePoint Portal Server 2003:
http://www.microsoft.com/sharepoint