Export (0) Print
Expand All

Authorization and authentication for apps in SharePoint 2013

apps for SharePoint

Get an overview of authentication and authorization in SharePoint 2013, which is used to authorize requests by an app for SharePoint to access SharePoint resources on behalf of a user.

Last modified: April 07, 2014

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

In this article
App authentication in SharePoint 2013
Authorization policies: user-only policy, user + app policy, or app-only policy
OAuth in SharePoint 2013
When is using OAuth required?
Access tokens
App permissions and app permission request scopes
Additional resources

Watch a video about app identity.

Videos

When a user signs in to SharePoint 2013, 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 2013 supports several kinds of 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 2013 uses the Microsoft Azure Access Control Service (ACS) as the app identity provider. OAuth is one of several ways for an app to be authenticated, but authorization is consistent across all apps, regardless of whether the apps use OAuth.

The authorization process verifies that an authenticated subject (an app or a user the app is acting on behalf of) has permission to perform certain operations or to access specific resources (for example, a list or a SharePoint document folder).

SharePoint 2013 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. Correspondingly, the authorization policy can be a user-only policy, a user + app policy, or an app-only policy. For example, if the user + app policy is used, both the app and the user the app is acting on behalf of must have permission to the resource the app is accessing. In the case of app-only policy, the access check only goes against the app's rights.

For more information about authorization policies for apps or users and how they work, see App authorization policy types in SharePoint 2013.

OAuth is an open protocol for authorization. OAuth enables secure authorization from desktop and web applications in a simple and standard way. OAuth enables users to approve an application to act on their behalf without sharing their user name and password. For example, it enables users to share their private resources or data (contact list, documents, photos, videos and so on) that are stored on one site with another site, without users having to provide their credentials (typically user name and password).

OAuth enables users to authorize the service provider (in this case, SharePoint 2013) to provide tokens instead of credentials (for example, user name and password) to their data that is hosted by a given service provider (that is, SharePoint 2013). Each token grants access to a specific site (for example, a SharePoint document repository) for specific resources (for example, documents from a folder) and for a defined duration (for example, 30 minutes). This enables a user to grant a third-party site access to information that is stored with another service provider (in this case, SharePoint), without sharing their user name and password and without sharing all the data that they have on SharePoint.

Note Note

This article assumes that you are familiar with the concepts and principles behind OAuth. For more information and background about OAuth, see OAuth.net and Web Authorization Protocol (oauth).

In SharePoint 2013, a typical apps for SharePoint usage scenario is as follows. A user signs in to SharePoint 2013 and is authenticated. The authenticated user then uses an Office Store or an app catalog app. The app is granted permission by the user to access SharePoint resources on the user's behalf. A SharePoint site has an app launch. When a user launches an app, SharePoint 2013 POSTs a context token to the app. The app then calls back to SharePoint 2013 to access the SharePoint resources on behalf of the user by using an access token.

Note Note

For more information about context tokens, access tokens and OAuth tokens, see OAuth authentication and authorization flow for cloud-hosted apps in SharePoint 2013 and Tips and FAQ: OAuth and remote apps for SharePoint.

The OAuth protocol is used to authenticate and authorize apps and services. The OAuth protocol is used:

  • To authorize requests by an app for SharePoint to access SharePoint resources on behalf of a user.

  • To authenticate apps in the Office Store, an app catalog, or a developer tenant.

Note Note

For example, OAuth is used in cases where calls have to be made from a remote web server to SharePoint 2013 on behalf of a user. You would not use OAuth to make a call from the app web or from a remote webpage using the client library, for example.

If the applications and services that you build for SharePoint 2013 do not require the previous authentication approach, you do not have to use the OAuth protocol when you create your applications and services. If you plan to build an app for SharePoint that runs in a remote web application and communicates back to SharePoint 2013, you will need to use OAuth.

To access resources, an app has to request app permissions. In general, delegated authorization codes or access tokens are issued by the OAuth security token service (STS). An example of OAuth STS is Microsoft Azure Access Control Service (ACS) OAuth endpoints. 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.

In SharePoint 2013, an OAuth STS is used only for issuing tokens (that is, server-to-server and context tokens). 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 2013.

But, SharePoint 2013 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 2013 implements the OAuth protocol 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 2013 takes on the role of the resource server.

  • ACS takes on the role of the authorization server.

An app for SharePoint requests permissions to access SharePoint resources by doing the following:

  • An app for SharePoint requests the permissions that it needs during installation from the user who is installing it.

  • The developer of an app must request, through the app manifest file, the permissions an app needs.

For an app to be granted the permissions it requested, the following conditions must be fulfilled:

  • An app must be granted permissions by the user who is installing it.

  • Users can grant only the permissions that they have; the user installing the app must be able to grant all permissions required by the app, or app installation fails.

An app is granted the permissions it asked for when:

  • An app is installed by a website administrator.

  • An app is explicitly granted permission by a tenant administrator or website administrator.

  • An end user gives consent.

In the app manifest file, an app requests access to specific scopes (that is, locations on SharePoint 2013). 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. In short:

  • An app uses permission request scopes to specify the permissions that it needs.

  • The requests specify both the rights and the scope that the app needs.

  • Scopes indicate where in the SharePoint hierarchy a permission request applies. SharePoint supports four different content scopes: site collection, website, list, and tenancy. There are also feature scopes for performing search queries, accessing taxonomy data, social features, Microsoft Business Connectivity Services (BCS) features, and Project Server 2013 features.

Note Note

For more information about app permissions, see App permissions in SharePoint 2013.

Show:
© 2014 Microsoft