OAuth authentication and authorization flow for cloud-hosted apps in SharePoint 2013
Published: July 16, 2012
Learn about the OAuth authentication and authorization flow for cloud-hosted apps in SharePoint 2013.
Applies to: apps for SharePoint | Office 365 | SharePoint Server 2013
In SharePoint 2013, the OAuth authentication and authorization flow for a cloud-hosted app involves a series of interactions between your app, SharePoint 2013, the authorization server, and the end user at runtime. The authorization server in this scenario is Windows Azure Access Control Service (ACS).
With a cloud-hosted app, you have a server that is separate from SharePoint 2013, and not part of the SharePoint farm. You, the app developer, own this server (let's call it the Contoso.com server). You write the code for your app and deploy the app to the Contoso.com server. The Contoso.com server can receive remote events from SharePoint 2013 to register events or changes that happen on SharePoint 2013.
For example, the Contoso.com server can use remote events to respond to events that occur to SharePoint items, such as lists or list items. Examples of remote events that the Contoso.com server might want to receive and respond to are list events, such as adding or removing a field; list item events, such as adding or removing a list item or attachment to a list item; or web events, such as adding or deleting a site or site collection. For more information about how to create remote event receivers, see How to: Create a remote event receiver.
The Contoso.com server uses the SharePoint client object model (CSOM) or REST endpoints with CSOM to make calls to SharePoint 2013. The Contoso.com app uses OAuth to authenticate with SharePoint 2013. The ACS is where SharePoint requests a context token that it can send to the Contoso.com server. Later, the Contoso.com server uses the context token to request an access token from the ACS as part of the OAuth transaction process. The Contoso.com server then uses the access token to talk back to SharePoint.
The OAuth authentication and authorization flow for a SharePoint 2013 cloud-hosted app is shown in Figure 1.
The flow, as shown in Figure 1, can involve an IFRAME, or if it is an app launch, SharePoint 2013 could do a full page navigation to Contoso.com.
A user types a URL in a browser to go to a SharePoint page where a particular app is installed. In this case, the app is a Contoso.com app and the user interface element on the SharePoint page comes from the Contoso.com app.
If the user is not already logged on, SharePoint 2013 prompts the user to log on.
SharePoint processes the page and detects that there is a component from the Contoso.com app on the page. SharePoint must get a context token that it can send to the Contoso.com app. SharePoint asks ACS to create and sign a context token that contains context information (for example, the current user, what web is being rendered on SharePoint, and other context information) and an authorization code.
This context token can be used later by Contoso.com to request an access token from ACS. The Contoso.com server can use the access token to talk back to SharePoint if the Contoso.com app wants to make a web service call to SharePoint later.
The security token service (STS), ACS in this scenario, is configured and provisioned by SharePoint 2013. The ACS is the tenant in the cloud that does the OAuth authentication. You do not have to configure it.
ACS returns the signed context token to SharePoint. The signed context token is signed with an client secret that only ACS and the Contoso.com app share.
The developer of the Contoso.com app receives the client secret value when the developer registers the app at the Seller Dashboard.
SharePoint renders the page, including an IFRAME pointing to the app host server—in this case, Contoso.com. When SharePoint renders the page, it also passes the context token to the IFRAME.
The IFRAME causes the browser to request a page from the Contoso.com server. The context token is included in the browser request that is sent to the Contoso.com server.
The Contoso.com server gets the context token. Contoso.com validates the signature on the context token. The token is signed with an client secret that only Contoso.com and ACS share. Contoso.com can validate that the token is really intended for it and that it is not a random request from some random server. It knows that it is part of a SharePoint request.
If the Contoso.com server wants to talk back to SharePoint, there is a refresh token in the context token that Contoso.com can extract, so that it can include that information in the request to ACS for an access token. Contoso.com uses the refresh token that it extracted from the context token, the context token that it got from SharePoint, and its credentials (which are its client Id value and its client secret value) to request an access token from ACS so that it can talk back to SharePoint.
The developer of the Contoso.com app receives the client Id value when the developer registers the app at the Seller Dashboard.
ACS returns an access token to the Contoso.com server. Contoso.com can cache this access token. That way, the Contoso.com server doesn't have to ask ACS for an access token every time that it talks back to SharePoint. (Or, Contoso.com can make an access token request every time and not cache the access token.)
By default, access tokens are good for a few hours at a time. Each access token is specific to the user account that is specified in the original request for authorization, and grants access only to the services that are specified in that request. Your app should store the access token securely, because it is required for all access to a user's data. For more information about access tokens, see Authorization and authentication for apps in SharePoint 2013.
Access tokens are not as long-lived as refresh tokens. By default, refresh tokens are good for about a year. So, the same refresh token can be redeemed for a new access token from ACS for about a year.
Contoso.com can use the access token to make a web service call or CSOM request to SharePoint, passing the OAuth access token in the HTTP Authorization header.
Currently, sample code is provided. The sample code is also included in Visual Studio 2012. In the future, the access token value will be written into the OAuth Authorization field in the HTTP header automatically, via the SharePoint OAuth API calls that the Contoso.com app code makes.
SharePoint returns the information that Contoso.com requested to Contoso.com.
The Contoso.com app renders the IFRAME contents as a per-user request in step 1. This completes the OAuth transaction process. The user now sees the SharePoint page fully rendered.
This article discusses the OAuth flow for cloud-hosted apps. As next steps, consider reading the following articles:
July 16, 2012