Export (0) Print
Expand All

Context Token OAuth flow for apps in SharePoint 2013

apps for SharePoint

Learn about the OAuth authentication and authorization flow for low-trust, provider-hosted apps in SharePoint.

Last modified: September 13, 2014

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

In this article
Get an overview of OAuth and SharePoint provider-hosted apps for SharePoint
Complete the prerequisites for using the flow
See the steps in the Context Token flow
Next steps
Additional resources

In SharePoint, the OAuth authentication and authorization flow for a provider-hosted, low-trust, app involves a series of interactions between your app, SharePoint, the authorization server, and the browser at runtime. The authorization server in this scenario is Microsoft Azure Access Control Service (ACS).

With a provider-hosted app, you have a remote web application or service that is separate from SharePoint, and not part of the SharePoint farm or SharePoint Online tenancy. It can be hosted in the cloud or on an on-premise server. In this article, the remote component is called Contoso.com.

Note Note

The remote component can also host event receivers that respond to events that occur to SharePoint items, such as lists or list items. Examples of remote events that Contoso.com might want to respond to are list events, such as adding or removing a list item; or web events, such as adding or deleting a site. For more information about how to create remote event receivers, see How to: Create a remote event receiver.

Contoso.com uses the SharePoint client object model (CSOM) or the SharePoint REST APIs to make calls to SharePoint. The Contoso.com application uses an OAuth token-passing flow to authenticate with SharePoint. SharePoint and Contoso.com do not trust each other; but both trust ACS and will accept tokens issued by ACS. There are three tokens involved: SharePoint has ACS create a context token that SharePoint forwards to Constoso.com. Contoso.com validates that the context token was issued by ACS so it trusts it. Contoso.com then extracts a refresh token from the context token and uses it to get an access token directly from ACS. It includes the access token in all its requests to SharePoint. SharePoint validates that the access token was issued by ACS, so it responds to the requests from Contoso.com.

You provide the token-handling code in the remote component. (But if your remote component is hosted on .NET, the Microsoft Office Developer Tools for Visual Studio provide sample code that does most of the work for you.) For details about token-handling code, see Handle security tokens in provider-hosted low-trust apps for SharePoint 2013.

There are some preliminary steps that must be done before an app for SharePoint can use the Context Token flow.

  • If the app for SharePoint is to be installed to an on-premise SharePoint farm, there are setup requirements that don't apply if it is only installed to SharePoint Online:

  • Regardless of whether the app is installed to SharePoint Online or to an on-premise SharePoint farm, the app for SharePoint must be registered with ACS. For details about how this can be done, see Guidelines for registering apps for SharePoint 2013. Among other things, the app provides ACS with its client ID and client secret as part of the registration.

The OAuth authentication and authorization flow for a SharePoint provider-hosted app is shown in the following figure.

OAuth Context Token flow

OAuth authorization process flow

These are the steps that correspond to the numbers in the figure:

  1. A user launches the app for SharePoint from SharePoint. The design of the app determines how this is done:

    • If the app is designed to surface the remote web application (at Contoso.com) in an app part (which is essentially a wrapper around an IFRAME), then launching the app simply means navigating to a SharePoint page that contains the app part. (If the user is not already logged on, SharePoint prompts the user to log on.) SharePoint processes the page and detects that there is a component from the Contoso.com application on the page. (For details about app parts, see How to: Create app parts to install with your app for SharePoint.)

    • If the app is designed to use as a full page in the browser, then the user launches it by clicking on its app tile on the SharePoint website's Site Contents page. (A variation of this is when the app includes a custom menu or ribbon item that launches the remote component.)

  2. Regardless of how the app is launched, SharePoint must get a context token that it can send to the Contoso.com application, so it asks ACS to create a context token that contains information about the SharePoint context including the current user, the remote application URL, and other information. The context token also contains an encrypted refresh token.

  3. ACS signs the context token, with an algorithm that uses the Contoso.com app secret, and returns it to SharePoint. Only ACS and the Contoso.com app know the secret.

  4. If the Contoso.com application is surfaced in an app part, SharePoint renders the page that hosts the app part and adds the context token to the URL that the IFRAME in the app part calls to get its contents. If the Contoso.com application is full page, SharePoint redirects the browser to Constoso.com and includes the context token as a part of the redirect response.

  5. The context token is included in the browser request that is sent to the Contoso.com server.

  6. The Contoso.com server gets the context token and validates the signature which it can do because it knows the client secret. This assures Contoso.com that the token was issued by ACS and not an imposter pretending to be SharePoint. Contoso.com extracts the refresh token from the context token and sends it, along with other information including the its client ID and client secret, to ACS in a request for an access token that will allow it to access SharePoint,

  7. ACS validates the refresh token so that it is assured that it issued the token, and then it returns an access token to Contoso.com. Optionally, Contoso.com can cache this access token so it doesn't have ask ACS for an access token every time that it accesses SharePoint. By default, access tokens are good for a few hours at a time. (When this article was written, the default expiration for ACS-issued access tokens to SharePoint was 12 hours, but that could change.) Each access token is specific to the user account that is specified in the original request for authorization, and grants access only to the service (in this case, SharePoint) that is specified in that request. Refresh tokens are longer lived (six months when this article was written) and can also be cached. So, the same refresh token can be redeemed for a new access token from ACS until the refresh token itself expires. (For more information about caching tokens, see Handle security tokens in provider-hosted low-trust apps for SharePoint 2013.) When the refresh token expires, the Contoso.com can get a new one by obtaining a new context token. For details about how this is done, see Get a new context token.

  8. Contoso.com uses the access token to make a SharePoint REST API call or CSOM request to spnv. It does this by passing the OAuth access token in the HTTP Authorization header. (Sample code for creating the header is provided in the Office Developer Tools for Visual Studio if your remote component is hosted on a .NET platform.

  9. SharePoint validates the access token so that it is assured the token was issued by ACS. It then sends the data that Contoso.com requested to Contoso.com or performs the create, read, update, or delete (CRUD) operation that Contoso.com requested.

  10. The Contoso.com application page renders in the browser (or in the IFRAME of the app part).

© 2015 Microsoft