2. SharePoint Online Authentication Patterns
Authentication options for connecting to SharePoint Online
Purvin Desai
I am Purvin Desai, and I work for Rapid Circle in Pune. I have been building products on top of SharePoint, Azure, and Office 365.
Architect
5th April 2017

3. Authentication Models
SharePoint Add-In Models:
Add-In Only
User + Add-In
O365 API Models (or Azure AD Authentication):
Application Model (Certificate)
Delegate Model
Cloud Service Account (Legacy):
Username and Password
Some time back, I was working on a very large migration project. I was told, that it was one of the largest migration projects from BPOS-D to SharePoint Online. BPOS-D was the Microsoft-hosted version of SharePoint 2010, and the D is for a Dedicated instance.
One of the things I was assigned to do, was help migrate all existing SharePoint applications, from the BPOS-D environment to current SharePoint Online. There were hundreds of applications to be migrated. When I started to talk to the application developers, each of them told me how they connected to SharePoint. One was using a provider-hosted application, another was a SaaS, etc.
From that exercise, I was able to build an exhaustive list of different types of applications that can be built on top of SharePoint, and the different kinds of authentication mechanisms that be used to connect to SharePoint.
Which I wish to share with you today.

4. Terminology 1
Before we talk about authentication methods, let us look at different types of applications
Footer
Date Month 2016

5. Types of SharePoint Online applications
SharePoint Add-ins
SharePoint Framework
SharePoint-Hosted
Provider-Hosted
Centered around SharePoint components including lists, pages, WebParts, workflows, libraries, are more.
Business logic is JavaScript on custom SharePoint pages
No server-side code
Centered around a remote web application or data source.
Business logic mainly remote server-side code.
Can include SharePoint components
Can be used in alternative scenarios where only client-side scripting is required.
Runs in context of the page with full power of the user viewing the part
Full trust client-side solutions
What are the different types of applications that you can build for SharePoint Online?
Before, SharePoint Framework came, we built SharePoint Add-ins.
There are two kinds of SharePoint Add-ins: SharePoint-Hosted and Provider-Hosted
SharePoint-Hosted applications are client-based applications, whose business logic is written in JavaScript, and can also provision SharePoint artefacts like Lists and Libraries, WebParts, etc.
Provider-Hosted applications are server-based applications, whose business logic is written in remote server-side code.
Add-ins are limited to the permissions that the add-in was granted at install time. For e.g., if the add-in was granted read-only permission to a list, the user cannot update the list through that add-in, even if the user has modify permissions on the list.
The add-in app parts run in their own domain inside an iFrame, and not in the context of the SharePoint page.
Then we have SharePoint Framework.
Can you tell me the difference between a SharePoint Framework application, and SharePoint Add-in?
It runs within the context of the page, with the full privileges of the current logged-in user. But you can only write client-side solutions with SharePoint Framework.
Hence, it is also called as full trust client-side application.
Since, there is no restrictions on the permissions of a SharePoint Framework application, there is no App Store for SharePoint Framework application. And because you can control the permissions of an Add-in, they have been able to build an app store, and make it available.
Add-ins are limited to the permissions that the add-in was granted at install time.
App parts, instead of running in the context of the page, they run in their own domain within an iFrame.

