Sharepoint 2013 : SharePoint App Security - Establishing app identity by using OAuth (part 1) - Understanding app principals

At a high level, it is fair to say that OAuth is primarily used for external app authentication in the Office 365 environment, whereas S2S authentication is used for external app authentication in on-premises farms. A common question is whether a company can use OAuth in on-premises farms. The answer to this question is—of course—it depends.

Although it is technically possible to configure OAuth support for external app authentication in an on-premises farm, you have to remember that the OAuth implementation in SharePoint 2013 is tightly coupled to Windows Azure ACS. The technical requirements for configuring OAuth support in an on-premises farm include obtaining an Office 365 tenancy from Microsoft and synchronizing user accounts between the on-premises farm and this Office 365 tenancy. Additional configuration is required to create trusts so that the local on-premises SharePoint farm and the remote web can both communicate with Windows Azure ACS.

The key takeaway is that OAuth is only supported in scenarios in which it is acceptable to have dependencies on Microsoft-hosted authentication servers in the cloud. OAuth cannot be used in a scenario in which you are required to avoid dependencies outside the LAN in which you are hosting an on-premises SharePoint farm and the remote web for a provider-hosted app.

The OAuth 2.0 protocol defines a flow for app authentication, which involves the following four participants.

Content owners represent the users who can grant access to the content in a site. In a SharePoint 2013 environment, a content owner has permissions to access objects such as sites, lists, and items, and can consequently grant these same permissions to an app.

The client app represents that part of a website that runs across the network. In a SharePoint 2013 environment, the client app is the portion of the app that runs in the remote web.

The content server is the web server that hosts the site with content. In a SharePoint 2013 environment, the content server is a web server hosted within the Office 365 environment that provides access to SharePoint sites within an Office 365 tenancy for a specific customer.

The authentication server is a server that creates access tokens used for app authentication. The authentication server must be trusted by both the content server and the client app. In a SharePoint 2013 environment, the authentication server is always Windows Azure ACS.

When it comes to registering the app principal for an autohosted app, things are pretty easy. That’s because the app principal is registered transparently behind the scenes as part of the app installation process.

When it comes to registering the app principal for a provider-hosted app, there are extra steps involved. The app principal must be explicitly registered by a user that possesses administrative permissions within the hosting Office 365 tenancy.

There are several ways by which you can register an app principal for a provider-hosted app in an Office 365 tenancy. The easiest way to do so is to use a standard application page named AppRegNew.aspx that was added to SharePoint 2013, as shown in Figure 1. As you can see, the AppRegNew.aspx page uses the terms App Id and App Secret instead of client ID and client secret. However, you have already learned that these are just different terms that refer to the client ID and the client secret.

A second way to register an app principal for a provider-hosted app in the Office 365 environment involves using the SharePoint Online Windows PowerShell Library. This is a Windows PowerShell library that you install on a local computer that provides cmdlets with which you can create a remote connection to your Office 365 tenancy. After you have established an authenticated connection, the SharePoint Online Windows PowerShell Library provides additional cmdlets with which you can manage various aspects of your Office 365 tenancies, including creating and managing app principals.

The OAuth 2.0 protocol involves passing various types of security tokens between Windows Azure ACS, the hosting Office 365 tenancy, and the remote web. The following list shows the different types of security tokens that are passed between the participants when authenticating an app by using OAuth.

The context token is a security token that’s used to pass contextual information such as the identity of the current user, the URL of the host web, and the ID of the current tenancy. The context token is created by Windows Azure ACS and initially passed to the SharePoint host environment. The SharePoint host environment is then able to pass the context token to the remote web, where it can be accessed and used by server-side code in the remote web.

The refresh token is included within the context token that is passed to the remote web. The value of the refresh token is that it can be used by code in the remote web to obtain an access token from Windows Azure ACS.

When a refresh token is created, it’s good for a period of 6 months, whereas an access token is only good for 12 hours. Therefore, it often makes sense for an app to store refresh tokens in a database from which they can be retrieved and reused to create access tokens on demand.

The access token is what the server-side code in the remote web actually needs to execute authenticated calls back to the SharePoint host environment by using CSOM or the REST API. Therefore, the remote web requires code to explicitly call into Windows Azure ACS and obtain access tokens when required.

An authorization code is a special type of security token used for a scenario in which an external website that has never been installed as a SharePoint app wants to acquire permissions on the fly to call in to a SharePoint site.

Now that you have learned about the different types of security tokens, you can understand how the app authentication flow works in a typical scenario with a cloud-hosted app that has been installed in an Office 365 tenancy. Figure 2 shows 10 different stages within the OAuth authentication flow as security tokens are passed back and forth between the Office 365 tenancy, Windows Azure ACS, and the remote web of the cloud-hosted app.

Let’s begin with stage 1, when the user first accesses a page in a SharePoint site within an Office 365 tenancy. The user is authenticated and a SAML token is created that contains information about the user identity such as the user’s logon name.

In stage 2, the user navigates to the Site Contents page in which the SharePoint host environment must display a tile that the user can employ to launch the app. When the SharePoint host environment needs to create a tile with an app launcher, it must first call to Windows Azure ACS and request creation of a context token.

When the SharePoint host environment calls to Windows Azure ACS to create a context token, it passes information about the current user, the host web, and the current tenancy. Windows Azure ACS needs this information because it must add information about the current user, the host web, and the current tenancy inside the context token. In stage 3, Windows Azure ACS creates the context token and returns it to the SharePoint host environment.

In stage 4, the SharePoint host environment has the context token returned from Windows Azure ACS. The SharePoint host environment makes use of the context token by adding it into the JavaScript code for the app launcher on the Site Contents page.

Stage 5 occurs when the user clicks the tile for the app on the Site Contents page and launches the app. The JavaScript code behind the app launcher redirects the user to the app’s start page in the remote web by using an HTTP POST request. When the HTTP POST request is executed, the context token is passed to the remote web by using a form variable named SPAppToken.

In stage 6 the client app retrieves the context token from SPAppToken in the incoming request to the state page. The client app is then able to read what’s inside the context token to obtain information about the current user, the host web, and the current tenancy. The client app also has the ability to extract the refresh token from the context token.

Stage 6 is where the client app calls to Windows Azure ACS to request an access token. When requesting an access token, the client app must pass the refresh token. In stage 7, Windows Azure ACS creates the access token from the refresh token and passes it back to the client app. Note that Windows Azure creates an access token that has both the identity of the app as well as the identity of the current user.

Once the client app has obtained an access token from Windows Azure ACS, it is finally at a point at which it can make an authenticated call to the host web by using either CSOM or the REST API. Stage 8 shows the client app making a CSOM or REST API call on the host web. When making this type of call, the client app must include explicit programming to ensure that the access token is passed in each call using an HTTP header.

In Stage 9, the SharePoint host environment is able to authenticate the call from the app by using the access token. As long as the SharePoint host environment is able to determine that the authenticated app and the current user both have the proper permissions, it returns content back to the client app.

In the final stage, stage 10, the client app is able to return a page from the remote web that displays content from the host web that was retrieved during stages 8 and 9.

You have now seen the end-to-end flow of authentication that’s used in an OAuth scenario.