2 out of 2 rated this helpful - Rate this topic

App authorization policy types in SharePoint 2013

apps for SharePoint

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

Last modified: December 09, 2013

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

In this article
App authorization policies types
Scenario example for apps using the app-only policy
Who can approve apps that use the app-only policy
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 OAuth authentication and authorization flow for cloud-hosted apps in SharePoint 2013.

SharePoint provides three types of authorization policies. The authenticated identities on the call determine which authorization policy is used. The authenticated identities can be user identity only, user + app identities or app identity only::

  • User-only policy—This user-only policy is the authorization policy that was always applied in SharePoint 2010. When the user-only policy is used, the authorization checks take into account only the user identity. An example of when this policy is enforced is when the user is accessing resources directly without using the app.

     

  • User + app policy—When the user + app policy is used, 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.

    An example of when this policy is used is when a SharePoint site has an embedded IFRAME that links to an Office Store app, and the app calls back to SharePoint to access SharePoint resources on behalf of the user. That is, when an Office Store app, which does not run in SharePoint Server, wants to act on behalf of the user to get access to the user's resources.

     

  • App-only policy—When the app-only policy is used, the content database 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).

    An example of when this policy is enforced is when the app is not acting on behalf of the user. An example of an app that might use this app-only policy is an expense submission app.

    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.

    For example, the person who installs the app allows the app to approve an expense submission that is equal to or less than $50, even though the users who submit the expense have no rights or authority to approve it. And, if the expense is more than $50, the app routes it to the appropriate manager for approval.

    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.

Scenario example for apps using 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. Let's say 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 tool (that is, the expense submission app Adam bought). The app prevents salespeople from approving their own expense reports, but the app is able to approve them because Adam granted it the ability to elevate user's permissions. Adam sets the app to automatically approve expense submission below $50, and he is automatically assigned a task to approve reports above $50.

Who can approve apps that use the app-only policy

Apps request the ability to use the app-only policy by specifying the policy as a property on the AppPermissionRequests collection in their app manifest. If no policy is specified, use of the app-only policy is not allowed. For example:

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

A user must be a site collection administrator to be able to grant use of the app-only policy. If the app-only policy is granted and the app already has tenant-scoped permissions, then the user must be a tenant administrator to be able to grant use of the app-only policy.

At runtime, apps opt into using the app-only policy by making a request with which they pass an app-only token. The italicized section of the following code example shows how an app can get an app-only access token (with the TokenHelper.cs file in the project):


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 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.
         ...
           }

This means that an app can choose to use an app-only policy or it can use the user + app policy token on each request. The italicized section of the following code example shows how an app can get an app + user policy access token.

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 access token.
     string accessToken =
          TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;

      ClientContext clientContext =
           TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), 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 authentication as SHAREPOINT\APP through user-based authentication.

When the app-only policy is used, content database authorization checks only take into account the app identity. In particular, when this policy is used, an authorization check succeeds if the current app has sufficient permissions to perform the action in question, regardless of the permissions of the current user, if any.

Guidelines for using the app-only policy

All OAuth and server-to-server calls should be user + app policy type calls (not app-only policy type), with the following exceptions. OAuth and server-to-server calls should use the app-only policy 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, the call is being made by the app alone, not by a user who is using the app).

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.