INTRODUCTION TO OAUTH

OAuth is an open standard managed by the Internet Engineering Task Force and is designed to allow applications to access services in a Web-friendly manner on behalf of an application or user.

Some might ask, “Why not just give the caller my username and password?” This unfortunately poses some issues that OAuth avoids:

• The app can do everything and anything your account can do. This means that if the calling code had your username and password it could, for example, change your password or do things that you would rather it didn’t have access to. Because the app has your username and password it is as if you are making the calls and the service has no idea who the real caller is.
• To the service, all calls look the same whether it is you or the calling app making the calls. This means keeping an audit trail is almost pointless because there is no way to tell who the caller really was if the same username is being used each time. Additionally, if you give your username and password to multiple services and one of them deletes information, you have no way to know which one it was. Obviously, this could cause some problems if you are not careful.
• You can’t revoke access to a particular service without changing your password. This means that you would need to update your password on all those services that you want to continue working. If a few services are involved this task can be error-prone and cumbersome.

Here is a simple analogy to help explain this concept. Imagine an office building that is secured using swipe cards. A lot of sensitive information is stored in this office building and many people work in it each day. Now imagine each of those workers were issued the exact same swipe card. From the door lock–system logs you couldn’t tell who was accessing the building and when. Additionally, if you fired a worker and she didn’t give her swipe card back you would need to reissue everyone one else a new key. This is the same as sharing your username and password.

To solve these issues, OAuth introduces the concept of an application identity or application principle. This is simply an identity given to an app much the same way a user has a username and password. It offers the ability to control and manage access to resources at an application level versus a user level, and therefore you don’t need to give an app your username and password to access any desired resources. Furthermore, this means an app’s access can be monitored, audited, and revoked if needed. For an app to gain access to a service the user must deliberately grant that specific application access to that specific service. Access is only granted once that app identity is checked and verified as valid with permissions to the resource. This access may be scoped to specific resources within the service. This means, for example, that the user could grant the app access to some data, but not to change the user’s password. This also means that a user may revoke an app’s access to the service at any time without needing to affect other applications’ access.

So, revisiting the analogy, if the building security system used an OAuth style access system, each worker in the building would be granted an ID, and then his swipe card with that ID on it would be granted access to the particular areas of the building that he was allowed to be in. When a worker is revoked access, the building owner simply revokes access for that worker’s ID in the system. That way when the worker tries to swipe in he is denied access. Or, in the case when a worker changes departments, the building owner simply signifies that for that particular ID the person is now denied access to Level 1, for example, and is allowed access to Level 2. It’s the same in OAuth. Each app (the equivalent of a person in the analogy) is granted an ID and a set of privileges. When the caller tries to access a resource, the ID is verified and a check is made to ensure he is allowed access to that particular resource. If access is allowed, the call proceeds and if not, the caller is denied.

OAuth is supported and used by many large services on the Internet today such as Facebook and Twitter. Numerous open source libraries exist for various languages to assist with the standard OAuth messages involved in authorizing and calling a service. The SharePoint 2013 app framework and tools also include many helper libraries and functions to wrap a lot of the underlying OAuth protocol exchanges. In many cases a developer might never be aware of the communication and messages OAuth uses behind the scenes.

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.