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
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
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
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
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
Table 1: App settings
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