Authorization and authentication of SharePoint Add-ins
Get an overview of authentication and authorization in SharePoint, which is used to authorize requests by an app for SharePoint to access SharePoint resources.
Last modified: September 13, 2014
Applies to: apps for SharePoint | Office 365 | SharePoint Add-ins | SharePoint Foundation 2013 | SharePoint Server 2013
The name "apps for SharePoint" is changing to "SharePoint Add-ins". During the transition, the documentation and the UI of some SharePoint products and Visual Studio tools might still use the term "apps for SharePoint". For details, see New name for apps for Office and SharePoint.
In this article
App authentication in SharePoint
Authorization policies: user-only policy, user+app policy, or app-only policy
App permissions and app permission request scopes
When is OAuth used?
When a user signs in to SharePoint, the user's security token is validated. The token is issued by an identity provider. SharePoint supports several kinds of user authentication. For more information, see Authentication, authorization, and security in SharePoint 2013.
Apps for SharePoint are also security principals that need to be authenticated and authorized. Apps can be authenticated and authorized in several different ways. For more information, see Three authorization systems for SharePoint Add-ins 2013.
The authorization process verifies that an authenticated subject (an app or a user or both) has permission to perform certain operations or to access specific resources (for example, a list or a SharePoint document folder).
SharePoint users three types of authorization policies. The user-only policy requires only that the call to SharePoint include an authenticated user identity. The app-only policy requires only that the call include only an authenticated app identity. The user+app policy requires that the call include both kinds of authenticated identities. When a user accesses SharePoint resources through the SharePoint UI, instead of through an app, SharePoint uses the user-only policy. However, for calls from an app for SharePoint, SharePoint always uses either the app-only or the user+app policy. The app for SharePoint determines which policy is used by the type of access token that it includes in its request to SharePoint. If a user+app request is made, SharePoint will require that both the app and the user have permission to the resource the app is accessing. In the case of an app-only request, SharePoint requires that the app have permission to the resource, but it does not matter whether the user does or not. (An app for SharePoint can make app-only requests only if it has been given permission to do so in advance; typically, when it is installed.)
For more information about authorization policies and how they work, see Add-in authorization policy types in SharePoint 2013.
The developer of an app for SharePoint must specify, through the app manifest file, the permissions an app needs to SharePoint resources outside the app web. (The app automatically has full control permission to the entire app web.) When the app is designed to be launched from within SharePoint, the app installation infrastructure prompts the user who installs the app to grant or deny the needed permissions. Once the permissions have been granted, users of the website can use the app without having to re-grant it permissions. However, when the app is designed to be launched outside of SharePoint; that is, it is not installed on SharePoint, then SharePoint will prompt the user who is executing the app to grant the needed permissions each time the app is run. Apps on mobile devices and apps for Office are examples of apps that can access SharePoint, but are not installed on it.
Only a website owner can install an app for SharePoint on a SharePoint website (unless a custom role has been created that has app installation rights). A user can grant an app only those permissions that the user himself or herself has. So a user cannot install an app that needs permissions the user doesn't have. Similarly, a user cannot run and externally launched app that needs permissions that the user does not have. However, when an app for SharePoint is installed on SharePoint, it can ask for permission to make app-only calls. An app that has that permission can access SharePoint in ways that the user running the app does not have permission to do.
Apps can also have permissions revoked or granted by SharePoint Online tenant administrators or SharePoint farm administrators.
In the app manifest file, an app for SharePoint specifies the permissions that it needs to function correctly. The permission requests specify both the rights that an app needs and the scope at which they need the rights. Scopes indicate where in the SharePoint hierarchy a permission request applies. SharePoint supports four different content scopes: tenancy, site collection, website, and list. There are also special scopes for performing search queries, accessing taxonomy data, social features, Microsoft Business Connectivity Services (BCS) features, and Project Server 2013 features. For more information, see Add-in permissions in SharePoint 2013.
You may have already heard that OAuth 2.0 plays an important role in the authentication and authorization of apps for SharePoint. It does, but it is not necessarily a part of the authorization story for every app for SharePoint. If you plan to build an app for SharePoint that runs in an remote web application and communicates back to SharePoint using server-side code, you will need to use OAuth. If the remote web application is off premise, then you would use the low-trust authorization system in which Azure ACS is the access token issuer. If it is on premise, then you would typically use the high-trust system in which the app itself and a digital certificate are the access token issuers.