Impersonation
Applies to: SharePoint Foundation 2010
Impersonation, a feature that was added in Windows SharePoint Services 3.0, enables you to perform actions on behalf of another user. Impersonation is useful in scenarios such as timer operations that need to update something asynchronously on behalf of a user long after the user has stopped using the Web site (that is, when their workflow is completed).
Note
For information about suspending impersonation, see Avoiding Suspending Impersonation of the Calling User.
When you create a SharePoint site programmatically by 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 enables you to use the Microsoft.SharePoint.SPSite constructor to instantiate a site collection object that runs as if that user is making changes.
It is usually unnecessary to provide extensive security for storage of the user credentials. The credentials may be viewed by using code running with system account privileges or by using code running with the appropriate user information privileges.
Note that user tokens generally expire after approximately 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 technique for managing security, it should be used with care to ensure that unwanted activity is not performed by users who should not 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 if the user’s token was generated more than 24 hours previously, SharePoint generates a new user token by trying to refresh the list of groups that the user belongs to.
If the user account is an NT account, SharePoint uses the AuthZ interface to query the Active Directory directory service for the TokenGroups property. This may fail if SharePoint is running in an extranet mode, and does not have permission to query Active Directory for this property.
If the user account is a membership user, SharePoint queries the ASP.NET RoleManager for all the roles that the user belongs 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 Active Directory or <roleManager>, the newly generated token contains only the user's unique security ID (SID). No exception is thrown, but an entry is written into the ULS server log. The new token is also written into the SharePoint database so that it will not be regenerated within 24 hours.
After SharePoint obtains a fresh token, from the SharePoint database or by generating a new token, SharePoint sets the timestamp to be the current time and then returns it to the caller. This guarantees that the token is fresh for 24 hours.
After the SPUserToken object is returned to the caller, it is the caller’s responsibility to not use the token 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 is 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 returns a value from the user token:
stsadm -o getproperty -propertyname token-timeout
Following is the result:
<Property Exist="Yes" Value="1440" /> // 1440 minutes is 24 hours
The following command sets a user token value:
stsadm -o setproperty -propertyname token-timeout -propertyvalue 720