6. Types of SharePoint applications
JavaScript Embedded Applications
Connected Applications
Embed or Inject
Script-Editor
SharePoint Add-ins
Office 365 API
Arbitrary JavaScript inserted to sites and pages, by using Custom Actions, mater pages, or page layouts
Script editor web parts
Arbitrary HTML, JavaScript, or CSS customizations
Using SharePoint ACS method
Azure Active Directory Applications
Allows the script code to run in the full context of the users
These solutions built by using JavaScript embeddings could potentially break whenever SharePoint Online is updated
Server-side applications
Background applications like windows service applications or Azure WebJobs
Mobile applications
Apart from these, are there any other kind of applications that can built on top of SharePoint?
If you just wanted to write JavaScript customisations, you did not need a SharePoint-Hosted application. You could inject JavaScript with Custom Actions, or through Master Pages, and Page Layouts. You could write JavaScript customisations, and could update the UI via DOM manipulation.
However, one, this is not possible now with Modern Pages, and two, even with classic pages, there is constant risk that these applications will break whenever SharePoint Online updates it’s default Master Pages.
Are there any other type of applications that are possible?
While there is no official term for these category of applications, let us call them “Connected Applications”.
These are either desktop client applications, or server-side applications that run in the background as a windows service, or as an Azure WebJobs. These also could be a SaaS solution, that runs on an independent domain, and connects to multiple SharePoint tenants.
So, anything that connects to an SharePoint environment which is not an Add-in, or SharePoint Framework package, and not merely an JavaScript injection falls under Connected applications. Even mobile applications can be considered as a Connected application.
The word “Connected application” is not a term that is devised by Microsoft, but there is no official category to put all these applications into. However, we can divide them based on how they authenticate.
There are two main ways, how these applications can authenticate with SharePoint. One is with the SharePoint ACS method, and another using the Azure AD authentication. We will look into these two options in detail. There is also another method using a “Service account”, but that method is to be used in only in very, very specific scenarios.

7. Add-In Only User + Add-In Only
SharePoint Add-In Models 2
Add-In Only User + Add-In Only
First, we will look at SharePoint Add-In authentication options. Here, we will talk about how is a provider-hosted application connected, and how can a connected application use this model.

8. SharePoint Add-in Model
Implements what is called the “Low Trust” Model.
A provider-hosted SharePoint Add-in registers with the Microsoft Azure Access Control Service (ACS), which then issues an access token to the add-in allowing it to access resources on the SharePoint tenant on which it’s installed.
Azure ACS is the trusted token issuer in an OAuth 2.0 Framework "flow" that includes SharePoint and the remote components of the add-in.
Note: There is a “High Trust” model, however this is generally applicable to on-prem deployments.
A provider-hosted application uses a “low-trust” model, in which it registers itself with Microsoft Azure Access Control Service, which then issues token to the add-in allowing it access resources on the SharePoint tenant.
Here, the mechanism uses a Client ID, and a Client Secret. The ACS signs the context token that uses the Client Secret provider by the application, in this case, it is contoso.com, and returns it to SharePoint. Only the ACS, and the Contoso.com add-in know the Client Secret.
There is also a “High-trust” model, that is used for server-to-server communication between the SharePoint server and the application server which does not require any ACS.

9. SharePoint Add-In Model
Client Secret and Client ID
Client ID is used to identify your application.
Client Secret is a string used to verify your applications identity.
You need to ensure these are stored safely, and securely at all times. Treat them like a username and password.
If this information is exposed, then you need to take steps to change them.
Never store in plain text, and never hard code in your application.
A Client ID, and a Secret, is just like username and password. So it needs to be treated with sensitivity, and ensure that they are stored securely at all times. Make sure, you either encrypt them and never hard-code them in your application.

10. SharePoint Add-In Model
Scope and Rights that can be requested by Applications:
Add-In can perform any operation that it has requested, to support doing:
Scope: eg. Tenant, Site Collection, Site, List.
Rights: eg. Read, Write, Full Control, Manage.
You can perform Tenant-level, Site Collection level, Site level, or list level operation. As we saw earlier, the permissions are determined by the Add-in, when it is installed.
You can also control whether you allow to just read content, perform updates, and manage lists.

11. SharePoint Add-In Model: Add-In Only
Highlights:
Operates as an Application only
Does not require any interactive action by a user to authenticate.
Trust is established via the application manifest, which is registered either via a .app package, or the AppInv.aspx page, done by a user with appropriate permissions.
Add-In can perform any operation that it has requested.
When performing actions as an Application Only token retrieved by:
string addinOnlyAccessToken = TokenHelper.GetAppOnlyAccessToken(contextToken.TargetPrincipalName, sharepointUrl.Authority, contextToken.Realm).AccessToken;
Now, there are three-kinds of add-in authorization policy types. The first one is Add-In policy.
When the add-in-only policy is used, SharePoint checks only the permissions of the add-in principal. Authorization checks succeed only if the current add-in has sufficient permissions to perform the action in question, regardless of the permissions of the current user.
If you gave your add-in permission to modify the artefacts of a Site Collection, but the current user has only read permissions, she will still be able to make those calls.
Here, operations are performed without considering current user’s permissions,

