From c4464c5682b1caee8a332fcb521ba12190c56cda Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Fri, 5 Jun 2026 16:13:03 -0700 Subject: [PATCH 1/3] add permission model and add sharing article --- .openpublishing.redirection.json | 7 +- .../consuming-tenant-admin/ctaUX.md | 2 +- docs/embedded/development/auth.md | 2 +- docs/embedded/development/permission-model.md | 133 +++++++++ docs/embedded/development/sharing-and-perm.md | 55 ---- docs/embedded/development/sharing.md | 279 ++++++++++++++++++ docs/toc.yml | 6 +- 7 files changed, 424 insertions(+), 60 deletions(-) create mode 100644 docs/embedded/development/permission-model.md delete mode 100644 docs/embedded/development/sharing-and-perm.md create mode 100644 docs/embedded/development/sharing.md diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 8a82f0f726..0589245a4c 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -227,7 +227,12 @@ }, { "source_path": "docs/embedded/concepts/app-concepts/sharing-and-perm.md", - "redirect_url": "/sharepoint/dev/embedded/development/sharing-and-perm", + "redirect_url": "/sharepoint/dev/embedded/development/sharing", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/development/sharing-and-perm.md", + "redirect_url": "/sharepoint/dev/embedded/development/sharing", "redirect_document_id": false }, { diff --git a/docs/embedded/administration/consuming-tenant-admin/ctaUX.md b/docs/embedded/administration/consuming-tenant-admin/ctaUX.md index 653a58708f..03c80055b9 100644 --- a/docs/embedded/administration/consuming-tenant-admin/ctaUX.md +++ b/docs/embedded/administration/consuming-tenant-admin/ctaUX.md @@ -64,7 +64,7 @@ The detailed container view provides a deeper dive into container-specific metad 1. **Membership:** This panel shows the user permissions for different users associated with the container. The admin can manage the membership on a container through this panel. > [!IMPORTANT] -> The SharePoint Embedded platform supports four distinct [roles](../../development/sharing-and-perm.md): Owner, Manager, Writer, and Reader. The SharePoint Embedded application on your tenant may not use all four roles and might refer to these roles using different names. +> The SharePoint Embedded platform supports four distinct [roles](../../development/permission-model.md): Owner, Manager, Writer, and Reader. The SharePoint Embedded application on your tenant may not use all four roles and might refer to these roles using different names. ![SharePoint Embedded Membership Roles](../../images/ctaux5.png) diff --git a/docs/embedded/development/auth.md b/docs/embedded/development/auth.md index 754ddda9ad..78533ea1c0 100644 --- a/docs/embedded/development/auth.md +++ b/docs/embedded/development/auth.md @@ -123,7 +123,7 @@ Membership to a container [grants users container permissions](/graph/api/filest 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). > [!NOTE] -> For more information about sharing, see [Sharing and permissions in SharePoint Embedded](./sharing-and-perm.md). +> For more information about sharing, see [Share content in SharePoint Embedded](./sharing.md). #### Managing SharePoint Embedded applications installed in the consuming tenant diff --git a/docs/embedded/development/permission-model.md b/docs/embedded/development/permission-model.md new file mode 100644 index 0000000000..08a3857648 --- /dev/null +++ b/docs/embedded/development/permission-model.md @@ -0,0 +1,133 @@ +--- +title: SharePoint Embedded permission model +description: Learn how to grant access to containers, folders, and files in SharePoint Embedded (SPE), and how to break inheritance when an item needs its own permissions. +author: cindylay +ms.author: cindylay +ms.service: sharepoint-embedded +ms.topic: concept-article +ms.date: 06/04/2026 +ms.localizationpriority: high +--- + +# SharePoint Embedded permission model + +In SharePoint Embedded (SPE), you grant access to a container, a folder, or a file. By default, permissions flow down: a folder picks up its container's access, and a file picks up its folder's access. The level you choose sets the reach of the grant: + +- Grant on the container, and the user gets that access on every folder and file in it. +- Grant on a folder, and the user gets that access on that folder and everything under it. +- Grant on a file, and the user gets that access on the file alone. + +A grant is additive. It adds to whatever access the user already has from grants higher up the tree. When the default flow doesn't fit a particular folder or file, you can break inheritance on that item so its permissions are independent of the folder it sits in. + +In this article, you learn how to: + +- Grant access to a container with one of four built-in roles. +- Grant access to a folder and everything in it. +- Grant access to a single file. +- Break inheritance to give a folder or file independent permissions. +- Predict what happens to permissions when you copy or move an item. + +## Granting access to a container and everything in it + +To give a user or group access to everything in a container, assign them one of four built-in container roles: + +| Role | What the user can do | +|------|---------------------| +| **Reader** | Read container content. | +| **Writer** | Reader access, plus create and modify content. | +| **Manager** | Writer access, plus manage container membership. | +| **Owner** | Manager access, plus delete and restore the container itself. | + +A container role grants that role's access across the container's content by default. As folders and files are added, they pick up the role automatically through inheritance. + +For the full role definitions, see [Authentication and authorization with SharePoint Embedded](./auth.md). + +## Granting access to a folder and everything in it + +To give a user or group access to a single folder and everything under it, call a Microsoft Graph permission API on the folder. The API you use depends on who you're granting to. + +### For a user or guest + +Call [`driveItem: invite`](/graph/api/driveitem-invite) on the folder. + +SPE rules: + +- Set `sendInvitation` to `false`. SPE doesn't deliver invitation emails. +- New guest users require delegated permissions. Inviting an existing guest (already in the consuming tenant's directory) works with either delegated or application permissions. + +### For a SharePoint group + +Call [`driveItem: createPermission`](/graph/api/driveitem-post-permissions) on the folder. + +SPE rules: + +- Use app-only auth. SPE only supports `createPermission` with app-only. +- SPE only accepts `sharePointGroup` permissions on this call. Other principal types are rejected. + +### What the new permission does + +The new permission applies to the folder. Subfolders and files inside the folder pick up the permission too, as long as they still inherit. A child folder or file with broken inheritance doesn't pick up the new permission. + +The new permission adds to the folder's existing permissions. It doesn't replace them, and it doesn't break the folder's inheritance from the container. + +To see the permissions on an item, use [List permissions](/graph/api/driveitem-list-permissions). To remove a permission, use [Delete permission](/graph/api/permission-delete). You can only delete a permission on the item where it was granted. You can't delete an inherited permission from a child item. + +## Granting access to a single file + +To give a user or group access to one file, call the same APIs on the file: + +- [`driveItem: invite`](/graph/api/driveitem-invite) for a user or guest. +- [`driveItem: createPermission`](/graph/api/driveitem-post-permissions) for a SharePoint group. + +The same SPE rules apply (see [Granting access to a folder and everything in it](#granting-access-to-a-folder-and-everything-in-it)). The new permission applies to the file alone, on top of whatever access the file already inherits from its parent folder and container. + +## Breaking inheritance + +> [!WARNING] +> Breaking inheritance is hard to undo. Avoid it unless you specifically need a folder or file to have permissions that don't follow its parent. For most scenarios, a regular grant on the item is enough, because the grant adds to what the user already has. + +To break inheritance on a folder or file, call [`driveItem: invite`](/graph/api/driveitem-invite) on the item with `retainInheritedPermissions` set to `false`. The parameter defaults to `true`, which is why regular grants don't break inheritance. + +After the break: + +- Container members keep access. Container-role assignments (Owner, Manager, Writer, Reader) always apply, even on items with broken inheritance. +- SPE drops the item-level permissions the item was inheriting from its parent folder and keeps only the ones you specify in the call. +- The item stops picking up item-level changes from its parent folder. Later grants on the parent folder don't reach the item. +- Anyone who reached the item only through an item-level grant on a parent folder loses access on the item. Add them back explicitly if they still need it. +- Subfolders and files under the item still inherit, but they now inherit from the item's independent permissions instead of the parent chain. + +You can break inheritance on a folder or a file. There's no API to break inheritance at the container itself. + +## Copy and move behavior + +What happens to permissions during a copy or move depends on where the item ends up. + +### Move within the same container + +When you move an item within its current container using [`driveItem: move`](/graph/api/driveitem-move): + +- Permissions set directly on the item are preserved at the destination. +- If the item still inherits, it picks up the destination parent folder's permissions. +- If the item has broken inheritance, it keeps its independent permissions and doesn't start inheriting from the new parent folder. +- Container-role assignments still apply, because the item is still in the same container. + +### Move across containers + +When you move an item to a different container using [`driveItem: move`](/graph/api/driveitem-move), only the file or folder transfers. None of the source item's permissions come with it. At the destination, the item starts fresh: no permissions of its own, picking up access only from the destination container and parent folder. + +### Copy + +Copying an item, in the same container or across containers, produces a new item at the destination. The new item starts with no permissions of its own and picks up access only from its destination container and parent folder. + +To give the new or moved item any direct access at the destination, add permissions explicitly with [`driveItem: invite`](/graph/api/driveitem-invite) or [`driveItem: createPermission`](/graph/api/driveitem-post-permissions). + + +## Related content + +- [Share content in SharePoint Embedded](./sharing.md) +- [Authentication and authorization with SharePoint Embedded](./auth.md) +- [`driveItem: invite`](/graph/api/driveitem-invite) +- [`driveItem: createPermission`](/graph/api/driveitem-post-permissions) +- [`driveItem: move`](/graph/api/driveitem-move) +- [List permissions](/graph/api/driveitem-list-permissions) +- [Delete permission](/graph/api/permission-delete) diff --git a/docs/embedded/development/sharing-and-perm.md b/docs/embedded/development/sharing-and-perm.md deleted file mode 100644 index 4c63f48430..0000000000 --- a/docs/embedded/development/sharing-and-perm.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Sharing and Permissions -description: Outlines Permission Model for SharePoint Embedded -ms.date: 03/03/2025 -ms.localizationpriority: high ---- - -# Sharing and permissions in SharePoint Embedded - -## Additive permissions - -In SharePoint Embedded, content always inherits permissions from its parent hierarchy. While you can't alter this inherited permission structure, you can extend access within a container by applying "additive permissions" to specific files and folders. For instance, if _UserA_ belongs to the Reader role, you can grant the user edit permission to a particular document in that container using Microsoft Graph: - -| Scenario | Microsoft Graph API(s) | Notes | -| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Grant an additive permission | [POST /drives/{drive-id}/items/{item-id}/invite](/graph/api/driveitem-invite) | The sendInvitation property must always be false. You can't grant additive permissions to the root folder in a container as this is essentially the same as adding a User to a role. You can't use AppOnly permissions. | -| Retrieve permissions | [GET /drives/{drive-id}/items/{item-id}/permissions](/graph/api/permission-get) & [GET /drives/{drive-id}/items/{item-id}/permissions/{perm-id}](/graph/api/permission-get), | | -| Delete additive permissions | [DELETE /drives/{drive-id}/items/{item-id}/permissions/{perm-id}](/graph/api/permission-delete) | You can only delete the additive permission on the drive item where it was originally added. | - -## Role-based sharing setting - -SharePoint Embedded offers a role-based sharing model that allows developers to configure file-sharing permissions based on container permission roles, offering a choice between restrictive and open sharing models. By default, the sharing setting is configured to the open model, permitting unrestricted content sharing by all users. This sharing setting is part of [container type configuration](../getting-started/containertypes.md#configuring-container-types). This configuration can only be set by the application owner's developers. To learn more about container permission roles, refer to [Authentication and Authorization with SharePoint Embedded](auth.md#container-permissions). - -### Restrictive sharing model - -Only container members who are either the Owner or Manager roles are permitted to add new permissions to files. - -### Open sharing model - -Any container members and guests with edit permissions can add new permissions to this file. - -This can be configured using the PowerShell cmdlet [Set-SPOcontainerTypeConfiguration](../administration/developer-admin/dev-admin.md#container-type-configuration-properties) as per this example: - -```powershell -Set-SPOcontainerTypeConfiguration - -containerTypeID - -sharingRestricted $false -``` - -## Sharing configuration setting - -By default, SharePoint Embedded application sharing configuration is the same as the consuming tenant-sharing configuration. For example, if the consuming tenant is configured to disable sharing for guests, then the SharePoint Embedded application is unable to add guests to container roles or grant them additive permissions. - -### Application external sharing override - -For SharePoint Embedded applications, sharing configurations can be adjusted at the application level. Consuming tenant admin can configure permissions that are different than tenant-level sharing settings. For example, if a tenant's sharing setting prohibits sharing with guests, SharePoint Embedded applications can be configured to allow guest sharing. So, all containers within that SharePoint Embedded application would have the ability to include guests or extend another permission, while other SharePoint Embedded applications and SharePoint maintain restricted sharing permissions. - -This setting can only be set by consuming tenant SharePoint Embedded admin, and can be configured using the latest PowerShell cmdlet [Set-SPOApplication](../administration/consuming-tenant-admin/ctapowershell.md#set-sharing-capability-of-applications) as shown in this example: - -```powershell -Set-SPOApplication - -OwningApplicationID - -OverrideTenantSharingCapability $true - -SharingCapability -``` diff --git a/docs/embedded/development/sharing.md b/docs/embedded/development/sharing.md new file mode 100644 index 0000000000..c592eaee89 --- /dev/null +++ b/docs/embedded/development/sharing.md @@ -0,0 +1,279 @@ +--- +title: Share content in SharePoint Embedded +description: How sharing works in SharePoint Embedded. The sharing settings, the sharing endpoints, and how each one interacts with the permission model. +ms.date: 06/04/2026 +ms.topic: concept-article +ms.service: sharepoint-embedded +author: cindylay +ms.author: cindylay +ms.localizationpriority: high +--- + +# Share content in SharePoint Embedded + +Sharing in SharePoint Embedded (SPE) is how you grant access to a file or folder beyond the people who already hold a container role. A sharing call creates a permission on the item. After that, the permission flows through the hierarchy the same way every other permission does, as described in [SharePoint Embedded permission model](./permission-model.md). + +This article covers two layers: + +- **Sharing settings.** Policy controls that gate what sharing operations are even allowed. The container-type developer sets a default; a consuming-tenant admin can override. +- **Sharing operations.** The Microsoft Graph endpoints your app calls to actually share an item: `invite`, `createPermission`, and `createLink`. + +## Before you share + +Three prerequisites for every sharing call: + +- **Container role of the caller.** A user's container role sets the upper bound on what they can share. Owners and Managers can share anything in the container; Writers can share items they can already access; Readers can't share. For role definitions, see [Authentication and authorization with SharePoint Embedded](./auth.md). +- **Sharing settings.** The container type's `isSharingRestricted` and `sharingCapability` settings can further narrow who can share and with whom (covered below). +- **Microsoft Graph permissions.** Every sharing call needs the `FileStorageContainer.Selected` scope, plus the standard `Files` or `Sites` permission for the endpoint you're calling. Required scopes are listed inline in each section under [Sharing operations](#sharing-operations). + +A container role is necessary but not sufficient. If any of the three prerequisites isn't met, the call fails. + +## Sharing settings + +SPE has two settings that gate sharing at the policy level: + +| Setting | Layer | What it controls | +|---|---|---| +| `isSharingRestricted` | Container type | Whether only Owners and Managers can share files in containers of this type. | +| `sharingCapability` | Container type, with per-application override | Whether sharing with users outside the consuming tenant is allowed, and which kind of external sharing. | + +You, as the owning-application developer, set both on the container type at registration. A consuming-tenant admin can override `sharingCapability` per application with a PowerShell cmdlet. + +When you update a container type's settings, the change reaches each container type registration (one per consuming tenant) within 48 hours. Registrations that a tenant admin has overridden aren't touched by the update. For details, see [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update). + +### Restricted sharing + +`isSharingRestricted` controls who can share files in containers of a given type. The setting lives on the [fileStorageContainerTypeSettings](/graph/api/resources/filestoragecontainertypesettings) resource. + +| State | `isSharingRestricted` | Who can share files | +|---|---|---| +| Unrestricted sharing (default) | `false` | Any container member whose role allows sharing. | +| Restricted sharing | `true` | Only the container's Owners and Managers. | + +Restricted sharing doesn't change who can read or write a file; it only narrows who can grant new permissions on it. + +To change the setting for a container type, call [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update): + +```http +PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId} +Content-Type: application/json + +{ + "settings": { + "isSharingRestricted": true + }, + "etag": "" +} +``` + +This call needs the `FileStorageContainerType.Manage.All` delegated permission. The signed-in user must be a SharePoint Embedded Administrator or Global Administrator in the owning tenant. + +### External sharing + +`sharingCapability` controls whether containers can be shared with users outside the tenant. The setting lives on [fileStorageContainerTypeSettings](/graph/api/resources/filestoragecontainertypesettings) and accepts these values: + +| Value | What it allows | +|---|---| +| `disabled` | No external sharing. Only people in the consuming tenant can be granted access. | +| `existingExternalUserSharingOnly` | Sharing only with guests already in the consuming tenant's directory (for example, guests previously added through earlier shares or Microsoft Entra B2B). New guests can't be invited, and `createLink` doesn't issue anonymous links. | +| `externalUserSharingOnly` | New and existing guests can be invited by email or object ID; recipients must sign in to access the item. `createLink` doesn't issue anonymous links. | +| `externalUserAndGuestSharing` | New and existing guests can be invited as above, **and** `createLink` can issue anonymous "Anyone with the link" URLs (`scope: anonymous`). | + +The effective capability for an application in a consuming tenant works like this: + +- By default, the application follows the consuming tenant's SharePoint Online sharing capability. +- When a SharePoint Embedded administrator in the consuming tenant runs [Set-SPOApplication](/powershell/module/sharepoint-online/set-spoapplication) with `-OverrideTenantSharingCapability $true`, the application uses the value passed to `-SharingCapability` instead, independent of the tenant-level setting. + +```powershell +Set-SPOApplication ` + -OwningApplicationId ` + -OverrideTenantSharingCapability $true ` + -SharingCapability +``` + +To share with users outside the consuming tenant at all, [Microsoft Entra B2B](/sharepoint/sharepoint-azureb2b-integration) must be enabled in that tenant. + +## Sharing operations + +This article covers the main Microsoft Graph sharing endpoints for SPE content. Each one solves a different scenario: + +| Endpoint | Use it to | +|---|---| +| [`invite`](/graph/api/driveitem-invite) | Add a specific user or group to an item by email or object ID, optionally with a notification. | +| [`createPermission`](/graph/api/driveitem-post-permissions) | Grant a SharePoint group access to an item from an application-only flow. | +| [`createLink`](/graph/api/driveitem-createlink) | Generate a sharing link whose audience is controlled by the link `scope`. | + +All three create a [permission](/graph/api/resources/permission) resource on the target item. Once that permission exists, it behaves like any other permission described in the [permission model](./permission-model.md). + +### Add a user or group with `invite` + +Use [driveItem: invite](/graph/api/driveitem-invite) when you want to grant access to a known user or group. + +SPE-specific requirements: + +- Set `sendInvitation` to `false`. SPE doesn't deliver invitation emails. +- New guest users require delegated permissions. Inviting an existing guest (already in the consuming tenant's directory) works with either delegated or application permissions. +- **Permissions:** `Files.ReadWrite` (delegated) or `Files.ReadWrite.All` (application), plus `FileStorageContainer.Selected`. See the [endpoint reference](/graph/api/driveitem-invite#permissions) for higher-privileged alternatives. + +```http +POST https://graph.microsoft.com/v1.0/drives/{driveId}/items/{itemId}/invite +Content-Type: application/json + +{ + "recipients": [ + { "email": "user@contoso.com" } + ], + "roles": ["read"], + "requireSignIn": true, + "sendInvitation": false +} +``` + +By default, `invite` is additive: `retainInheritedPermissions` defaults to `true`, so the call grants the new permission without removing what the item already inherits. Setting `retainInheritedPermissions` to `false` on the first share of an item breaks inheritance. See [Inheritance behavior of sharing calls](#inheritance-behavior-of-sharing-calls) below. + +To grant access to everyone in a container, assign a container role instead of inviting on the container's root item. + +### Grant a SharePoint group with `createPermission` + +Use [driveItem: createPermission](/graph/api/driveitem-post-permissions) when you need an application-only flow that grants access to a SharePoint group. + +SPE-specific rules from the Graph reference: + +- Application permissions only. Delegated calls aren't supported on SPE items for this endpoint. +- The `grantedToV2` value must be a `sharePointGroup`. No other user or group types are supported on this endpoint in SPE. +- The call isn't allowed on a container's root item. +- **Permissions:** `Files.ReadWrite.All` (application), plus `FileStorageContainer.Selected`. See the [endpoint reference](/graph/api/driveitem-post-permissions#permissions) for higher-privileged alternatives. + +```http +POST https://graph.microsoft.com/v1.0/drives/{driveId}/items/{itemId}/permissions +Content-Type: application/json + +{ + "roles": ["read"], + "grantedToV2": { + "sharePointGroup": { + "id": "" + } + } +} +``` + +#### Getting a SharePoint group ID + +A SharePoint group in SPE exists within the scope of a single container. To obtain the `id` you pass in `grantedToV2.sharePointGroup.id`: + +- **Create a new group** in the container with [Create sharePointGroup](/graph/api/filestoragecontainer-post-sharepointgroups). A container can hold up to 10,000 SharePoint groups. The response includes the `id` to pass to `createPermission`. +- **List existing groups** in the container with [List sharePointGroups](/graph/api/filestoragecontainer-list-sharepointgroups) to look up the `id` of a group you've already created. + +Always use the `id` field, not `principalId`. `principalId` is only unique within a single site, while `id` is globally unique. Both group endpoints require application permissions and the `FileStorageContainer.Selected` scope. + +### Share with a link using `createLink` + +Use [driveItem: createLink](/graph/api/driveitem-createlink) when you want a URL recipients can use to access the item, instead of granting access to specific users or groups up front. + +The `type` parameter controls what the link grants: + +| `type` | Effect | +|---|---| +| `view` | Read-only access via the link. | +| `edit` | Read-write access via the link. | + +The `embed` type doesn't apply to SPE; it's OneDrive personal only. + +The `scope` parameter controls who can use the link: + +| `scope` | Who the link works for | +|---|---| +| `anonymous` | Anyone with the link, no sign-in required. Subject to tenant and application sharing policy. | +| `organization` | Anyone signed into the consuming tenant. | +| `users` | A specific set of users listed in the request. | + +```http +POST https://graph.microsoft.com/v1.0/drives/{driveId}/items/{itemId}/createLink +Content-Type: application/json + +{ + "type": "view", + "scope": "organization" +} +``` + +Like `invite`, `createLink` accepts `retainInheritedPermissions`; setting it to `false` on the first share breaks inheritance. See the next section. + +**Permissions:** `Files.ReadWrite` (delegated) or `Files.ReadWrite.All` (application), plus `FileStorageContainer.Selected`. See the [endpoint reference](/graph/api/driveitem-createlink#permissions) for higher-privileged alternatives. + +### Inheritance behavior of sharing calls + +Both `invite` and `createLink` accept a `retainInheritedPermissions` parameter. The default is `true`. + +- `true` (default). The new permission is added; everything the item already inherited stays in place. +- `false`. On the first share of an item, the item's item-level inherited permissions are removed and the item starts holding only the permissions you specify. Container-role assignments still apply. This breaks inheritance at this item, the same way the [permission model article describes](./permission-model.md#breaking-inheritance). Use `false` with caution; broken inheritance is hard to undo. + +`createPermission` doesn't expose `retainInheritedPermissions`; calls to it are always additive. + +> [!WARNING] +> Setting `retainInheritedPermissions` to `false` is the only way a sharing call breaks inheritance. Calls without it are purely additive; they don't change anything an item already inherits. + +## Manage existing shares + +Once a sharing call creates a permission on an item, you can list, update, or remove it like any other permission. + +### List the permissions on an item + +```http +GET https://graph.microsoft.com/v1.0/drives/{driveId}/items/{itemId}/permissions +``` + +The response includes permissions granted directly on the item plus those it inherits. Inherited permissions are marked with an `inheritedFrom` property pointing at the ancestor that owns them. Permissions created by `createLink` show up with a `link` property describing the link's type and scope. + +**Permissions:** `Files.Read` (delegated) or `Files.Read.All` (application), plus `FileStorageContainer.Selected`. See the [endpoint reference](/graph/api/driveitem-list-permissions#permissions) for higher-privileged alternatives. + +### Remove a share + +Call [delete permission](/graph/api/permission-delete) to revoke a permission you previously granted: + +```http +DELETE https://graph.microsoft.com/v1.0/drives/{driveId}/items/{itemId}/permissions/{permissionId} +``` + +You can only delete permissions that were granted directly on the target item. To remove an inherited permission, delete it on the ancestor where it was granted, or break inheritance on the child first. See [Breaking inheritance](./permission-model.md#breaking-inheritance). + +Container-level permissions—the four container roles—can't be removed from individual `driveItem` objects through this API. Anyone holding a container role has access to every item in the container. To revoke that access, change the user's role on the container itself rather than calling `delete permission` on an item. + +**Permissions:** `Files.ReadWrite` (delegated) or `Files.ReadWrite.All` (application), plus `FileStorageContainer.Selected`. See the [endpoint reference](/graph/api/permission-delete#permissions) for higher-privileged alternatives. + +## How sharing interacts with the permission model + +Every successful sharing call creates a permission on the target item. From that point on, the permission follows the same rules as any other: + +- It applies to the item it was created on. +- It flows down to children of that item, unless a child has broken inheritance. +- It can be removed with [delete permission](/graph/api/permission-delete) on the item where it was granted. +- If `retainInheritedPermissions` was `false` on the sharing call, the item stops picking up changes from its parent chain. + +For the full mechanics, see [SharePoint Embedded permission model](./permission-model.md). + +## Common errors + +| Symptom | Likely cause | +|---|---| +| `403 Forbidden` on any sharing call | Missing `FileStorageContainer.Selected`, or the caller's container role doesn't allow sharing. | +| `403 Forbidden` for a Writer trying to share | The container type has restricted sharing on (`isSharingRestricted = true`). Only Owners and Managers can share. | +| External recipient is rejected | The application's effective `sharingCapability` doesn't allow this kind of external sharing, or Microsoft Entra B2B isn't enabled in the consuming tenant. | +| Inviting a new guest with an app-only token fails | New guest invitations require delegated permissions on `invite`. Use a delegated flow for first-time guests. | +| `createPermission` is rejected with a non-group recipient | `createPermission` accepts only `sharePointGroup` in `grantedToV2` for SPE. Use `invite` for users or non-SharePoint groups. | +| `createPermission` is rejected on a container root | `createPermission` isn't allowed on the container root item. Grant a container role instead, or call the endpoint on a child item. | + +## Related content + +- [SharePoint Embedded permission model](./permission-model.md) +- [Authentication and authorization with SharePoint Embedded](./auth.md) +- [driveItem: invite](/graph/api/driveitem-invite) +- [driveItem: createPermission](/graph/api/driveitem-post-permissions) +- [driveItem: createLink](/graph/api/driveitem-createlink) +- [Create sharePointGroup](/graph/api/filestoragecontainer-post-sharepointgroups) +- [List sharePointGroups](/graph/api/filestoragecontainer-list-sharepointgroups) +- [delete permission](/graph/api/permission-delete) +- [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) +- [fileStorageContainerTypeSettings](/graph/api/resources/filestoragecontainertypesettings) +- [Set-SPOApplication](/powershell/module/sharepoint-online/set-spoapplication) diff --git a/docs/toc.yml b/docs/toc.yml index 9682cc3961..8758c67bf4 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -612,8 +612,10 @@ href: embedded/development/app-architecture.md - name: Authentication and Authorization href: embedded/development/auth.md - - name: Sharing and Permissions - href: embedded/development/sharing-and-perm.md + - name: SharePoint Embedded permission model + href: embedded/development/permission-model.md + - name: Share content in SharePoint Embedded + href: embedded/development/sharing.md - name: Limits and Calling Patterns href: embedded/development/limits-calling.md - name: Fluid Framework From 167ddbae50d98bf8a18f4f5e47c67e0f37b1ab0a Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Fri, 5 Jun 2026 16:31:42 -0700 Subject: [PATCH 2/3] Clarify permission grant descriptions in documentation Reworded sections for clarity and consistency regarding permissions in SharePoint Embedded. --- docs/embedded/development/permission-model.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/embedded/development/permission-model.md b/docs/embedded/development/permission-model.md index 08a3857648..65fd48bb84 100644 --- a/docs/embedded/development/permission-model.md +++ b/docs/embedded/development/permission-model.md @@ -13,23 +13,23 @@ ms.localizationpriority: high In SharePoint Embedded (SPE), you grant access to a container, a folder, or a file. By default, permissions flow down: a folder picks up its container's access, and a file picks up its folder's access. The level you choose sets the reach of the grant: -- Grant on the container, and the user gets that access on every folder and file in it. -- Grant on a folder, and the user gets that access on that folder and everything under it. -- Grant on a file, and the user gets that access on the file alone. +- Grant on the container, and the user receives access to all children folders and files. +- Grant on a folder, and the user receives access on that folder and all child items. +- Grant on a file, and the user receives access on the file alone. A grant is additive. It adds to whatever access the user already has from grants higher up the tree. When the default flow doesn't fit a particular folder or file, you can break inheritance on that item so its permissions are independent of the folder it sits in. In this article, you learn how to: - Grant access to a container with one of four built-in roles. -- Grant access to a folder and everything in it. +- Grant access to a folder and its children. - Grant access to a single file. - Break inheritance to give a folder or file independent permissions. -- Predict what happens to permissions when you copy or move an item. +- Add permissions when you copy or move an item. -## Granting access to a container and everything in it +## Granting access to a container -To give a user or group access to everything in a container, assign them one of four built-in container roles: +To give a user or group access to all content within a container, assign them one of four built-in container roles: | Role | What the user can do | |------|---------------------| @@ -42,9 +42,9 @@ A container role grants that role's access across the container's content by def For the full role definitions, see [Authentication and authorization with SharePoint Embedded](./auth.md). -## Granting access to a folder and everything in it +## Granting access to a folder -To give a user or group access to a single folder and everything under it, call a Microsoft Graph permission API on the folder. The API you use depends on who you're granting to. +To give a user or group access to a single folder and all its children, call a Microsoft Graph permission API on the folder. The API you use depends on who you're granting to. ### For a user or guest @@ -64,7 +64,7 @@ SPE rules: - Use app-only auth. SPE only supports `createPermission` with app-only. - SPE only accepts `sharePointGroup` permissions on this call. Other principal types are rejected. -### What the new permission does +### How inheritance affects new permissions The new permission applies to the folder. Subfolders and files inside the folder pick up the permission too, as long as they still inherit. A child folder or file with broken inheritance doesn't pick up the new permission. From b2cb762b7dcf9f9cd4c0c9a260bf1e4151992b6a Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Mon, 8 Jun 2026 13:20:05 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/embedded/development/permission-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/embedded/development/permission-model.md b/docs/embedded/development/permission-model.md index 65fd48bb84..db0d49fbe4 100644 --- a/docs/embedded/development/permission-model.md +++ b/docs/embedded/development/permission-model.md @@ -79,7 +79,7 @@ To give a user or group access to one file, call the same APIs on the file: - [`driveItem: invite`](/graph/api/driveitem-invite) for a user or guest. - [`driveItem: createPermission`](/graph/api/driveitem-post-permissions) for a SharePoint group. -The same SPE rules apply (see [Granting access to a folder and everything in it](#granting-access-to-a-folder-and-everything-in-it)). The new permission applies to the file alone, on top of whatever access the file already inherits from its parent folder and container. +The same SPE rules apply (see [Granting access to a folder](#granting-access-to-a-folder)). The new permission applies to the file alone, on top of whatever access the file already inherits from its parent folder and container. ## Breaking inheritance