Creating apps for SharePoint that use low-trust authorization
Learn about the low-trust authorization system for apps for SharePoint.
Last modified: September 13, 2014
Applies to: SharePoint Foundation 2013 | SharePoint Online
Remote components in an app for SharePoint (or external application) can gain authorization to SharePoint resources by passing an access token to SharePoint with each HTTP request. The remote components obtain the access token from a Microsoft Azure Access Control Service (ACS) account that is associated with the customer's Microsoft Office 365 tenancy. Azure ACS acts as the authorization server in an OAuth 2.0 transaction, called a flow, with SharePoint as the resource server and the remote components as the client. For related protocol specifications, see Web Authorization Protocol (oauth).
Provider-hosted apps for SharePoint that use low-trust authorization system can be sold in the Office Store and installed on either Microsoft SharePoint Online or an on-premise SharePoint farm that has been configured to use the customer's Office 365 tenancy to establish trust with Azure ACS. The customer must have an Office 365 tenancy to install apps for SharePoint that use the low-trust system. However, it is not necessary for the customer to use the tenancy for any other purpose. For instructions about linking an on-premise farm to a Office 365 tenancy, see How to: Use an Office 365 SharePoint site to authorize provider-hosted apps on an on-premises SharePoint site.
To use the low-trust system, the app for SharePoint must first be registered with Azure ACS and with the App Management Service of the SharePoint farm or SharePoint Online tenancy. For apps that are sold through the Office Store, registration to ACS is performed in the Seller Dashboard and registration with the service is performed when the app is installed. For apps that are distributed in the organization app catalog, registration to both ACS and the service is performed on the \_Layouts\15\AppRegNew.aspx page of any SharePoint tenancy or farm where the app is to be installed. External, non- SharePoint, applications that access SharePoint, also need to be registered. This category includes apps for Office, Windows Store apps, web applications, and device apps such as smartphone apps.
Registration requires that the application have an Internet domain. Any existing domain can be used for this purpose, but you can't be 100% certain that any domain you don't own will always exist, so a web application would need to be part of a native device application even if the web application component played no other role than to enable registration. For an advanced code sample that is designed in this way, see Provision sites in batches with the app model.
For more information on registration, see Guidelines for registering apps for SharePoint 2013.
App secret expiration
The app secret must be replaced every 12 months. For details, see How to: Replace an expiring client secret in an app for SharePoint.
An app for SharePoint can be designed to use either of two authorization policies:
User + app Policy: Apps that use this policy can only perform actions that both the app and the user have permission to do. This is the default policy that is used unless the developer takes specific steps to use the other.
App-only Policy: Apps that use this policy can perform any action that it has permission to do, even if the user does not have permission for the action. The developer must request that this policy be used in the app manifest of the app. The request must be approved by the user who installs the app. This policy is allowed for only provider-hosted apps for SharePoint.
For more information about authorization policies, see App authorization policy types in SharePoint 2013.
Each time a cloud-hosted app for SharePoint or external application that is accessing SharePoint is run, a flow -- a series of interactions between the app, SharePoint 2013, ACS, and sometimes the end user -- occurs. The end result of the flow is that SharePoint receives an access token included with each create, update, delete (CRUD) request that the application makes to SharePoint.
There are two major OAuth flows used by SharePoint. One is for cloud-hosted apps for SharePoint. The other, called "on the fly," is for applications on other platforms that access SharePoint data.
Context Token flow: The remote component of the app for SharePoint uses the SharePoint client object model (CSOM) or REST endpoints to make calls to SharePoint. SharePoint requests a context token from ACS that it can send to the remote server. The remote server uses the context token to request an access token from the ACS. The remote server then uses the access token to talk back to SharePoint. For details about this flow, see Context Token OAuth flow for apps in SharePoint 2013.
Authenticaton Code flow: An app for SharePoint is granted the permissions it needs to SharePoint resources when it is installed. But applications that are not installed on SharePoint must ask for permissions "on the fly," that is, each time they run. There is no SharePoint context token in this flow. Instead, when the app runs and attempts to access SharePoint, SharePoint prompts the user to grant the permissions to the application that it is requesting. When the user grants the permissions, SharePoint obtains an authorization code from ACS which it passes to the application. The application uses the code to obtain an access token from ACS which it can then use to talk to SharePoint. For details about this flow, see Authentication Code OAuth flow for apps in SharePoint 2013.