12. SharePoint Add-in Model: Add-In Only
Examples of appropriate applications:
Any external applications that need to be able to connect to SharePoint content with a specific permission level. Includes console applications, web applications or windows services.
Solution which pulls the contents of a list on a nightly basis in order to drive a KPI Dashboard, or that performs nightly maintenance on a document library and which shouldn’t be associated to a user.
Examples of inappropriate applications:
Applications that need to perform operations as though they were the currently logged on user.
Another example is when an example is of a connected application, such as, a console application, or a windows service, or an Azure Web Job, which wants to, say, retrieve user profile properties of all the SharePoint users, or a solution that builds a KPI Dashboard by aggregating all the information in various SharePoint lists, and runs in the background.
Anything application that requires to perform operations, as the current logged-in user, cannot be covered under this policy. So, if you wanted to show list items that o

13. SharePoint Add-in Model: Add-In Only
/_layouts/appregnew.aspx
/_layouts/appinv.aspx
If it is a provider-hosted application, the permissions are mentioned in the app package. But if it is a connected application, then the application is registered through appregnew.aspx, and the permissions are updated through the appinv.aspx.
This method is typically called the “SharePoint ACS” method.

14. SharePoint Add-in Model: User + Add-In
Highlights:
This is the default model, and requires use of the App Catalog, a .app package, and appears as an “Apps from your organization”
Can operate either as a User + Application or Application Only, so it’s a superset of the Add-In Only model
Trust is established at the point in time the Application is added to the site, the user performing the trust of the Application must have at least the permissions requested by the Application in the manifest.
When performing actions as the User + Application token retrieved by:
string accessToken = TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;
When performing actions as an Application Only token retrieved by:
string addinOnlyAccessToken = TokenHelper.GetAppOnlyAccessToken(contextToken.TargetPrincipalName, sharepointUrl.Authority, contextToken.Realm).AccessToken;
Another model, is the User+Add-In model, where SharePoint checks the permissions of both the current user as well as the Add-In principal. The operation is completed only if both the current user and the add-in have the permission to perform it.
The user performing the action, must have the permission requested in the application manifest.
In this case, you can either create a User+Add-In token or an Add-In only token, based on the type of call you wish to make.

15. SharePoint Add-in Model: User + Add-In
Examples of appropriate applications:
Any applications that are suited to the “Add-In Only” approach and that additionally need to perform operations as a user.
Examples of inappropriate applications:
Applications that don’t need to perform operations under the context of a user.
Any applications identified as inappropriate in the “Add-In Only” approach section.
For example, a SaaS application, may need to perform certain actions on behalf of the user, such as listing Sites or Lists that belong to the user, but may have a certain task that aggregates information in a background task to build a Dashboard.
In this case, you would be using two different types of tokens. One for the user interface, and the add-in only for the background task.

16. Application Model (Certificate) Delegate Model
O365 API Models (Azure AD Authentication) 3
Application Model (Certificate) Delegate Model
Instead of using a SharePoint ACS token, to connect to SharePoint, you can also use Azure AD based App registration method to authenticate with SharePoint.

17. Office 365 API
The Office 365 API services use Azure Active Directory (Azure AD) to provide secure authentication and authorization to users' Office 365 data. Azure AD implements authorization flows according to the OAuth 2.0 protocol.
Therefore, enabling your app to authenticate in order to access Office 365 data consists of two basic steps:
Register your app with Azure AD
Implement code in your app that handles the appropriate authentication flow
For this to work, first you need to register you app with Azure AD, and implement the authentication flow in your code. Microsoft has rich libraries supporting this flow, that can be implemented.

