Skip to content

docs: Document container type owner capabilities in SPE auth page #10751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andrewconnell merged 3 commits into from
Apr 6, 2026
Merged

docs: Document container type owner capabilities in SPE auth page #10751

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8c33550
docs: Document container type owner capabilities in SPE auth page
Apr 1, 2026
26683c8
docs: ✏️ minor wording fixes in SPE auth
andrewconnell Apr 6, 2026
766e9d2
docs: ✨ improve SPE auth formatting & links
andrewconnell Apr 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 65 additions & 19 deletions docs/embedded/development/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: SharePoint Embedded Authentication and Authorization
description: This article describes the authentication and authorization model for SharePoint Embedded applications.
ms.date: 03/20/2026
ms.date: 04/02/2026
ms.localizationpriority: high
---

Expand Down Expand Up @@ -35,22 +35,22 @@ SharePoint Embedded operations are exposed via Microsoft Graph. SharePoint Embed

SharePoint Embedded applications need to request the following Microsoft Graph permissions in their application manifest to work with SharePoint Embedded:

- [FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainermanageall) to allow an application to create and manage container types on the owning tenant. This permission is only needed on the owning tenant where the container type is created.
- [FileStorageContainerTypeReg.Selected](/graph/permissions-reference#filestoragecontainertyperegselected) to allow an application to register the container type on consuming tenants.
- [FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected) to allow an application to access containers of the given container type on consuming tenants.
- **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** to allow an application to create and manage container types on the owning tenant. This permission is only needed on the owning tenant where the container type is created.
- **[FileStorageContainerTypeReg.Selected](/graph/permissions-reference#filestoragecontainertyperegselected)** to allow an application to register the container type on consuming tenants.
- **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** to allow an application to access containers of the given container type on consuming tenants.

#### Access on behalf of a user

SharePoint Embedded operations [on behalf of a user](/graph/auth-v2-user) require applications to receive consent for Microsoft Graph [`FileStorageContainer.Selected`](/graph/permissions-reference#filestoragecontainerselected) delegated permission.
SharePoint Embedded operations [on behalf of a user](/graph/auth-v2-user) require applications to receive consent for Microsoft Graph **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** delegated permission.

In addition to your application receiving consent for `FileStorageContainer.Selected` on a consuming tenant, the user that it's acting on behalf of is required to have [user permissions](#user-permissions). The effective permissions that the application has are the intersection of the application permissions and the user permissions when acting on behalf of a user.
In addition to your application receiving consent for **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** on a consuming tenant, the user that it's acting on behalf of is required to have [user permissions](#user-permissions). The effective permissions that the application has are the intersection of the application permissions and the user permissions when acting on behalf of a user.

> [!IMPORTANT]
> Using SharePoint Embedded on behalf of a user is the recommended approach. This type of access enhances the security of your application. It also improves the auditability of actions performed by your application.

#### Access without a user

SharePoint Embedded operations [without a user](/graph/auth-v2-service) require applications to receive consent for Microsoft Graph [`FileStorageContainer.Selected`](/graph/permissions-reference#filestoragecontainerselected) application permission. This permission requires admin consent on the consuming tenant.
SharePoint Embedded operations [without a user](/graph/auth-v2-service) require applications to receive consent for Microsoft Graph **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** application permission. This permission requires admin consent on the consuming tenant.

> [!NOTE]
> An administrator on the consuming tenant must consent to your application's request for permissions. To learn more, see [Grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal).
Expand Down Expand Up @@ -132,6 +132,30 @@ Specific items in a container can be shared with users via the [driveItem invite

[SharePoint Embedded Administrators](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) can manage all SharePoint Embedded applications created in the **owning** tenant. Additionally, any Microsoft Entra user that isn't an external identity can be assigned as an owner of a [container type](/graph/api/resources/filestoragecontainertype). Container type owners can manage that specific container type. To learn more about managing applications created in the owning tenant, see [SharePoint Embedded developer administrator](../administration/developer-admin/dev-admin.md).

#### Container type owner capabilities

Container type owners are managed through the [permissions](/graph/api/filestoragecontainertype-post-permissions) navigation property on the [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) resource. Each permission entry has a role of `owner` and identifies the user via `grantedToV2`. Owners can be managed in the following ways:

- **Automatic assignment**: The user who [creates a container type](/graph/api/filestorage-post-containertypes) is automatically assigned as an owner.
- **Add owners**: Use [`POST /containerTypes/{id}/permissions`](/graph/api/filestoragecontainertype-post-permissions) to add up to three owners per container type.
- **Remove owners**: Use [`DELETE /containerTypes/{id}/permissions/{id}`](/graph/api/filestoragecontainertype-delete-permissions) to remove an owner.
- **Read owners**: Use [`GET /containerTypes/{id}?$expand=permissions`](/graph/api/filestoragecontainertype-get) or [`GET /containerTypes/{id}/permissions`](/graph/api/filestoragecontainertype-list-permissions) to retrieve the container type owners.

Container type owners can do the following operations on the **owning tenant** when using an application with **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** in delegated mode:

- **Create, read, update, and delete** the container type they own. Non-admin owners can only manage container types where they appear in the permissions collection and the calling app matches the owning application.
- **Add and remove** other owners on the container type they own (via the permissions endpoint)
- **Create containers** of the container type they own, as long as the call is delegated (not app-only)

> [!NOTE]
> The user who creates a container type is automatically assigned as an owner. External identities (guest users) can't be assigned as container type owners and can't perform owner operations.

> [!IMPORTANT]
> Container type owners exist only in the owning tenant. When a container type is registered in a consuming tenant, the owner information is **not** propagated to that tenant. For example, if Contoso creates a container type with owners and registers it in Fabrikam, those Contoso users don't exist in Fabrikam's tenant and have no owner capabilities there.

> [!IMPORTANT]
> Container type owner capabilities are user permissions. The effective access is the intersection of the application permissions (Microsoft Graph permissions) and the user permissions (owner role). The application must have sufficient Graph permissions for the intersection to grant the desired access.

### Exceptional access patterns

Currently, there are two types of operations with exceptional access patterns:
Expand All @@ -146,7 +170,7 @@ Currently, there are two types of operations with exceptional access patterns:

This section refers only to the search scenarios in [Search Content](./content-experiences/search-content.md), and not the enumeration scenarios.

To use [Microsoft Search](/microsoftsearch/overview-microsoft-search) on SharePoint Embedded content, you must request the Delegated [`Files.Read.All`](/graph/permissions-reference#filesreadall) Microsoft Graph permission on top of `FileStorageContainer.Selected`, normally used for SharePoint Embedded access. During the Preview stage of this feature, the `Files.Read.All` application permission grants applications access to search capabilities on all SharePoint Embedded content.
To use [Microsoft Search](/microsoftsearch/overview-microsoft-search) on SharePoint Embedded content, you must request the Delegated **[Files.Read.All](/graph/permissions-reference#filesreadall)** Microsoft Graph permission on top of **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)**, normally used for SharePoint Embedded access. During the Preview stage of this feature, the **[Files.Read.All](/graph/permissions-reference#filesreadall)** application permission grants applications access to search capabilities on all SharePoint Embedded content.

> [!NOTE]
> Microsoft Search support for SharePoint Embedded content is in Preview and is subject to change. The access requirements for Microsoft Search on SharePoint Embedded content will align with the SharePoint Embedded authorization model in the future. Stay tuned.
Expand All @@ -157,7 +181,7 @@ SharePoint Embedded is designed to work without the need for end users to have a

##### List containers

The [List containers](/graph/api/filestorage-list-containers?tabs=http) operation returns a `403 Forbidden` response code if called on behalf of a user who doesn't have a OneDrive. There are plans to remove this dependency soon. This dependency doesn't apply to the List containers operation when called without a user context (app-only mode).
The [List containers](/graph/api/filestorage-list-containers?tabs=http) operation returns a **403 Forbidden** response code if called on behalf of a user who doesn't have a OneDrive. There are plans to remove this dependency soon. This dependency doesn't apply to the List containers operation when called without a user context (app-only mode).

##### Mention users in Office documents

Expand All @@ -168,19 +192,41 @@ The common [Office experience](./content-experiences/office-experience.md) inclu
Here are some actions you can take next:

1. Configure your SharePoint Embedded [application manifest](/entra/identity-platform/reference-app-manifest#requiredresourceaccess-attribute) (you can use [Microsoft Entra PowerShell](/powershell/entra-powershell/manage-apps#assign-permissions-to-an-app) or the [Azure CLI](/cli/azure/ad/app/permission#az-ad-app-permission-add)) to request the required permissions on your _owning_ tenant:
- Microsoft Graph (resourceAppId: `00000003-0000-0000-c000-000000000000`)
- Add: `FileStorageContainerType.Manage.All` (type: `Role`, ID: `8e6ec84c-5fcd-4cc7-ac8a-2296efc0ed9b`) to create container types on the _owning_ tenant
- Add the Microsoft Graph permission **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** to create container types on the _owning_ tenant:
- **resourceAppId**: `00000003-0000-0000-c000-000000000000`
- **type**: `Role`
- **ID**: `8e6ec84c-5fcd-4cc7-ac8a-2296efc0ed9b`
1. [Grant admin consent](/entra/identity-platform/v2-admin-consent) to your application on your _owning_ tenant
1. [Create a new container type](../getting-started/containertypes.md) on the _owning_ tenant.
1. Reconfigure your SharePoint Embedded [application manifest](/entra/identity-platform/reference-app-manifest#requiredresourceaccess-attribute) to request only the required permissions on consuming tenants:
- Microsoft Graph (resourceAppId: `00000003-0000-0000-c000-000000000000`)
- Remove: `FileStorageContainerType.Manage.All` (type: `Role`, ID: `8e6ec84c-5fcd-4cc7-ac8a-2296efc0ed9b`) as this is only needed to create the container type on the _owning_ tenant
> [!NOTE]
> After creating the container type on the _owning_ tenant, you should remove the `FileStorageContainerType.Manage.All` permission from your application's manifest.
> Your application DOES NOT need this on _consuming_ tenants, only on the _owning_ tenant to create the container type. Failure to remove this permission from the application's manifest will lead to your customers being concerned about the excessive permissions requested by your application.
- Add: `FileStorageContainerTypeReg.Selected` (type: `Role`, ID: `2dcc6599-bd30-442b-8f11-90f88ad441dc`) to register the container type on _consuming_ tenants
- Add: `FileStorageContainer.Selected` (type: `Scope`, ID: `085ca537-6565-41c2-aca7-db852babc212`) to access containers on _consuming_ tenants on behalf of users
- Optionally add: `FileStorageContainer.Selected` (type: `Role`, ID: `40dc41bc-0f7e-42ff-89bd-d9516947e474`) to access the container on _consuming_ tenants without a user

- Remove the Microsoft Graph permission [FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** as this is only needed to create the container type on the _owning_ tenant:
- **resourceAppId**: `00000003-0000-0000-c000-000000000000`
- **type**: `Role`
- **ID**: `8e6ec84c-5fcd-4cc7-ac8a-2296efc0ed9b`

> [!NOTE]
> After creating the container type on the _owning_ tenant, you should remove the **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** permission from your application's manifest.
> Your application DOES NOT need this on _consuming_ tenants, only on the _owning_ tenant to create the container type. Failure to remove this permission from the application's manifest will lead to your customers being concerned about the excessive permissions requested by your application.

- Add the Microsoft Graph permission **[FileStorageContainerTypeReg.Selected](/graph/permissions-reference#filestoragecontainertyperegselected)** to register the container type on _consuming_ tenants:
- **resourceAppId**: `00000003-0000-0000-c000-000000000000`
- **type**: `Role`
- **ID**: `2dcc6599-bd30-442b-8f11-90f88ad441dc`
- Add the Microsoft Graph permission **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** to access containers on _consuming_ tenants on behalf of users:
- **resourceAppId**: `00000003-0000-0000-c000-000000000000`
- **type**: `Scope`
- **ID**: `085ca537-6565-41c2-aca7-db852babc212`
- Optionally add the Microsoft Graph permission **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** to access the container on _consuming_ tenants without a user:
- **resourceAppId**: `00000003-0000-0000-c000-000000000000`
- **type**: `Role`
- **ID**: `40dc41bc-0f7e-42ff-89bd-d9516947e474`

1. [Grant admin consent](/entra/identity-platform/v2-admin-consent) to your application on a _consuming_ tenant (which can be the same as the owning tenant).
1. [Register the container type](../getting-started/register-api-documentation.md) on the _consuming_ tenant.
1. Remove **[FileStorageContainerTypeReg.Selected](/graph/permissions-reference#filestoragecontainertyperegselected)** from your application's manifest after registration is complete.

> [!NOTE]
> After registering the container type, you should remove the **[FileStorageContainerTypeReg.Selected](/graph/permissions-reference#filestoragecontainertyperegselected)** permission from your application's manifest. This permission is only needed during registration setup. Keeping it after registration unnecessarily increases your application's permission surface.

1. [Create a container](/graph/api/filestoragecontainer-post) on the _consuming_ tenant