Export (0) Print
Expand All

App authorization policy types in SharePoint 2013

apps for SharePoint

Learn about the different authorization policies for apps in SharePoint: app-only policy, user+app policy, and user-only policy. It also provides guidelines for using app-only policy.

Last modified: August 20, 2014

Applies to: apps for SharePoint | Office 365 | SharePoint Foundation 2013 | SharePoint Server 2013

In this article
Get an overview of app authorization policies types
See an example scenario of an app that uses the app-only policy
Learn how apps get permission to use the app-only policy
Learn how apps make app-only calls
Get guidelines for using the app-only policy
Additional resources

Before reading this article, you should first be familiar with the articles App permissions in SharePoint 2013 and Context Token OAuth flow for apps in SharePoint 2013.

SharePoint provides three types of authorization policies:

  • User-only policy— When the user-only policy is used, SharePoint checks only the permissions for the user. SharePoint uses his policy is enforced is when the user is accessing resources directly without using an app. (This policy was always used in SharePoint 2010.)

     

  • User+app policy—When the user+app policy is used, SharePoint checks the permissions of both the user and the app principal. Authorization checks succeed only if both the current user and the app have permissions to perform the action in question.

    An example of when this policy is used is when an app for SharePoint wants to get access to the user's resources on SharePoint. The code in the remote components of the app for SharePoint should be designed to make user+app calls to SharePoint.

     

  • App-only policy—When the app-only policy is used, SharePoint checks only the permissions of the app principal. 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).

    An expense approval app is an example of when this policy is used. The app allows users who wouldn't otherwise be able to approve expenses to approve expenses below a certain amount. See the scenario below for details.

    Note Note

    Certain APIs require a user context and can't be executed with an app-only policy. These include many APIs for interacting with Project Server 2013 and for performing search queries.

See an example scenario of an app that uses the app-only policy

Let's says a sales manager at Contoso, Adam, buys an expense submission app that uses the app-only policy. When Adam chooses to buy the app, Adam is prompted to allow the app to elevate user permissions; that is, to allow the app to make app-only calls to SharePoint. Adam grants the app the requested permission. He then purchases enough licenses for all of the Contoso sales people to use the app, and he installs it in the sales team's central SharePoint site.

Soon, the salespeople are submitting expense reports using the new expense submission app. Salespeople usually cannot approve their own expense reports, but they can do this when using the app because Adam granted it the ability to do this for expense submissions below $50 because he set the app to automatically approve reports below $50. The app is automatically assigns him a task to approve reports of $50 or more. This could be implemented by giving the app for SharePoint Write permission to a SharePoint list of approved expenses. But, among users, only human resources managers have Write permission to the list. The code in the app is designed to make an app-only call to SharePoint, if the expense is less than $50, to add the expense to the list. Since the user's permissions aren't checked, any user's submissions below $50 are automatically added to the approved expenses list, even if the user doesn't have Write permission to the list.

Learn how apps get permission to use the app-only policy

To be able to make app-only calls to SharePoint, your app must request the ability to use the app-only policy in the app manifest. You do this by adding the AllowAppOnlyPolicy attribute to the AppPermissionRequests element and setting it to true as shown in the following markup:

<AppPermissionRequests AllowAppOnlyPolicy="true">
    ...
</AppPermissionRequests>

A user installing the app will be prompted to approve this request. If the app asks for tenant-scoped permissions, then only a tenant administrator can grant use of the app-only policy, so only a tenant administrator can install the app. If the app does not ask for any permissions scoped higher than site collection, then a site collection administrator can install the app. For more information about permission scopes, see App permissions in SharePoint 2013.

Learn how apps make app-only calls

The difference between an app-only call to SharePoint and a user+app call is the tyoe of access token that is included in the call. The following code shows how to make obtain user+app and app-only access tokens in managed code. The detailed coding is done for you in the TokenHelper.cs (or .vb) file that the Office Developer Tools for Visual Studio automatically add to the project in Visual Studio.

string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
if (contextTokenString != null)
{
     //Get context token.
     SharePointContextToken contextToken =
          TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);
     Uri sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);

     //Get user+app access token.
     string accessToken =
          TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;

      ClientContext clientContext =
           TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), accessToken);

      //Do something. 
       ...
    
      //Get app-only access token.
       string appOnlyAccessToken = 
            TokenHelper.GetAppOnlyAccessToken(contextToken.TargetPrincipalName, 
                              sharepointUrl.Authority, contextToken.Realm).AccessToken;
         //Do something.
         ...
}
NoteNote

Apps that do not make OAuth authenticated calls (for example, apps that are only JavaScript running in the app web) cannot use the app-only policy. They can request the permission, but they will not be able to take advantage of it because doing so requires passing an app-only OAuth token. Only apps with web applications running outside of SharePoint can create and pass app-only tokens.

In general, a current user is required to be present for a call to be made. In the case of app-only policy, SharePoint creates a SHAREPOINT\APP, similar to the existing SHAREPOINT\SYSTEM user. All app-only requests are made by SHAREPOINT\APP. There is no way to authenticate as SHAREPOINT\APP through user-based authentication.

Get guidelines for using the app-only policy

Since app-only calls effectively elevate user privileges, you should be conservative in creating apps that ask for permission to make them. Calls should use the app-only policy only if:

  • The app needs to elevate its permissions above the user for a specific call; for example, to approve an expense report under conditions evaluated by the app.

  • The app is not acting on behalf of any user; for example, an app that performs nightly maintenance tasks on a SharePoint document library.

Show:
© 2014 Microsoft