18. Office 365 API: Application Permissions
Highlights:
Operates as an Application Only.
Does not require any interactive action by a user.
Requires tenant administrator consent.
Not supported for use by native client applications.
Once authorised, communication to API is achieved via the use of a certificate.
Note: Application Permissions are granted at the Tenant scope *only*. This means if ”Read” access is requested, the application will be able to read all content, in all site collections in the Tenant.
Again, in this method, there is Application Permissions, which is similar to the Add-In Only model. Which means, the application can perform operations, regardless of the permissions of the current user.
Application permissions can only be consented by an administrator because they are typically powerful and allow access to data across user-boundaries, or data that would otherwise be restricted to administrators.
For this to work with SharePoint, one first needs to install a certificate on the server when the calling application resides. The certificate credentials, are then updated against the application registered in Azure AD.
This approach, does not work with Native Client registrations. I think, this is mainly because, a native application is expected to perform in the context of a user, and secondly, since there is certificate involved there is no way to install the certificate on each device the Native Client is present.
For example, an app that has the User.ReadWrite.All application permission can update the profile of every user in the organization.
Even though, this is the preferred way to communicate with SharePoint, this approach has one limitation:
All permissions apply to “all site collections”. For e.g. If you wanted to create an application that needs to read items from a specific list, of a specific site, you would end up giving read permissions to the whole tenant. There is no way to specify that you wish to grant access to this specific list or site.
This is important, because of the principle of least priviledge. This helps you reduce the risk exposure of your application. Say, you have written a SaaS application, and have onboarded multiple clients. And to read or update items from one particular list from each of their environments, you have used this method which gives your application to read items for all the site collections of those tenant.
Now, if something wrong happens in their environment, even if it is not your applications fault, your application will need to be audited to see if it had caused the damage.

19. Office 365 API: Delegated Permissions
Highlights:
Operates under the context of a user.
Requires a user to log on interactively in order to perform actions on their behalf.
Requires only user consent, and once given, has access to the permissions requested by the application
Once authorised, communication to API is achieved via the use of a token.
Azure AD Delegated Permissions is recommended if you are building an application that needs to talk to the O365 Graph API, One Note API, and SharePoint sites.
Delegated permissions operate under the context of a user. When you grant read access to a user, through Delegated Permissions, the application will be able to read all items that this particular user has.
In this case, no certificate is required. It works only through a client Id, and secret. And requires that a user is logged on via a browser or a native application to perform the action.
For these apps, either the user or an administrator consents to the permissions that the app requests
Your app can never have more privileges than the signed-in user.
For example, assume your app has been granted the User.ReadWrite.All delegated permission in Microsoft Graph. This permission nominally grants your app permission to read and update the profile of every user in an organization. If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. However, if the signed-in user is not in an administrator role, your app will be able to update only the profile of the signed-in user. It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.
Background applications won’t work in this case.
This is the most preferred authentication method to connect to SharePoint, if your application needs to work with user context.

20. Office 365 API
Both the methods, give access to “all site collections”, rather than specific sites.
Footer
Date Month 2016

21. Cloud Service Account 4
Cloud Service Account is nothing but a username and password created in Azure AD to perform operations by connecting to SharePoint via code.

22. Cloud Service Account Highlights:
Direct equivalent of Service Accounts.
They can be used for third-party applications that cannot authenticate with SharePoint Online by any of the previous methods described in this document.
Password resets every 90 days.
MFA will not work in this scenario.
Standard best practices for storing usernames and passwords apply.
Now, this is not all acceptable or preferred to use them, for legitimate enterprise applications. However, there may be some legacy third-party applications do not support oAuth 2.0. In that case, you do not have an alternative.

23. Notes 5

24. Applications that use User Context
There is significant overlap between the SharePoint Add-in User + Add-in model and the O365 API Delegated model. Things to consider:
Use of O365 API’s require O365 API Delegated. (eg. Graph, Contacts, etc.)
O365 API gives access to ALL a users resources eg. All Site Collections, SharePoint Add-In model only the scope described in the manifest. Eg. Site Collection, Web, List.
Device based solutions recommended to use O365 API.
The key take aways are:;
There is significant overlap between SharePoint user+add-in, and the Azure AD Delegated model. In most cases, you can use either. And the more preferred one is the Azure AD Delegated permissions, since it is the one Microsoft is actively working and supporting.
You especially need to use the Azure AD Delegated Permissions to write Mobile applications, that will work seamlessly.
For any application that connects to SharePoint, as well as Graph, and other Office 365 service, the delegated model is the most preferred.

25. Decision Chart
This is how the decision tree will look like if you were to choose which authentication method to use based on what you want to do.

26. Questions and Answers