App Only Permission Policy

Apps are the biggest change in SharePoint 2013. Over the past many years, SharePoint developers have been trying to figure out how to make applications work securely with each other, without users dealing with excessive passwords. Ideally, enterprises should have the confidence that installed software isn't doing more than what they think it is doing. All this is being solved with SharePoint Apps.

App Permission Policies

Apps, when installed, get their own identity, called the App Principal. What Apps are allowed to do depends on the App's identity and the user's identity. App permission policies are of three types:

• User-only policy: This is what can be thought of as code running in SharePoint. This means that the code is running as intended by the user running it - and code is able to access a resource if the logged-in user has access to the resource. An example of when this policy is enforced is when the user accesses resources directly without using the App, or an App accesses functionality in the AppWeb. Here, the SAML token is examined and the code can perform the necessary actions.
• User + App policy: This is new in SharePoint 2013. With this policy, the authorization checks take into account both the user identity and the App identity. In particular, when this policy is used, authorization checks succeed only if both the current user and the App have sufficient permissions to perform the action in question. This is the most common scenario when it comes to Apps.
• App-only policy: This is also new in SharePoint 2013. With this policy, authorization checks take into account only the App identity. In particular, when this policy is used, an authorization check succeeds only if the current App has sufficient permissions to perform the action in question, regardless of the permissions of the current user (if any). This can also be thought of as “elevation” or for scenarios where the user identity is not available such as anonymous scenarios (think WCM-web content management–sites). Also, in order to grant permissions to an app-only permissions policy App, you must be a site collection administrator. In the App-only policy App type, the person who installs the App (for example, a human resources manager) has the rights that the App needs, even though users who actually use the App might not have those rights.

In this article, I will look deeper into the App-only policy. This is where you don't have a user's identity, or the currently logged in user's identity is not enough to perform a certain action, and you need to elevate via the App. Remember, such an App can only be installed by the site collection administrator.

Writing Apps That Use App-Only Permission Policies

My assumption in this article is that you already know how to write provider-hosted Apps and you feel quite comfortable writing another one to follow along with this article.

So first, go ahead and set up a provider-hosted App that you can successfully run and deploy from Visual Studio. The default code from the Visual Studio template App will show you the title of the host SPWeb.

Now you have a provider-hosted App that displays the title of an SPWeb, Next, you will enhance it to use the App-Only security policy.

Now, try to change the title of the SPWeb. You cannot do that unless you have Full Control permission. Assuming there is a user in the SPWeb called “croc”, and croc has read-only rights to the SPWeb, croc will be able to change the title of the site using this App, even though croc has read-only permissions. Croc will be able to do this through the App, because the App will allow croc's permissions to be elevated at the server-side using an App-only security policy.

In order for croc to make this change, you need to do three things:

• Change the permissions of the App so that it requests Full Control on the SPWeb.
• Change the App so that it requests the App-only permissions policy.
• Change the logic of the App so that it changes the title of the SPWeb.

First, change the permissions of the App, as shown in Figure 1.

Figure 1: Change the permissions of the App.

Next, in AppManifest.xml add the attribute - AllowAppOnlyPolicy="true". You can see this in Figure 2.

Figure 2: Add the AppOnlyPolicy attribute in the App.

Finally, in the Default.aspx.cs of the App, add the code shown in Listing 1.

Listing 1: Code for the Default.aspx.cs file

protected void Page_Load(object sender, EventArgs e)
{
    Uri hostWeb = new Uri(Request.QueryString["SPHostUrl"]);

    using (var clientContext = TokenHelper.GetS2SClientContextWithWindowsIdentity(
                                  hostWeb, Request.LogonUserIdentity))
    {
        clientContext.Load(clientContext.Web, web => web.Title);
        clientContext.ExecuteQuery();
        Response.Write(clientContext.Web.Title);
        clientContext.Web.Title = DateTime.Now.ToLongTimeString();
        clientContext.Web.Update();
        clientContext.ExecuteQuery();
    }
}

Now go ahead and deploy the App from Visual Studio. You will probably have to sign in as administrator to SharePoint. Verify that after the App has run once, the title of the SPWeb changes from “Test” to the current time, as shown in Figure 3.

Figure 3: The title of the site shows the current time.

Keep Visual Studio running, and open a Chrome browser, or any webkit-based browser, so it will ask you to log in as a different user. Now, log in to http://sp using an account that has read-only rights to the SharePoint site, such as croc.

Once you have logged in as croc, locate your installed App under the “Recent” section, as can be seen in Figure 4.

Figure 4: Locate the App under the Recent section.

Still logged in as croc, launch the App - the App shows you the new title, as shown in Figure 5.

Figure 5: The title of the host Web shows in the App.

Now view the title of the SPWeb in another window either as administrator or croc, and verify that the title has changed, as can be seen in Figure 6.

Figure 6: The title of the host Web has changed.

As you can see, croc was able to elevate his rights and do things through the App that he didn't have permissions to do as a user.

An Important Security Consideration

One important limitation of App-only permissions is that you cannot use App-only permissions using client-side-only code. Can you guess why that may be? If Microsoft had enabled client-only-side code to work with App only permissions, any user would be able to hijack the DOM of the page and essentially do whatever they wish under the App's elevated permission. This is good forethought that Microsoft has put in as a limitation. Therefore, client-side code is explicitly prevented from using App-only permissions and must use App + User Permissions.

Summary

Apps are awesome! It's like the rabbit hole that Alice in Wonderland fell through. They keep getting deeper and deeper. There is an amazing amount of information and thought that Microsoft has put into them. That said, there are also pot holes that we need to pay attention to. In some ways Apps are a version 1 release. I will dig into that and other interesting topics in future articles.

Until then, Happy SharePointing.