Introduction
Microsoft's SharePoint Services and Technologies (SharePoint) has a robust security model. Every operation attempted within the SharePoint framework is subject to the security settings and policies that apply to the affected objects. This article discusses the methods provided by the SharePoint framework that allow developers to accomplish tasks regardless of a user's permissions.
Need Alternate Security Context
When writing an application that is based on the SharePoint framework, it is common for the program to update or create a SharePoint object. A typical scenario is a feedback form on an anonymous website.The form needs to write data to a SharePoint list, but granting write permission to the anonymous user is not acceptable.
This article includes code and screenshots from anIdentity Web Part that displays information about identities used in the current request.
Note: The Identity Web Part is available from the downloads library of this site.
Impersonation versus Elevation
Before discussing this topic further, we need to define the meaning of elevation of privilege and impersonation. The SharePoint Software Development Kit (SDK) provides the following descriptions:
Impersonation: Enables developer to perform actions on behalf of another user.
Elevation of privilege: Enables developers to programmatically perform actions in code using an increased level of privilege.
What is not clear in these definitions is the difference in the requirements to use these approaches. For example, in order to impersonate you typically require the user's credentials. In order to elevate, the elevated privileges must be available in the execution environment. Both of these approaches can be used in SharePoint.
Identities
SharePoint is built on the ASP.NET infrastructure. However, since a complete discussion of the ASP.NET infrastructure is outside of the scope of this paper, we will explore the concept of identities at a high level. Details that are omitted in this paper can be reviewed in the ASP.NET documentation on MSDN.
There are a few different identities in the ASP.NET pipeline. The first is the process identity that is set via the application pool in which the Web application is configured. In ASP.NET, the Default Application Pool is running with the System Identity. When SharePoint is installed, a new application pool is created and configured to use the service account specified during the configuration wizard. This is commonly referred to as the AppPool identity. (There is also a thread identity. The web server process spawns threads to handle each request, and these threads also use the process identity.)
The next identity is the context identity. When the ASP.NET framework processes a request, the impersonation and authorization settings in web.config indicate how the context identity is created. As indicated in the following code, the default SharePoint configuration uses Windows authentication and has impersonation enabled:
<authentication mode="Windows" />
<identity impersonate="true" />
Refer to the MSDN article titled "Authentication in ASP.NET: .NET Security Guidance" for more information on this topic.
The net effect of these settings is that the identity of the user running the browser is also the identity of the request. This identity is exposed to pages and controls as the Windows identity. The Windows identity is available to server-side code via the static method: System.Security.Principal.WindowsIdentity.GetCurrent().
SharePoint also requires an identity to perform security checks. In the SharePoint object model, the SharePoint identity is represented by the SPUser object. During the request pipeline, the SPUser is set to the same value as the Windows identity. However, they are not the same object, which means they can be altered independently.
Use the following code to retrieve the SharePoint value in code running on a Web page such as a Web Part:
SPWeb web = SPContext.Current.Web;
SPUser user = web.CurrentUser;
Note: You cannot create an SPUser object. Instead, the SharePoint framework creates this object in the context of a site collection (SPSite) based on the context identity.
Identity Web Part
In Figure 1, the Identity Web Part is shown on the home page of a blank site. This Web Part displays the current values of the Windows identity and SharePoint identity. It also contains buttons to perform both elevation and impersonation. The current user account, which is Victor Visitor in this example, is a member of the site visitors group and has only read access to the site.
Figure 1 - Default Identities
Impersonation
There are a few scenarios in which impersonation of another user is helpful. One such scenario is the restricted access of a sensitive resource such as a database. This is the case for SharePoint when a service account is configured to access the content databases. This service account is then impersonated and the data retrieved. However, the users do not have permission to the database. The service account scenario is accomplished by storing and later retrieving the credentials of the impersonated account.
Note: Since the details about impersonation in ASP.NET are outside the scope of this whitepaper, refer to the "Impersonation and Delegation" article on Microsoft's ASP.NET Community site for more information on this topic.
Another common scenario is a background or deferred process that executes a user initiated function. This background process acts on behalf of several users, which means it runs with credentials such as LocalSystem that are appropriate for a background process. In this scenario, the requesting user account is impersonated and the requested action is performed.
In addition, there is a system account provided by the SharePoint platform that functions similar to a service account. The system account has permission to all SharePoint objects and can be used to update items using code that would denied if attempted by the requesting user account. The system account can be impersonated without a password, which makes it a powerful alternative to granting user permissions throughout the farm.
Impersonate a User
To impersonate a user in the SharePoint framework, you must have a SPUserToken object. This object can be obtained by referencing the UserToken property of the SPUser object. However, the SPUser class cannot be created in code. Instead, a user token must be accessed and stored during a page request.
SPUseruser = SPContext.Current.Web.CurrentUser;
SPUserTokentoken = user.UserToken;
// store token
At this point the background process can retrieve the token and use it to impersonate the requestor. The actual impersonation is performed by SharePoint during the creation of a SPSite object. Creating the SPSite object also requires the objects GUID or the site collection URL.
stringurl = http://localhost; // use your url
SPUserTokentoken = user.RetrieveToken(); // a custom method
using (SPSite site = new SPSite(url, token))
{
// access the SPSite and its objects under the identity
// represented by the token
}
Retrieving the SPUserToken of the system account requires similar code. Since the system account is a known principal, there is no need to store and retrieve the token.
SPUsersystemUser = SPContext.Current.Site.SystemAccount;
SPUserTokentoken = systemUser.UserToken;
// store token
Figure 2 shows the code for the Impersonate button of the Identity Web Part that provides the user token as it creates a new SPSite object. This step is required to obtain a new SharePoint identity.
Figure 2 - Impersonate method
Effects of Impersonation
Running the impersonate method affects the SharePoint identity of the request. The Windows identity is still set by the base ASP.NET settings. Since the SPWeb object used to retrieve the current user was created within the scope of the impersonation, the SharePoint identity is set to SHAREPOINT\system, which is the predefined value of the system account (see Figure 3).
Figure 3 - Impersonated identities
When to Impersonate
Impersonating an alternate account is appropriate whenever code must perform an action within the SharePoint platform on behalf of a user. The impersonation method only changes the SharePoint identity of the request, not the Windows identity.
Best Practice:
If the code is expected to honor the permissions of the requesting user, the users token must be used to perform the impersonation.
Best Practice:
For code that updates SharePoint on behalf of a user without permissions, use the System Account token to perform the impersonation.
Best Practice:
If the current user cannot access the system account token, use the RunWithElevatedPrivileges method to retrieve the system account token and then impersonate. Do not perform all required actions with elevated privileges.
Elevation of Privilege
Elevation of privilege provides an increased level of privilege. However, from where does this level of privilege come? The possible choices are the involved infrastructure frameworks, which are IIS, ASP.NET, and SharePoint. The IIS process is configured to run with minimal privilege to reduce the attack surface open to malicious code and hackers. SharePoint is leveraging the identity of the HttpContext. Therefore, the natural place is from ASP.NET.
As mentioned previously, the identity of the ASP.NET process is configured in the Application Pool (AppPool). Since the AppPool identity is set during configuration of SharePoint, we can assume it has the privileges necessary to access the resources used throughout the farm including the database, servers, and services.
Elevate Level of Privilege
In the SharePoint platform, running code with elevated privileges is accomplished using the SPSecurity.RunWithElevatedPrivileges method. This method invokes a delegate that runs with the Windows identity set to the AppPool account. The password of the AppPool account is not required, as it is with Impersonation.
Figure4 shows the code for the Elevate button of the Identity Web Part. In this method, the RunWithElevatedPrivileges method runs an anonymous function, which is identitified by the delegate keyword.
Figure4 - Method to elevate privilege
Effects of Elevation
As discussed previously, the RunWithElevatedPrivileges method executes the specified code with the identity of the application pool. The Identity Web Part reflects this change, as shown in Figure 5.
Behind the scenes, there is significant code that creates a new application domain that has a separate security context. Next, the code provided to the RunWithElevatedPrivileges method runs within this separate application domain, which is reflected in the different Windows identity.
Figure5 - Elevated identities
When to Elevate
Since elevation of privilege does not change the SharePoint identity, performing the elevation is appropriate only when an alternate Windows identity is required. For code running on the SharePoint platform, the AppPool identity is the only available Windows identity. This means that elevation is only effective if the AppPool identity has the necessary permissions to the secured resource.
Best Practice:
Use elevated privileges to access non-SharePoint resources to which the application pool account has the necessary permissions.
Best Practice:
Use only the RunWithElevatedPrivileges method of the SPSecurity class to obtain a context with elevated privileges. Any other approach is not supported.
Summary
This article explains how developers can use impersonation and elevation of privilege when working with ASP.NET identities to accomplish tasks regardless of a user's permissions. The ability to use these methods allows developers to create solutions that work with, rather than work around, security settings.