Impersonation

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Impersonation is a new feature of Windows SharePoint Services 3.0that enables you to perform actions on behalf of another user. Impersonation is useful in scenarios such as "timer" operations which need to update something asynchronously on behalf of a user long after the user has stopped using the web site (i.e., when their workflow is completed.)

Important

If you install "Infrastructure Update for Windows SharePoint Services 3.0 (KB951695)," custom solutions may fail if they call the SharePoint object model while impersonation is suspended. If you use Windows authentication and your code calls the SharePoint object model from an IIS worker process, the request must impersonate the calling user’s identity. Windows SharePoint Services configures ASP.NET to impersonate the calling user automatically, but your code may work unexpectedly, or fail, if you suspend impersonation--for example, by calling the RevertToSelf function of the Windows API, or by calling the System.Security.Principal.WindowsIdentity.Impersonate method and passing IntPtr.Zero as the value of the user token parameter. Even if your code does not explicitly revert to self, it might be called by ASP.NET after it reverts to self, such as happens when implementing a virtual path provider; if your code does not impersonate the calling user, it might not function properly.

When you create a SharePoint site programmatically using the Microsoft.SharePoint namespace, you can supply a user token which enables you to create objects in the context of a specific user. You can impersonate a user by supplying the user token for that user, obtained from the Microsoft.SharePoint.SPUser object. The user token, SPUserToken, is a binary object that contains the identification and domain group membership of a user.

This allows you to use the Microsoft.SharePoint.SPSite constructor to instantiate a site collection object that runs as if that user was making changes.

It is usually unnecessary to provide extensive security for storage of the user credentials. The credentials may be viewed using code running with either system account privileges or with the appropriate user information privileges.

Note that user tokens generally expire after about 24 hours. If you are planning to perform a long, delayed operation, you may want to save the user ID in a database and retrieve it later. However, this may slow performance because of the added overhead of retrieving information from a database. This should not be necessary if you expect the operation to be "slightly asynchronous" -- for example, if the operation runs five minutes later.

Because it requires two-way trust, also note that impersonation is not available if the Web front-end that interacts with the SharePoint database is located on a server located between two other networks. In this scenario, the Web front-end server has only one-way trust. Also, group security IDs (SIDS) are not filtered, which may cause violations of SID filtering policy among domains.

Although impersonation provides a powerful new technique for managing security, it should be used with care to make sure that unwanted activity is not performed by users who shouldn't have the ability to impersonate.

Note

To continue working with objects on a site after performing an impersonation action in code, you must reinstantiate the SPSite object.

Managing User Tokens

SharePoint fetches user token information from the SharePoint database. If the user has never visited the site or the token was generated more than 24 hours before, SharePoint generates a new user token by trying to refresh the list of groups the user belongs to.

If the user account is an NT account, SharePoint uses the AuthZ interface to query ActiveDirectory for the TokenGroups property. This may fail if SharePoint is running in an extranet mode, and do not have permission to query ActiveDirectory for this property.

If the user account is a membership user, then SharePoint queries the ASP.NET RoleManager for all the roles the user belong to. This may fail if there is not a proper .config file for the current executable file. 

If SharePoint cannot obtain the user's group memberships from ActiveDirectory or RoleManager, the newly generated token will only contain the user's unique security ID (SID). No Exception will be thrown, but an entry is written into the ULS server log. The new token is also written into SharePoint database so that it will not be regenerated within 24 hours.

After SharePoint obtains a fresh token either from the SharePoint database, or by generating a new one, SharePoint set the timestamp to be current time before returning it to the caller. This guarantees that the token is fresh for 24 hours. 

Once the SPUserToken is returned to the caller, it is the caller’s responsibility to make sure not to use it after it is expired. You can write a helper utility to track the token expiration by recording the time when you get the token, and compare the diff with current time against SPWebService.TokenTimeout.

If an expired token is used to create a SharePoint web site, an exception will be thrown. The default token timeout value is 24 hours. It can be accessed via SPWebService.TokenTimeout. 

You can also use stsadm to get or set the token timeout value. The following command line returns a value from the user token:

stsadm -o getproperty -propertyname token-timeout

Here is the result: 

<Property Exist="Yes" Value="1440" /> // 1440 minutes is 24 hours

The following command line sets a user token value:

stsadm -o setproperty -propertyname token-timeout -propertyvalue 720