Authorization and authentication for apps in SharePoint 2013
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: July 14, 2014
Applies to: apps for SharePoint | Office 365 | SharePoint Foundation 2013 | SharePoint Server 2013
In this article
App authentication in SharePoint
Authorization policies: user-only policy, user + app policy, or app-only policy
OAuth 2.0 in SharePoint 2013
When is OAuth used?
App permissions and app permission request scopes
When a user signs in to SharePoint, the user's token is validated and then used to sign in to SharePoint. The user's token is a security token that is issued by an identity provider. SharePoint supports several kinds of user authentication. For more information, see Authentication, authorization, and security in SharePoint 2013.
In the case of app authentication, the authentication process verifies a claim that is made by a subject (in this case, an app) that it should be allowed to act on behalf of a given principal (in this case, an authenticated SharePoint user). Apps can be authenticated in several different ways. When a call is made to an app web, for example, unless that call is an OAuth call, the call is attributed to the app associated with the app web (in addition to the authenticated user). If it is an OAuth call, SharePoint uses the Microsoft Azure Access Control Service (ACS), or a digital certificate as the app identity provider.
For more information about OAuth calls to SharePoint, see Creating apps for SharePoint that use ACS authorization and Creating apps for SharePoint that use high-trust authorization.
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 authenticated identities on a particular call to SharePoint determine which authorization policy SharePoint uses. The authenticated identities can be the identity of only the user, the identity of only the app for SharePoint, or both identities. Correspondingly, the authorization policy that SharePoint uses can be the user-only policy, the app-only policy, or the user + app policy. For example, when a user accesses SharePoint resources through the SharePoint UI, instead of through an app, SharePoint uses the user-only policy. SharePoint always uses either the app-only or the app + user policy for calls from an app for SharePoint. The app determines which policy is used by the type of access token that it includes in its request to SharePoint. If the 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 App 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, then SharePoint will prompt the user who is executing the app to grant the needed permissions each time the app is run.
Only a website owner can install an app for SharePoint on a 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 (or run, in the case of an externally launched app) an app that needs permissions the user doesn't have.
Apps can also have permissions revoked or granted by tenant administrators or SharePoint web application administrators.
In the app manifest file, an app for SharePoint uses a permission request to specify 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 about app permissions, see App permissions in SharePoint 2013.
OAuth 2.0 is an open framework for authorization. OAuth enables secure authorization from desktop and web applications in a simple and standard way. OAuth enables a user to approve an application to act on his or her behalf without sharing his or her user name and password. For example, it enables a user to share his or her private resources or data (contact list, documents, photos, videos and so on) on one site with another site, without requiring the user to provide his or her credentials (typically user name and password).
OAuth enables users to provide access tokens, instead of credentials (for example, user name and password), to their data that is hosted by a given service provider (such as SharePoint). Each token grants access to a specific resource provider (such as a SharePoint website) for specific resources (for example, documents in a SharePoint document library) and for a defined duration (for example, 12 hours). This enables a user to grant a third-party web or desktop application access to information that is stored with another resource or service provider (such as SharePoint), without sharing his or her user name and password and without sharing all the data that he or she has on SharePoint.
A typical apps for SharePoint scenario is as follows. A user signs in to SharePoint and is authenticated. The authenticated user then installs an app for SharePoint from either the Office Store or the app catalog. The app is granted permission by the user to access SharePoint resources. When an authenticated user (not necessarily the same one who installed the app) launches the app, SharePoint POSTs a context token to the app. The app then calls back to SharePoint to access the SharePoint resources on behalf of the user by using an access token.
For more information about context tokens and access tokens, see OAuth authentication and authorization flow for cloud-hosted apps in SharePoint 2013 and Tips and FAQ: OAuth and remote apps 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 ACS authorization system in which ACS is the 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 token issuers.
The OAuth 2.0 framework uses token passing "flows" to:
Authorize requests by an app for SharePoint to access SharePoint resources.
Authenticate apps in the Office Store, an app catalog, or a developer tenant.
To access resources, an app has to request an access token from an OAuth security token service (STS) that has previously been designated as a trusted token issuer by the resource owner. An example of an OAuth STS is Microsoft Azure Access Control Service (ACS). In contrast, the WS-Federation STS and the Security Assertion Markup Language (SAML) passive sign-in STS are primarily intended to issue sign-in tokens. For more information about ACS, see Creating apps for SharePoint that use ACS authorization and it's child topics.
In SharePoint, an OAuth STS is not used for issuing sign-in tokens, that is, they are not used as identity providers. So, you will not see an OAuth STS listed in the user sign-in page, the Authentication Provider section in Central Administration, or the people picker in SharePoint.
SharePoint administrators can use Windows PowerShell commands to enable or disable an OAuth STS. SharePoint administrators are able to enable or disable OAuth for a given web application, similar to how they can enable or disable trusted login providers in SharePoint 2010.
SharePoint implements the OAuth 2.0 framework to allow apps that are running external to SharePoint to access protected SharePoint resources on behalf of a resource owner. In the SharePoint incoming implementation of the protocol, the OAuth roles are played by the following components:
External apps take on the role of the client.
SharePoint users take on the role of resource owner.
SharePoint takes on the role of the resource server.
ACS takes on the role of the authorization server when the ACS authorization system is used. When the the high-trust system is used, the app itself (along with a digitial certificate) becomes the authorization server.