Create SharePoint Embedded applications

  • 6 minutes

Developers can create applications that utilize the powerful file and document management capabilities in SharePoint through SharePoint Embedded. These types of applications have two distinct components.

  • One component is responsible for performing CRUD operations against SharePoint Embedded using Microsoft Graph APIs.
  • The other component implements the interface for users to consume and store the documents stored in SharePoint Embedded.

Introducing SharePoint Embedded

SharePoint Embedded provides a faster way for developers to create file and document focused applications. SharePoint Embedded is powered by SharePoint. Developers can integrate the same powerful file and document capabilities that SharePoint has to offer in their own custom applications.

Another way to look at SharePoint Embedded is your custom application uses SharePoint for all document storage and collaboration features. This effectively uses SharePoint Embedded as a “headless-API” to SharePoint's document storage system.

App documents stay in their Microsoft 365 tenant

When a consumer installs/registers a SharePoint Embedded application in their Microsoft 365 tenant, SharePoint Embedded creates another SharePoint partition. This storage partition doesn't have a user interface but instead, the documents in the partition are only accessible via APIs. This means that all documents will be accessible to the ISV or developer's application, but the documents will only reside in the consumer's Microsoft 365 tenant.

Consumer Microsoft 365 settings apply to app documents

All documents stored in the SharePoint partition created by the SharePoint Embedded app are in the consumer's Microsoft 365 tenant and therefore are subject to the consumer's Microsoft 365 tenant settings.

Understanding different types app permissions and the On-Behalf-Of flow

When creating applications for that access REST APIs like Microsoft Graph and SharePoint Online, different tasks require different types of access. To address this, the OAuth v2.0 is an open standard for authorization used for API access, including Microsoft Graph and SharePoint Online. It provides applications with delegated access to protected resources on behalf of a user. This includes two types of permissions: App+User (also known as Delegated) and App-Only (or Application).

  • App+User (or Delegated) Permissions: This model is about a two-party permission model. The application is performing tasks and calling APIs on behalf of a signed-in user. The application gets delegated permissions from the user who signs into it, inheriting the privileges that the user has, including any restrictions like not being able to access certain data or take certain actions. These reflect the tasks the user has permitted the app to carry out on their behalf during their session.

    For example, an app might be given permission to send an email on behalf of a user, but if the user doesn't have permission to send an email, then the app won't be able to send it either.

    This type of permission is often used when you want your app to operate as the signed-in user would, to application scenarios where interaction is on behalf of a user and the permissions should vary by the user who grants consent.

  • App-Only (or Application) Permissions: App-only permissions, conversely, are used when an app needs to access resources independently of a user. The application gets the permissions directly granted to itself, irrespective of the user permissions. It allows the application to access the API service with its own identity and privileges. This is ideal for background services or daemons that run independent from a user session.

For instance, if you have an application that needs to access all the files in a document library, even those which aren't shared with any user, app-only permissions would be the right choice.

Application permissions can only be consented by an administrator because they often grant higher privileges.

In addition to these two options, a third OAuth 2.0 flow, On-Behalf-Of (also known as the OBO flow) can be used when an application needs to perform a task on behalf of the user. Here's how the entire OBO flow works:

  1. A client application authenticates to the authorization server (like Microsoft Entra ID) and requests an access token for an API (like our project's API server).
  2. The user signs in and allows the application to act on their behalf.
  3. The client application receives an access token and refresh token representing the user's session.
  4. When the client application needs to call another service, such as SharePoint Online, on behalf of the user, it sends the access token it obtained earlier in the Authorization HTTP header.
  5. Our server-side API validates the access token and processes the request. If it needs to call another service (like SharePoint Online) on behalf of the user, it fetches a token from Microsoft Entra ID by presenting this already obtained token.
  6. Microsoft Entra ID issues a 'new' access token for SharePoint Online that our project's API server can now use to call SharePoint Online.

In a practical scenario dealing with Microsoft Graph or SharePoint Online, when a user wants an app to access their calendar, it's not ideal to have the application sign in for each individual operation. Instead, with the OBO flow, the user only needs to authenticate once and the application will perform all authorized operations on their behalf.

Thus, the OBO flow simplifies user experience and enhances the security of the system by ensuring that permissions are validated each time a chain of calls is made.

Summary

In this section, you completed the initial steps to create a web application that will perform CRUD operations on a SharePoint Embedded Container.