Programming OAuth in Microsoft Azure and SharePoint 2013 Applications

Scot Hillier

by Scot Hillier on 7/29/2014

Share this:

Article Details

Date Revised:

Applies to:
Azure, O365 APIs, OAuth controller, OAuth security, SharePoint Online, SharePointContextProvider

Perhaps the biggest challenge that SharePoint developers face as they migrate to the cloud is the plumbing associated with OAuth security. In a previous article, I outlined as many as 12 events/redirects/actions that occur during the user authentication and app authorization process for cloud-based apps using OAuth. This type of complexity can make cloud development feel overwhelming and scare developers away. So, no one should be surprised that Microsoft is expending a lot of effort to simplify the authentication and authorization process for developers. Currently, SharePoint developers have three approaches to programming OAuth security: the SharePointContextProvider class, the Office 365 APIs, and the OAuth controller.

The SharePointContextProvider class is only used with provider-hosted apps (PHA) that are launched from within SharePoint. Using the SharePointContextProvider class allows you to reduce the OAuth token programming to just a few lines of code.

The following code shows a sample controller from my previous article on single-page applications (SPA). Notice how the access token is retrieved in just two lines of code. Because the referenced article covers this approach in detail, I won’t repeat the coverage here.


If you are creating a web application that is launched from outside of SharePoint, you can use either the O365 APIs or the OAuth Controller. The O365 APIs provide a high-level of abstraction so the code is simple, but the flexibility is low. Whereas the OAuth controller provides maximum flexibility because all of the code is available to you within the controller itself. In this article, I’ll cover these two approaches in detail.

Creating a New Project

In order to compare OAuth programming approaches, let’s create a simple task pane app that displays the titles of SharePoint lists in Word 2013. The idea is to make a simple REST call into SharePoint Online and retrieve the collection of lists. Let’s start the example by creating a new App for Office. This project will be a task pane app and target Word 2013.


Figure 1: Create the new project


Figure 2: Select Task Pane


Figure 3: Target Word 2013

The default project template for the app is based on HTML pages and JavaScript functionality. However, the O365 APIs and OAuth controller both run server side. So, the next step is to add a default controller to the project that will run before the app user interface is visible. This will allow you to get the required access token. We begin by adding a Controllers folder to the project. Next, right click the folder and select Add>>Controller.


Figure 4: Add an empty Controller


Figure 5: Name the new controller “HomeController”

Using the O365 APIs

Start by using the O365 APIs to manage the OAuth security in our new app. In order to do this, make sure that you have the Office 365 API Tools for Visual Studio installed. Using the tools, you can right click the web project and select Add>>Connected Service. After signing in, grant Read permissions on Sites.


Figure 6: Grant Read permissions to Sites

Once the permissions are granted, you can add code to our Home controller that will log in and obtain an access token for our SharePoint online resource. Then you can use that access token to query SharePoint. The following code shows how to retrieve the collection of list titles and pass them to an associated view. Note that you will need to update the SharePoint service root value to reflect your Office 365 tenant.


Before you can run the app, we have to update the start URL to refer to our new Home controller instead of the default HTML page in the project template. We also have to add App Domain URLs so that when the login redirects occur, they will show inside the task pane and not a separate window. App Domain URLs are simply the set of trusted pages that will be allowed to run in the task pane. Any other referenced URL will cause a new browser window to open. The following code shows the updated manifest for the task pane app.


When you run the app, we’ll be prompted to log into SharePoint online. The set of list titles will then appear in the task pane.


Figure 7: Task pane app in Word

Using the OAuth Controller

Now that the solution is working with the O365 APIs, we’ll modify it to work with the OAuth controller. We start by adding the OAuth controller to our project. The OAuth controller is available in GitHub, so we’ll just pull it from there and add it to the project.

The OAuth Controller provides all the functionality necessary to retrieve and cache an access token. The OAuth Controller requires you to provide the URL of your app (i.e., the redirect URL) as an input, and it will then create an authorization URL for obtaining an access token. If the user is properly logged in, no additional prompt will occur. If the user is not logged in, the app should redirect to the authorization URL. Once obtained, the access token is stored is session state, but you could easily modify the OAuth controller to save the token in a database so that it is available across sessions.

When using the O365 APIs, the web.config file is automatically updated with necessary app settings such as the Client ID and key when you use the Visual Studio tooling. When using the OAuth Controller, the same basic information is required, but you have to enter the settings manually. Additionally, the OAuth controller uses app setting names that are slightly different than those used by the O365 APIs. Table 1 shows the app settings used by each approach, and code follows showing both sets of app settings in the web.config.

Table 1: App settings

App Setting

O365 APIs

OAuth Controller

App Id



App Key



Login URL



Redirect URI








Once the web.config file is updated with the values expected by the OAuth Controller, you can modify the code in the Home controller to use the new approach. All that is necessary is to replace the O365 authentication code with the following code.



When programming OAuth security in cloud-based apps, you have three approaches: the SharePointContextProvider class, the O365 APIs, and the OAuth controller. The SharePointContextProvider is used with provider-hosted apps, while the O365 APIs and OAuth Controller are used with apps that are launched outside of SharePoint. The O365 APIs are simple, but less flexible. The OAuth Controller exposes all the security code and may be customized if necessary.

Topic: Development

Sign in with

Or register