Clarify behavior when both FSC.Manage.All and FSC.Selected are granted for admin and nonadmin

docs/embedded/development/auth.md

@@ -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: 04/02/2026
+ms.date: 04/16/2026
 ms.localizationpriority: high
 ---
 
@@ -17,12 +17,12 @@ Here are some key principles of SharePoint Embedded authentication and authoriza
 - Applications need container type application permissions to access containers of that container type.
 - Applications can only access containers that the user is a member of when using access on behalf of a user.
 - Applications can access all containers enabled by their container type application permissions when using access without a user.
-- Applications use access on behalf of users whenever possible to enhance security and accountability
+- Applications use access on behalf of users whenever possible to enhance security and accountability.
 
 ## Prerequisites
 
 - A Microsoft Entra ID application registration. See [register an application](/graph/auth-register-app-v2).
-- Your Microsoft Entra ID tenant has a Microsoft 365 subscription
+- Your Microsoft Entra ID tenant has a Microsoft 365 subscription.
 
 ## Authorization
 
@@ -35,15 +35,16 @@ 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.
+- **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** 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.
-
-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.
+SharePoint Embedded operations [on behalf of a user](/graph/auth-v2-user) support two Microsoft Graph permissions: 
+- **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** to allow an application to access containers on behalf of the signed-in user.
+    - In addition to your application receiving consent for the permission 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.
+- **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** to allow an application to utilize administration capabilities on all containers of all governable container types within the consuming tenant on behalf of an administrator user. The administration capabilities include the ability to enumerate, delete, restore, purge, and update containers, as well as manage their permissions.
 
 > [!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.
@@ -100,7 +101,7 @@ There are two ways in which users can gain access to content in containers:
 Users can be assigned container permissions in two ways:
 
 - Direct membership. A user is directly added as a member of a container with specific permissions.
-- Transitive membership. A user is a member of an [Microsoft 365 group](/microsoft-365/admin/create-groups/office-365-groups) that is itself a member of a container with specific permissions.
+- Transitive membership. A user is a member of a [Microsoft 365 group](/microsoft-365/admin/create-groups/office-365-groups) that is itself a member of a container with specific permissions.
 
 Membership to a container [grants users container permissions](/graph/api/filestoragecontainer-post-permissions). These permissions define the access level that users have on a given container. Container permissions only apply to access on behalf of a user and not to access without a user. A SharePoint Embedded application accessing containers without a user gets the full access defined in its [container type application permissions](#container-type-application-permissions) instead.
 
@@ -110,7 +111,7 @@ Membership to a container [grants users container permissions](/graph/api/filest
 | Permission  |                                                                                   Description                                                                                   |
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Reader**  | This role allows the user to read the properties and the contents of the container.                                                                                             |
-| **Writer**  | This role has all the permissions a Reader has, plus the permission to create, update, and delete content inside the container, and to update applicable  container properties. |
+| **Writer**  | This role has all the permissions a Reader has, plus the permission to create, update, and delete content inside the container, and to update applicable container properties.  |
 | **Manager** | This role has all the permissions a Writer has, plus the permission to manage membership of the container.                                                                      |
 | **Owner**   | This role has all the permissions a Manager has, plus the permission to delete containers and restore deleted containers.                                                       |
 
@@ -141,11 +142,11 @@ Container type owners are managed through the [permissions](/graph/api/filestora
 - **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:
+Container type owners can do the following operations on the **owning tenant** when using an application with **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** 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)
+- **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.
@@ -158,10 +159,11 @@ Container type owners can do the following operations on the **owning tenant** w
 
 ### Exceptional access patterns
 
-Currently, there are two types of operations with exceptional access patterns:
+Currently, there are three types of operations with exceptional access patterns:
 
 - [Operations involving searching SharePoint Embedded content](#operations-involving-searching-sharepoint-embedded-content)
 - [Operations that require a user license](#operations-that-require-a-user-license)
+- [Operations that involve administrative actions on containers](#operations-that-involve-administrative-actions-on-containers)
 
 > [!IMPORTANT]
 > Consider the repercussions of these exceptional access patterns on how your application and other applications can access SharePoint Embedded content in your container type.
@@ -187,26 +189,33 @@ The [List containers](/graph/api/filestorage-list-containers?tabs=http) operatio
 
 The common [Office experience](./content-experiences/office-experience.md) includes reviewing documents and adding comments to those documents. For users to show up in the @mentions people picker, they need to have a Microsoft 365 license assigned to them.
 
+#### Operations that involve administrative actions on containers
+
+The **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** permission requires the signed-in user to be a SharePoint Embedded Administrator or Global Administrator. If the user is not an administrator, **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** does not grant the application any permissions:
+
+- If only **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** is granted, the application will get an access denied error when trying to access the container on behalf of the non-admin user.
+- If both **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** and **[FileStorageContainer.Selected](/graph/permissions-reference#filestoragecontainerselected)** are granted, **[FileStorageContainer.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** will be ignored and the application can access containers on behalf of the non-admin user but won't be able to perform any administrative actions on the container.
+
 ## What's next
 
 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:
-    - Add the Microsoft Graph permission **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainermanageall)** to create container types on the _owning_ tenant:
+    - Add the Microsoft Graph permission **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** 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:
 
-    - 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:
+    - Remove the Microsoft Graph permission **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** 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.
+          > After creating the container type on the _owning_ tenant, you should remove the **[FileStorageContainerType.Manage.All](/graph/permissions-reference#filestoragecontainertypemanageall)** 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: