diff --git a/docs/embedded/development/auth.md b/docs/embedded/development/auth.md index b9804e703..e0fc816b7 100644 --- a/docs/embedded/development/auth.md +++ b/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: 01/20/2026 +ms.date: 03/20/2026 ms.localizationpriority: high --- @@ -39,58 +39,108 @@ SharePoint Embedded applications need to request the following Microsoft Graph p - [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 +#### 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. This permission requires admin consent on the consuming tenant before any user from the tenant can consent to it. +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 [container permissions](#container-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` 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 +#### 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. > [!NOTE] -> An administrator on the consuming tenant must consent to your application's request for permissions. Learn more [here](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal). +> 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). -### Exceptional access patterns +### Container type application permissions -Currently, there are two types of operations with exceptional access patterns: +SharePoint Embedded applications need to be granted container type application permissions by the owning application before they can access containers of the given container type. Container type application permissions are granted to applications via [container type registration](../getting-started/register-api-documentation.md) in a consuming tenant. -- [Operations not exposed via Microsoft Graph](#operations-not-exposed-via-microsoft-graph) -- [Operations involving searching SharePoint Embedded content](#operations-involving-searching-sharepoint-embedded-content) -- [Operations that require a user license](#operations-that-require-a-user-license) +| Permission | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------ | +| None | Has no permissions to any containers or content of this container type. | +| ReadContent | Can read the content of containers of this container type. | +| WriteContent | Can write content to containers for this container type. This can't be granted without the ReadContent permission. | +| Create | Can create containers of this container type. | +| Delete | Can delete containers of this container type. | +| Read | Can read the metadata of containers of this container type. | +| Write | Can update the metadata of containers of this container type. | +| EnumeratePermissions | Can enumerate the members of a container and their roles for containers of this container type. | +| AddPermissions | Can add members to the container for containers of this container type. | +| UpdatePermissions | Can update (change roles of) existing memberships in the container for containers of this container type. | +| DeletePermissions | Can delete other members (but not self) from the container for containers of this container type. | +| DeleteOwnPermission | Can remove own membership from the container for containers of this container type. | +| ManagePermissions | Can add, remove (including self), or update members in the container roles for containers of this container type. | +| ManageContent | Can manage the content of the container (WriteContent plus discard checkout permission in app-only mode). | +| Full | Has all permissions for containers of this container type. | + +> [!NOTE] +> The combination of Microsoft Graph permissions and container type application permissions encompasses the client authorization for applications. + +### User permissions + +Users are granted different access levels to SharePoint Embedded based on the scenario: + +- [Accessing content in containers](#accessing-content-in-containers) +- [Managing SharePoint Embedded applications installed in the consuming tenant](#managing-sharepoint-embedded-applications-installed-in-the-consuming-tenant) +- [Managing SharePoint Embedded applications created in the owning tenant](#managing-sharepoint-embedded-applications-created-in-the-owning-tenant) + +#### Accessing content in containers + +There are two ways in which users can gain access to content in containers: + +- [Container permissions](#container-permissions) +- [Access to specific items in a container](#access-to-specific-items-in-a-container) + +##### Container permissions + +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 [M365 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. > [!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. +> The calling user creating a new container via delegated calls is automatically assigned the Owner role. + +| 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. | +| 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. | -#### Operations not exposed via Microsoft Graph +##### Access to specific items in a container -There is one scenario that isn't accessible via Microsoft Graph today: +Specific items in a container can be shared with users via the [driveItem invite](/graph/api/driveitem-invite) or the [permission create](/graph/api/driveitem-post-permissions) endpoints. Sharing grants users access to the specific items, but it doesn't grant them access to the container itself or any other item in the container. For information on the access levels supported, see [permission roles](/graph/api/resources/permission#roles-property-values). -- [SharePoint Embedded agent](./declarative-agent/spe-da.md) exposed via SharePoint REST API v2 permissions. +> [!NOTE] +> For more information about sharing, see [Sharing and permissions in SharePoint Embedded](./sharing-and-perm.md). -To use the [SharePoint Embedded agent](./declarative-agent/spe-da.md) experience (in Preview stage) in your application, you need the `Container.Selected` permission on the `Office 365 SharePoint Online` resource: +#### Managing SharePoint Embedded applications installed in the consuming tenant -| Scope name | Scope ID | Type | Operation | -| :-------------------: | :----------------------------------: | :---------: | :-----------------------------------------------------------------------------------------------: | -| Container.Selected | 19766c1b-905b-43af-8756-06526ab42875 | Application | In the context of SharePoint Embedded, enables container type registration on a consuming tenant. | +[SharePoint Embedded Administrators](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) can manage all SharePoint Embedded applications installed in the **consuming** tenant. To learn more about managing installed applications in the consuming tenant, see [Manage SharePoint Embedded applications installed in the consuming tenant](../administration/consuming-tenant-admin/cta.md). > [!NOTE] -> The `Container.Selected` permission is a hidden permission and won't show up in the Microsoft Entra admin consent experience. See [Granting admin consent for hidden permissions](#granting-admin-consent-for-hidden-permissions) for more details. +> [Global Administrators](/entra/identity/role-based-access-control/permissions-reference#global-administrator) have all the permissions that SharePoint Embedded Administrators have and more, so they can also manage SharePoint Embedded applications installed in the consuming tenant. However, you should assign the least privileged role necessary to perform administrative tasks, so using the SharePoint Embedded Administrator role is recommended for managing SharePoint Embedded applications. -##### Granting admin consent for hidden permissions +#### Managing SharePoint Embedded applications created in the owning tenant -[Granting admin consent](/entra/identity-platform/v2-admin-consent) for applications requesting hidden permission MUST be done by using the [admin consent URL](/entra/identity-platform/v2-admin-consent#request-the-permissions-from-a-directory-admin). Provide the consent URL to the Microsoft Entra directory administrator and ensure they [confirm a successful response](/entra/identity-platform/v2-admin-consent#successful-response). The consent URL may look like this: +[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). -```http -https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id={client_id}&redirect_uri={redirect_uri}&scope={tenant_root_site_url}/.default -``` +### Exceptional access patterns + +Currently, there are two 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) > [!IMPORTANT] -> Do not use the App registrations pane in the Azure portal to grant admin consent for applications that request hidden permissions. The App registrations pane will fail to validate the requested hidden permissions and will remove them from the manifest. You may use the Enterprise Applications pane in the Azure portal to view the granted hidden permissions after admin consent has been granted via the admin consent URL. +> Consider the repercussions of these exceptional access patterns on how your application and other applications can access SharePoint Embedded content in your container type. #### Operations involving searching SharePoint Embedded content @@ -113,45 +163,6 @@ 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. -### Container type application permissions - -SharePoint Embedded applications need to be granted container type application permissions by the owner application before they can access containers of the given container type. Container type application permissions are granted to applications via [container type registration](../getting-started/register-api-documentation.md). - -| Permission | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------ | -| None | Has no permissions to any containers or content of this container type. | -| ReadContent | Can read the content of containers of this container type. | -| WriteContent | Can write content to containers for this container type. This can't be granted without the ReadContent permission. | -| Create | Can create containers of this container type. | -| Delete | Can delete containers of this container type. | -| Read | Can read the metadata of containers of this container type. | -| Write | Can update the metadata of containers of this container type. | -| EnumeratePermissions | Can enumerate the members of a container and their roles for containers of this container type. | -| AddPermissions | Can add members to the container for containers of this container type. | -| UpdatePermissions | Can update (change roles of) existing memberships in the container for containers of this container type. | -| DeletePermissions | Can delete other members (but not self) from the container for containers of this container type. | -| DeleteOwnPermissions | Can remove own membership from the container for containers of this container type. | -| ManagePermissions | Can add, remove (including self), or update members in the container roles for containers of this container type. | -| ManageContent | Can manage the content of the container | -| Full | Has all permissions for containers of this container type. | - -> [!NOTE] -> The combination of Microsoft Graph permissions and container type application permissions encompasses the client authorization for applications. - -### Container permissions - -Any user accessing a container must be a member of the container. 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. - -> [!IMPORTANT] -> The calling user creating a new container via delegated calls is automatically assigned the Owner role. - -| 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. | -| 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. | - ## What's next Here are some actions you can take next: @@ -159,7 +170,7 @@ 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 -1. [Grant admin consent](#granting-admin-consent-for-hidden-permissions) to your application on your _owning_ tenant +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`) @@ -170,8 +181,6 @@ Here are some actions you can take next: - 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 - - Office 365 SharePoint Online (resourceAppId: `00000003-0000-0ff1-ce00-000000000000`) - - `Container.Selected` (type: `Role`, ID: `19766c1b-905b-43af-8756-06526ab42875`) to use SharePoint Embedded Agent -1. [Grant admin consent](#granting-admin-consent-for-hidden-permissions) to your application on a _consuming_ tenant (which can be the same as the owning tenant). +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. [Create a container](/graph/api/filestoragecontainer-post) on the _consuming_ tenant