OAUTH IN SHAREPOINT 2013

SharePoint apps use OAuth to authorize calls to SharePoint APIs. When an app calls an API in SharePoint to, for example, get some list data, SharePoint checks that the app identity is valid and has permissions to the resource; for example, a list. Additionally, the app may pass information about what the calling user identity is so that SharePoint can also check that the user has access to the resource. When discussing OAuth in the context of SharePoint, the following standard naming conventions are commonly used and therefore worth understanding:

• Content owner: The user who installs the app and grants the application access to particular resources.
• Client app: The SharePoint app that uses an API to access and make calls to the content server (SharePoint).
• Content server: The SharePoint environment that has the resources the client app wants to access.
• Authentication server: A service that both the client app and content server trust that creates the various tokens used in the OAuth process. In SharePoint the Authentication server is either Azure Access Control Services (ACS) in the case of Office 365 or a Security Token Service (STS) hosted with SharePoint in the case of SharePoint on premises.

When you’re building SharePoint apps, the three different app types fall into two distinct categories in regard to authentication and authorization:

• Internally authenticated apps: Includes SharePoint-hosted apps
• Externally authenticated apps: Includes Autohosted and Provider-hosted apps

The key difference between these two categories is that externally authenticated apps must explicitly authenticate with SharePoint, whereas internally authenticated apps do not. Take, for example, the case of a SharePoint-hosted app with some client-side code that uses the JavaScript Client-Side Object Model (CSOM) to create a SharePoint list item. In this case the JS code doesn’t need to authenticate explicitly with SharePoint. This is considered internal authentication because the code is served from the SharePoint domain.

An externally authenticated app is one where the code runs outside of the security boundary of SharePoint. For example, when your app code is running in Azure, that code must authenticate with SharePoint using OAuth prior to making API calls. As part of this process several important IDs, secrets, and “tokens” are used to authenticate and authorize a user and calls to the APIs:

• Client ID
• Client secret
• Context token
• Access token

The client ID and client secret are pre-issued identifiers and secret strings that only SharePoint and the app know about. These are shared and are used to sign the various tokens involved in the process.

The context token includes information about who the caller is and the Security Token Service (STS) that signed and issues tokens for this server. It also includes a “refresh token” that is used to request access tokens.

The access token is a token passed when accessing an API and is requested from the STS by the app when it needs to make calls.

The following sections show you how to create and manage client IDs and secrets, how the various parts of the authentication flows work, and how apps are granted access to various SharePoint resources.