diff --git a/docs/embedded/administration/billing/billing.md b/docs/embedded/administration/billing/billing.md index 6ef373a92..680e676a5 100644 --- a/docs/embedded/administration/billing/billing.md +++ b/docs/embedded/administration/billing/billing.md @@ -1,124 +1,42 @@ --- -title: PAYG billing for SharePoint Embedded -description: This article explains the billing models and how to set up PAYG billing. -ms.date: 03/03/2025 +title: Pay-as-you-go billing for SharePoint Embedded +description: This article explains the billing models and how to set up pay-as-you-go billing. +ms.date: 08/13/2025 ms.localizationpriority: high --- # SharePoint Embedded billing -SharePoint Embedded is a consumption-based Pay-as-you-go (PAYG) offering meaning you pay only for what you use. SharePoint Embedded provides two billing models that the tenant developing the SharePoint Embedded application can select for respective container types, tailoring it to their unique business requirements. The two billing models are Standard and Pass-through billing. +SharePoint Embedded is a consumption-based pay-as-you-go offering meaning you pay only for what you use. SharePoint Embedded provides two billing models that the tenant developing the SharePoint Embedded application can select for respective container types, tailoring it to their unique business requirements. The two billing models are Standard and Passthrough billing. -### Standard +## Standard billing With the standard billing model, all consumption-based charges are directly billed to the tenant who owns or develops the application. The admin in the developer tenant must establish a valid billing profile when creating a standard container type. -![Standard](../../images/1bill521.png) +![Standard billing](../../images/1bill521.png) -### Pass-through +## Passthrough billing -With pass-through billing, consumption-based charges are billed directly to the tenant registered to use the SharePoint Embedded application. Admins in the developer tenant don't need to set up a billing profile when creating a pass-through SharePoint Embedded container type. Once the container type is registered in the consuming tenant, the consuming tenant admin (SharePoint Admin or Global Admin) needs to set up the billing profile in the consuming tenant to use the SharePoint Embedded application. +With passthrough billing, consumption-based charges are billed directly to the tenant registered to use the SharePoint Embedded application. Admins in the developer tenant don't need to set up a billing profile when creating a passthrough SharePoint Embedded container type. Once the container type is registered in the consuming tenant, the consuming tenant admin (SharePoint Admin or Global Admin) needs to set up the billing profile in the consuming tenant to use the SharePoint Embedded application. -![Pass Through](../../images/2bill521.png) +![PassThrough billing](../../images/2bill521.png) -## Prerequisites to create SharePoint Embedded container type +## Create a SharePoint Embedded container type -A new container type will be created using **SharePoint Online Management Shell**: +For information on how to create a container type with billing enabled, see [creating a container type](../../getting-started/containertypes.md#creating-container-types). -1. Download and install the [latest version of SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588) -1. Open SharePoint Online Management Shell from **Start** screen, type **sharepoint**, and then select **SharePoint Online Management Shell**. -1. Connect to SPO service using `Connect-SPOService` cmdlet by providing admin credentials associated with tenancy. For information on [how to use Connect-SPOService](/powershell/module/sharepoint-online/connect-sposervice), refer the linked documentation. +## View & edit billing properties of standard container type -### Tenant requirements +You can view the properties of a container type and associated billing properties by using the Container Type APIs: -- An active instance of SharePoint is required in your Microsoft 365 tenant. -- Users who will be authenticating into SharePoint Embedded Container Types and Containers must be in Entra ID (Members and Guests) +- [List container types](/graph/api/filestorage-list-containertypes) +- [Get container type](/graph/api/filestoragecontainertype-get) - > [!NOTE] - > An Office license is not required to collaborate on Microsoft Office documents stored in a container. +To update the billing properties on a container type with standard billing, see [set the billing profile](../../getting-started/containertypes.md#set-the-billing-profile). -### Roles and Permissions +## Set up billing for passthrough container types in consuming tenant -- The admin who sets up the billing relationship for SharePoint Embedded needs to have owner or contributor permissions on the Azure subscription. -- Admin needs to have a SharePoint Embedded Administrator or Global Admin role to operate billing cmdlets. - -### Azure Subscription - -For the Standard Billing container type, the developer admin needs to set up: - -- An existing SharePoint tenancy -- An Azure subscription in the tenancy -- A resource group attached to the Azure subscription - -## Set up a Standard Billing container type - -For standard billed container types, developer admins should set up billing in their tenant. The Microsoft 365 SharePoint Embedded Administrator serves as the developer admin. Global Administrators in Microsoft 365 can assign users the SharePoint Embedded Administrator role, which already has all the permissions of the SharePoint Embedded Administrator role. The SharePoint Embedded Admin role is available in Microsoft Entra and Microsoft 365 Admin Center. - -SharePoint Embedded Admin can create a container type using the `New-SPOContainerType` cmdlet by providing an Azure subscription, the resource group associated with the subscription, and a region. - -- If you don't have an Azure subscription, you can create one by following the steps here to [create an Azure subscription in your tenancy](/azure/cloud-adoption-framework/ready/azure-best-practices/initial-subscriptions), -- If you don't have a resource group, you can create one by following the steps here to [create a resource group](/azure/azure-resource-manager/management/manage-resource-groups-portal) - -```powershell -New-SPOContainerType -ContainerTypeName - -OwningApplicationId - -AzureSubscriptionId - -ResourceGroup - -Region -``` - -> [!IMPORTANT] -> Every container type must have an owning application. -> -> A single-owning app can only own one container type at a time. -> -> An Azure subscription can be attached to any number of container types. - -### View & Edit billing properties of Standard container type - -You can view the properties of a container type and associated billing properties by using one of the two PowerShell cmdlets: - -1. See all container types and billing properties except associated region: - - ```powershell - Get-SPOContainerType - ``` - -1. See billing properties associated with a container type including region: - - ```powershell - Get-SPOContainerType -ContainerTypeId - ``` - -1. Update Azure subscription or resource group associated with a container type: - - ```powershell - Set-SPOContainerType -ContainerTypeId [-AzureSubscriptionId ] [-ResourceGroup ] - ``` - - -## Set up a Pass-through Billing container type - -For Pass-through Billing container types, the developer admin doesn't have to set up billing in the developer tenant. SharePoint Embedded Admin can create container type using `New-SPOContainerType` cmdlet with `isPassThroughBilling` specified. - -```powershell -New-SPOContainerType -ContainerTypeName - -OwningApplicationId - -isPassThroughBilling -``` - -### [Set Up Guide in Consuming Tenant Admin Center](../consuming-tenant-admin/cta.md#set-up-billing-for-pass-through-app) - -1. In [Microsoft 365 admin center](https://admin.microsoft.com/), select **Setup**, and the view the **Files and Content** section. Select **Automate Content with Microsoft Syntex.** - - ![Microsoft 365 admin center Files and Content](../../images/DTCBilling1.png) - -1. Select **Go to Syntex settings**. -1. Select **Apps** under **Syntex services for**, select **SharePoint Embedded** - - ![Microsoft 365 admin center SharePoint Embedded Billing setting](../../images/DTCBilling2.png) - -1. Follow the instructions on the **SharePoint Embedded** flyer to turn on SharePoint Embedded apps. +To set up billing for a passthrough container type in the consuming tenant, see the [setup guide in the consuming tenant Admin Center](../consuming-tenant-admin/cta.md#set-up-billing-for-passthrough-app). ## SharePoint Embedded meters diff --git a/docs/embedded/administration/billing/meters.md b/docs/embedded/administration/billing/meters.md index a6f770eea..7ad212a82 100644 --- a/docs/embedded/administration/billing/meters.md +++ b/docs/embedded/administration/billing/meters.md @@ -5,18 +5,17 @@ ms.date: 04/30/2025 ms.localizationpriority: high --- -# SharePoint Embedded Billing Meters +# SharePoint Embedded billing meters -SharePoint Embedded employs a pay-as-you-go (PAYG) billing model through an Azure subscription. Billing is determined by how much data in GB you store in SharePoint Embedded, transactions used to access and modify the container and container contents, and data that is egressed from the SharePoint Embedded platform. Each of these factors contributes to the overall cost, ensuring that you only pay for the resources and services you use. You can view this usage and billing details in the [Azure Cost Management](https://ms.portal.azure.com/). Both Standard Billing container type and Pass-through Billing container type will use the same meters. +SharePoint Embedded employs a pay-as-you-go (PAYG) billing model through an Azure subscription. Billing is determined by how much data in GB you store in SharePoint Embedded, transactions used to access and modify the container and container contents, and data that is egressed from the SharePoint Embedded platform. Each of these factors contributes to the overall cost, ensuring that you only pay for the resources and services you use. You can view this usage and billing details in the [Azure Cost Management](https://ms.portal.azure.com/). Both standard billing container type and passthrough billing container type will use the same meters. SharePoint Embedded has three billing meters as shown. Refer to the [product page](https://adoption.microsoft.com/en-us/sharepoint/embedded/) for pricing details. - ## Storage Storage consumption meters in SharePoint Embedded apply to the storage used by files and documents along with their metadata and versions. Storage consumption also includes all content in the recycle bin and deleted container collection within SharePoint Embedded. -## API Transactions +## API transactions Each Microsoft Graph call made explicitly by the SharePoint Embedded application is counted as one transaction and customers are billed based on the transaction count. See the [examples](/graph/api/resources/filestoragecontainer) of Microsoft Graph calls that can be made by a SharePoint Embedded application. diff --git a/docs/embedded/administration/consuming-tenant-admin/cta.md b/docs/embedded/administration/consuming-tenant-admin/cta.md index 786aa6acf..3a5b873a4 100644 --- a/docs/embedded/administration/consuming-tenant-admin/cta.md +++ b/docs/embedded/administration/consuming-tenant-admin/cta.md @@ -1,14 +1,14 @@ --- title: Consuming Tenant Admin description: This article describes the role and responsibilities of Consuming Tenant Admin in SharePoint Embedded. -ms.date: 03/03/2025 +ms.date: 08/13/2025 ms.localizationpriority: high --- # Consuming Tenant Admin > [!IMPORTANT] -> Assign the SharePoint Embedded Administrator role available in M365 Admin Center or Microsoft Entra to execute SharePoint Embedded Container cmdlets mentioned in this article. +> Assign the SharePoint Embedded Administrator role available in M365 Admin Center or Microsoft Entra ID to execute SharePoint Embedded Container cmdlets mentioned in this article. > > Global Administrators can continue to execute SharePoint Embedded container cmdlets. > @@ -18,13 +18,22 @@ The organizations that use the SharePoint Embedded applications on their Microso ## Consuming Tenant Admin Role -Microsoft 365 SharePoint Embedded Administrator serves as the consuming tenant admin. Global Administrators in Microsoft 365 can assign users the SharePoint Embedded Administrator. The Global Administrator role already has all the permissions of the SharePoint Embedded Administrator role. The SharePoint Embedded Role is available in Microsoft Entra and Microsoft 365 Admin Center. +Microsoft 365 SharePoint Embedded Administrator serves as the consuming tenant admin. Global Administrators in Microsoft 365 can assign users the SharePoint Embedded Administrator. The Global Administrator role already has all the permissions of the SharePoint Embedded Administrator role. The SharePoint Embedded Role is available in Microsoft Entra ID and Microsoft 365 Admin Center. For information on [SharePoint Embedded Admin](../adminrole.md) ## Administration Tools Consuming tenant admins can manage SharePoint Embedded applications with the following options: +### Microsoft Graph APIs + +The [fileStorageContainerTypeRegistration](/graph/api/resources/filestoragecontainertyperegistration) resource represents the registration of a container type in a consuming tenant. To manage all container type registrations in the consuming tenant, the `FileStorageContainerTypeReg.Manage.All` delegated permission is required. + +- [List container type registrations](/graph/api/filestorage-list-containertyperegistrations) +- [Get container type registrations](/graph/api/filestoragecontainertyperegistration-get) +- [Update container type registrations](/graph/api/filestoragecontainertyperegistration-update) +- [Delete container type registrations](/graph/api/filestorage-delete-containertyperegistrations) + ### SharePoint Online Management Shell On PowerShell, the SharePoint Embedded Admin can run the following cmdlets: @@ -48,19 +57,19 @@ The SharePoint Embedded Admin can access the Active and Deleted containers page For information on consuming tenant admin in SharePoint Admin see [container management](ctaUX.md) -## Security and Compliance Administration +## Security and compliance administration SharePoint Embedded uses Microsoft’s comprehensive compliance and data governance solutions to help organizations manage risks, protect, and govern sensitive data, and respond to regulatory requirements. Security and compliance solutions work in a similar manner in the SharePoint Embedded platform as they do today in the Microsoft 365 platform so that data is stored in a secure, protected way that meets customers’ business and compliance policies while making it easy for Compliance and SharePoint Administrators to enforce critical security and compliance policies on the content. For information on supported security and compliance capabilities, see [Security and Compliance](../../compliance/security-and-compliance.md). -## Set Up Billing for Pass-through App +## Set up billing for passthrough container type -To use Pass-through SharePoint Embedded App, SharePoint Embedded Admin needs to set up Microsoft Syntex billing in [Microsoft 365 admin center](https://admin.microsoft.com/). No user can access any Pass-through SharePoint Embedded apps before a valid billing is set up for the SharePoint Embedded platform. +To use passthrough billing SharePoint Embedded app, SharePoint Embedded Admin needs to set up Microsoft Syntex billing in [Microsoft 365 admin center](https://admin.microsoft.com/). No user can access any passthrough SharePoint Embedded apps before a valid billing is set up for the SharePoint Embedded platform. ### [Meters](../billing/meters.md) SharePoint Embedded employs a pay-as-you-go (PAYG) billing model through an Azure subscription. Billing is determined by how much data in GB you store in SharePoint Embedded, transactions used to access and modify the container and container contents, and data that is egressed from the SharePoint Embedded platform. Each of these factors contributes to the overall cost, ensuring that you only pay for the resources and services you use. You can view this usage and billing details in the [Azure Cost Management](https://ms.portal.azure.com/). -SharePoint Embedded has three billing meters as shown. Refer to the [product page](https://adoption.microsoft.com/en-us/sharepoint/embedded/) for pricing details +SharePoint Embedded has three billing meters as shown. Refer to the [product page](https://adoption.microsoft.com/en-us/sharepoint/embedded/) for pricing details | SharePoint Embedded Service Meters | Meter Unit | | :--------------------------------: | :------------: | diff --git a/docs/embedded/administration/developer-admin/dev-admin.md b/docs/embedded/administration/developer-admin/dev-admin.md index f9621225e..91b2a6aee 100644 --- a/docs/embedded/administration/developer-admin/dev-admin.md +++ b/docs/embedded/administration/developer-admin/dev-admin.md @@ -1,30 +1,30 @@ --- -title: Developer Admin -description: This article describes the role and responsibilities of Developer Tenant Admin in SharePoint Embedded. +title: SharePoint Embedded developer administrator +description: This article describes the role and responsibilities of developer tenant admin in SharePoint Embedded. ms.date: 03/03/2024 ms.localizationpriority: high --- -# Developer Admin +# SharePoint Embedded Developer Administrator ## Overview -Organizations that use SharePoint Embedded for file management are included in the Developer Ecosystem, which is overseen by developer administrators. These administrators are responsible for managing applications and the container types that have containers, the foundation of an application that needs to store content. Additionally, they can connect billing profiles to their applications. This article describes the management features available to developer administrators. +Organizations that use SharePoint Embedded for file management are included in the developer ecosystem which developer administrators oversee. These administrators are responsible for managing applications and the container types that have containers, the foundation of an application that needs to store content. Additionally, they can connect billing profiles to their applications. This article describes the management features available to developer administrators. -## Developer Admin Role +## Developer Admin role > [!IMPORTANT] -> Global Administrators can assign the SharePoint Embedded Administrator role available in M365 Admin Center or Microsoft Entra to execute SharePoint Embedded container commandlets mentioned in this article. +> Global Administrators can assign the SharePoint Embedded Administrator role available in Microsoft 365 Admin Center or Microsoft Entra ID to execute SharePoint Embedded container cmdlets mentioned in this article. > > Global Administrators can continue to execute SharePoint Embedded container cmdlets. -A Microsoft 365 SharePoint Embedded Administrator serves as the developer admin. Global Administrators in Microsoft 365 can assign users the SharePoint Embedded Administrator role. The Global Administrator role already has all the permissions of the SharePoint Embedded Administrator role. The SharePoint Embedded Role is available in Microsoft Entra and Microsoft 365 Admin Center. For information on [SharePoint Embedded Administrator](../adminrole.md) role. +A Microsoft 365 SharePoint Embedded Administrator serves as the developer admin. Global Administrators in Microsoft 365 can assign users the SharePoint Embedded Administrator role. The Global Administrator role already has all the permissions of the SharePoint Embedded Administrator role. The SharePoint Embedded Role is available in Microsoft Entra ID and Microsoft 365 Admin Center. For information on [SharePoint Embedded Administrator](../adminrole.md) role. The following are some of the container-specific commands actions currently supported on PowerShell: - Creation of container types - - Creation of Standard container type with standard billing - - Creation of Standard container type with direct to customer billing - - Creation of Trial container type + - Creation of standard container type with standard billing + - Creation of standard container type with passthrough billing + - Creation of trial container type - Container type management - Viewing of container types in the tenant - Editing properties of a container type in the tenant @@ -34,19 +34,26 @@ The following are some of the container-specific commands actions currently supp ### Billing responsibilities of the developer admin -There are two types of billing models followed: +There are two types of billing models in SharePoint Embedded. To learn more, see [SharePoint Embedded billing](../billing/billing.md). -Standard billing: -The developer admin is responsible for the billing of SharePoint Embedded applications. The developer admin needs to establish billing for SharePoint Embedded while creating container types given they have owner or contributor permissions on the Azure subscription that they use to establish the billing relationship on the product. To learn more about how to set up billing and manage cost and invoice, read about [PAYG for SharePoint Embedded](../billing/billing.md). +#### Standard billing -Direct to Customer billing: -In this model, the customer, or the consuming tenant admin, is responsible for billing. To ensure the Direct to Customer (DTC) Billing model, the developer admin must set the billing property of Direct to customer to enabled. +The developer admin is responsible for the billing of SharePoint Embedded applications. The developer admin needs to [set the billing profile for the container type](../../getting-started/containertypes.md#set-the-billing-profile) after its creation, provided they have owner or contributor permissions on an Azure subscription. To learn more about how to set up billing, read about [creating container types](../../getting-started/containertypes.md#creating-container-types) and [SharePoint Embedded billing](../billing/billing.md). + +#### Passthrough billing + +In this model, the customer, or the consuming tenant admin, is responsible for billing. For this reason, this billing model is also known as "direct-to-customer billing." To ensure the passthrough billing model is in place, the developer admin must set the `billingClassification` on the container type to `directToCustomer`. To learn more about how to set up passthrough billing in the container type, read about [creating container types](../../getting-started/containertypes.md#creating-container-types). To learn more about how to configure billing for SharePoint Embedded applications with passthrough billing in a consuming tenant, see [setup guide in the consuming tenant Admin Center](../consuming-tenant-admin/cta.md#set-up-billing-for-passthrough-app). ## Administration Tools -Developer admins are able to manage SharePoint Embedded applications with PowerShell commands using SharePoint Online Management Shell. +Developer admins are able to manage SharePoint Embedded applications with Microsoft Graph APIs and PowerShell commands using the SharePoint Online Management Shell. + +To get started using the Microsoft Graph APIs for SharePoint Embedded management, see: -To get started using PowerShell to manage SharePoint Embedded, you have to install the SharePoint Online Management Shell and connect to SharePoint Online. +- [fileStorageContainerType](/graph/api/resources/filestoragecontainertype) resource representing a container type and its related methods +- [fileStorageContainerTypeRegistration](/graph/api/resources/filestoragecontainertyperegistration) resource representing the registration of a container type in a consuming tenant and its related methods + +To get started using PowerShell to manage SharePoint Embedded, you have to install the SharePoint Online Management Shell and connect to SharePoint. > [!IMPORTANT] > You must use the latest version of SharePoint PowerShell to use container type administration cmdlets. @@ -55,14 +62,16 @@ To get started using PowerShell to manage SharePoint Embedded, you have to insta ### Creation of container types -The developer administrator can create a container type using PowerShell cmdlets. Each container type is associated to an application ID, a one to one mapping, and an Azure subscription ID. The developer administrator can also create Trial container types that have a validity of 30 days to test out SharePoint Embedded. The following [commands](/powershell/module/sharepoint-online/new-spocontainertype) can be used to create SharePoint Embedded container types on the developer admin’s tenant: +The developer administrator can create a container type using PowerShell cmdlets. Each container type is associated to an application ID, a one to one mapping, and an Azure subscription ID. The developer administrator can also create trial container types that have a validity of 30 days to test out SharePoint Embedded. The following [commands](/powershell/module/sharepoint-online/new-spocontainertype) can be used to create SharePoint Embedded container types on the developer admin’s tenant: Standard billing container type: ```powershell -New-SPOContainerType -ContainerTypeName -OwningApplicationId -AzureSubscriptionId -ResourceGroup -Region ​ +New-SPOContainerType -ContainerTypeName -OwningApplicationId +Add-SPOContainerTypeBilling -ContainerTypeId -AzureSubscriptionId -ResourceGroup -Region ​ ``` -Direct to customer billing container type: + +Passthrough billing container type: ```powershell New-SPOContainerType -IsPassThroughBilling -ContainerTypeName -OwningApplicationId @@ -74,7 +83,7 @@ Trial container type: New-SPOContainerType –TrialContainerType -ContainerTypeName -OwningApplicationId ``` -OwningApplicationId is the ID of the SharePoint Embedded application. Azure Subscription ID is the ID of the Microsoft Entra ID profile for billing purposes. +`OwningApplicationId` is the ID of the SharePoint Embedded application. `AzureSubscriptionId` is the ID of the Azure subscription for billing purposes. ### Viewing of container types @@ -87,7 +96,7 @@ Get-SPOContainerType -ContainerTypeId ### Manage properties of container types -Using PowerShell cmdlets, the developer administrator can change the properties of container types, both standard and trial. The following commands can be used to change the properties SharePoint Embedded applications created on the developer admin’s tenant: +The developer administrator can change the properties of container types, both standard and trial. The following commands can be used to change the properties SharePoint Embedded applications created on the developer admin’s tenant: ```powershell Set-SPOContainerType -ContainerTypeId @@ -129,7 +138,7 @@ The developer admin can view the container type configuration settings using the Get-SPOContainertypeConfiguration -ContainerTypeId < ContainerTypeId > ``` -## Manage billing profile of applications/ container types +## Manage billing profile of container types The developer administrator can change the billing profile of container types using PowerShell cmdlets. The following commands can be used to change the properties SharePoint Embedded applications created on the developer admin’s tenant: diff --git a/docs/embedded/development/auth.md b/docs/embedded/development/auth.md index 6e20ceb95..6b2fe7222 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: 06/24/2025 +ms.date: 07/16/2025 ms.localizationpriority: high --- @@ -51,6 +51,7 @@ SharePoint Embedded operations [without a user](/graph/auth-v2-service) require Currently, there are two types of operations with exceptional access patterns: +- [Hidden permissions in Microsoft Graph](#hidden-microsoft-graph-permissions) - [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) @@ -58,26 +59,38 @@ Currently, there are two types of operations with exceptional access patterns: > [!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. +### Hidden Microsoft Graph permissions + +The following operations require permissions that are currently hidden in Microsoft Graph: + +- [Container type management](../getting-started/containertypes.md) on owning tenants. +- [Container type registration](../getting-started/register-api-documentation.md) on consuming tenants. + +The Microsoft Graph permissions are rolling out to all tenants in the near future and will be visible once the rollout completes. + +#### Granting admin consent for hidden permissions + +[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: + +```http +https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id={client_id}&scope=https://graph.microsoft.com/.default +``` + +> [!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. + #### Operations not exposed via Microsoft Graph -There are two types of operations that aren't accessible via Microsoft Graph today: +There is one scenario that isn't accessible via Microsoft Graph today: -- [Container type management](../getting-started/containertypes.md) on owning tenants, which are performed via PowerShell cmdlets. -- [Container type registration](../getting-started/register-api-documentation.md) on consuming tenants, exposed via SharePoint REST API v2. - [SharePoint Embedded agent](./declarative-agent/spe-da.md) exposed via SharePoint REST API v2 permissions. -To perform [container type management](../getting-started/containertypes.md) operations, you must be a [SharePoint Embedded Administrator](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) or [Global Administrator](/entra/identity/role-based-access-control/permissions-reference#global-administrator). - -To [register a container type](../getting-started/register-api-documentation.md), you must request the `Container.Selected` permission on the `Office 365 SharePoint Online` resource. +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: | 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. | -> [!NOTE] -> Container type management on owning tenants and registration on consuming tenants will become Microsoft Graph operations soon, and this permission will no longer be needed. Stay tuned. - -To use the [SharePoint Embedded agent](./declarative-agent/spe-da.md) experience (in the Preview stage) in your application, you also need the `Container.Selected` permission on the `Office 365 SharePoint Online` resource. #### Operations involving searching SharePoint Embedded content @@ -143,22 +156,22 @@ Any user accessing a container must be a member of the container. Membership to 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: - - - Microsoft Graph (resourceAppId: `00000003-0000-0000-c000-000000000000`) - - `FileStorageContainer.Selected` (type: `Scope`, ID: `085ca537-6565-41c2-aca7-db852babc212`) to access containers on consuming tenants - - Office 365 SharePoint Online (resourceAppId: `00000003-0000-0ff1-ce00-000000000000`) - - `Container.Selected` (type: `Role`, ID: `19766c1b-905b-43af-8756-06526ab42875`) to register a container on consuming tenants - -1. [Grant admin consent](/entra/identity-platform/v2-admin-consent) to your application on both owning and consuming tenants (which can be the same tenant). - - > [!NOTE] - > The `Container.Selected` application permission is hidden, which can cause issues with granting admin consent using the Enterprise apps pane in the Azure portal. Instead, [construct the admin consent URL](/entra/identity-platform/v2-admin-consent#request-the-permissions-from-a-directory-admin) and provide it to your Microsoft Entra directory administrator. For example: - > - > `https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id={client_id}` - > - > Make sure the Microsoft Entra directory administrator [confirms a successful response](/entra/identity-platform/v2-admin-consent#successful-response). - -1. [Create a new container type](../getting-started/containertypes.md) on the owning tenant. -1. [Register a container type](../getting-started/register-api-documentation.md) on the consuming tenant. -1. [Create a container](/graph/api/filestoragecontainer-post) +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. [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. + - 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 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. [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 diff --git a/docs/embedded/getting-started/containertypes.md b/docs/embedded/getting-started/containertypes.md index f21edc78f..0a45a91c1 100644 --- a/docs/embedded/getting-started/containertypes.md +++ b/docs/embedded/getting-started/containertypes.md @@ -1,124 +1,132 @@ --- -title: Create New SharePoint Embedded Container Types -description: This article explains how Container Types work and the steps to create new Container Types. -ms.date: 03/03/2025 +title: Create New SharePoint Embedded container types +description: This article explains how container types work and the steps to create new container types. +ms.date: 07/17/2025 ms.localizationpriority: high --- -# SharePoint Embedded Container Types +# SharePoint Embedded container types A container type is a SharePoint Embedded resource that defines the relationship, access privileges, and billing accountability between a SharePoint Embedded application and a set of containers. Also, the container type defines behaviors on the set of containers. Each container type is strongly coupled with one SharePoint Embedded application, which is referred to as the owning application. The owning application developer is responsible for creating and managing their container types. SharePoint Embedded mandates a 1:1 relationship between owning application and a container type. -Container type is represented on each container instance as an immutable property (ContainerTypeID) and is used across the entire SharePoint Embedded ecosystem, including: +A container type is represented on each container instance as an immutable property (ContainerTypeID) and is used across the entire SharePoint Embedded ecosystem, including: - **Access authorization**: A SharePoint Embedded application must be associated with a container type to get access to container instances of that type. Once associated, the application has access to all container instances of that type. The actual access privilege is determined by the application-ContainerTypeID permission setting. The owning application by default has full access privilege to all container instances of the container type it's strongly coupled with. Learn more about [SharePoint Embedded Authorization](../development/auth.md). - **Easy exploration**: Container type can be created for trial purposes, allowing developers to explore SharePoint Embedded application development and assess its features for free. -- **Billing**: Container types for non-trial purposes are billable and must be created with an Azure Subscription. The usage of containers is metered and charged. Learn more about [metering](../administration/billing/meters.md) and the [SharePoint Embedded billing experience](../administration/billing/billingmanagement.md). +- **Billing**: Container types for nontrial purposes are billable and must be created with an Azure Subscription. The usage of containers is metered and charged. Learn more about [metering](../administration/billing/meters.md) and the [SharePoint Embedded billing experience](../administration/billing/billingmanagement.md). - **Configurable behaviors**: Container type defines selected behaviors for all container instances of that type. Learn more about setting [Container type configuration](../getting-started/containertypes.md#configuring-container-types). > [!NOTE] > -> 1. You must specify the purpose of the container type you're creating at creation time. Depending on the purpose, you may or may not need to provide your Azure Subscription ID. A container type set for trial purposes can't be converted for production; or vice versa. -> 1. Standard and pass through container types can't be converted once created. If you want to convert a standard container type to pass through billing or vice versa, you must delete and re-create the container type. -> 1. You must use the latest version of SharePoint PowerShell to configure a container type. For permissions and the most current information about Windows PowerShell for SharePoint Embedded, see the documentation at [Intro to SharePoint Embedded Management Shell](/powershell/sharepoint/sharepoint-online/introduction-sharepoint-online-management-shell). +> 1. You must specify the purpose of the container type you're creating at creation time. A container type set for trial purposes can't be converted for production; or vice versa. +> 1. Standard and passthrough container types can't be converted once created. If you want to convert a standard container type to passthrough billing or vice versa, you must delete and re-create the container type. -## Creating Container Types - -SharePoint Embedded has 2 different Container Types you can create. - -1. [Trial Container Type](#trial-container-type) -1. [Standard Container Type](#standard-container-types-non-trial) - -### Prerequisites to create SharePoint Embedded container type - -A new container type will be created using **SharePoint Online Management Shell**: - -1. Download and install the [latest version of SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588) -1. Open SharePoint Online Management Shell from **Start** screen, type **sharepoint**, and then select **SharePoint Online Management Shell**. -1. Connect to SPO service using `Connect-SPOService` cmdlet by providing admin credentials associated with tenancy. For information on [how to use Connect-SPOService](/powershell/module/sharepoint-online/connect-sposervice), refer the linked documentation. - -### Tenant requirements +## Tenant requirements - An active instance of SharePoint is required in your Microsoft 365 tenant. -- Users who will be authenticating into SharePoint Embedded Container Types and Containers must be in Entra ID (Members and Guests) +- Users who authenticate into SharePoint Embedded container types and containers must be in Microsoft Entra ID (Members and Guests) +- A Microsoft Entra ID app registration needs to be configured for container type management. For more information, see [SharePoint Embedded authentication and authorization](../development/auth.md). - > [!NOTE] - > An Office license is not required to collaborate on Microsoft Office documents stored in a container. +> [!NOTE] +> An Office license isn't required to collaborate on Microsoft Office documents stored in a container. -### Roles and Permissions +## Creating container types -- The admin who sets up the billing relationship for SharePoint Embedded needs to have owner or contributor permissions on the Azure subscription. -- Admin needs to have a SharePoint Embedded Administrator or Global Admin role to operate billing cmdlets. +SharePoint Embedded has two different container types you can create. -### Azure Subscription +1. [Trial container type](#trial-container-type). Uses the `trial` billing classification. +1. [Standard container type](#standard-container-types-non-trial). Uses the `standard` or `directToCustomer` billing classification. -For the standard billing container type, the global administrator or SharePoint Embedded Administrator needs to set up: +To create a container type, your Microsoft Entra ID application needs to have the `FileStorageContainerType.Manage.All` application permission on the owning tenant. Your Microsoft Entra ID application needs to call the [Create fileStorageContainerType](/graph/api/filestorage-post-containertypes) endpoint on behalf of a [SharePoint Embedded Administrator](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator): -- An existing SharePoint tenancy -- An Azure subscription in the tenancy -- A resource group attached to the Azure subscription +```http +POST https://graph.microsoft.com/beta/storage/fileStorage/containerTypes +Content-Type: application/json -## Trial Container Type +{ + "name": "{ContainerTypeName}", + "owningAppId": "{ApplicationId}", + "billingClassification": "{BillingClassification}", + "settings": { + ... + } +} +``` -A container type can be created for trial/development purposes and isn't linked to any Azure billing profile. This enables developers to explore SharePoint Embedded application development and assess its features for free. For trial container types, the developer tenant is the same as the consuming tenant. -Each developer can have only one container type in the trial status in their tenant at a time. The trial container type is valid for up to 30 days but can be removed at any time within this period. +> [!NOTE] +> You need to replace: +> +> - `{ContainerTypeName}` with a user-friendly name for your SharePoint Embedded application. +> - `{ApplicationId}` with the ID of your properly configured application ID. +> - `{BillingClassification}` with either `trial`, `standard`, or `directToCustomer`. Keep reading to understand what each means. +> +> Additionally, you may [configure your container type](#configuring-container-types) during creation by using the `settings` field. -To create a container type for trial purposes, you can: +## Trial container type -- Use SharePoint Embedded Visual Studio Code Extension to create the container type in just a few steps. The Visual Studio Code extension registers your container type and creates containers for you. -- Use SharePoint PowerShell. You must be a SharePoint Embedded Administrator or Global Administrator to run the following cmdlet. If you're a SharePoint Administrator, grant yourself the SharePoint Embedded Admin role as well to execute these cmdlets. +A container type can be created for trial/development purposes and isn't linked to any Azure billing profile. Trial container types enable developers to explore SharePoint Embedded application development and assess its features for free. For trial container types, the developer tenant is the same as the consuming tenant. +Each developer can have only one container type with `trial` billing classification in their tenant at a time. The trial container type is valid for up to 30 days but can be removed at any time within this period. - ```powershell - New-SPOContainerType [–TrialContainerType] [-ContainerTypeName] [-OwningApplicationId] [-ApplicationRedirectUrl] [] - ``` +You can easily set up a trial container type using the [SharePoint Embedded Visual Studio Code extension](../getting-started/spembedded-for-vscode.md). The following restrictions are applied to trial container types: -- Up to five containers of the container type can be created. This includes active containers and those in the recycle bin. +- The tenant can have up to five containers of the container type. This includes active containers and those in the recycle bin. - Each container has up to 1 GB of storage space. -- The container type expires after 30 days and access to any existing containers of that container type will be removed. +- The container type expires after 30 days and access to any existing containers of that container type is then removed. - The developer must permanently delete all containers of an existing container type in trial status to create a new container type for trial. This includes containers in the deleted container collection. - The container type is restricted to work in the developer tenant. It can't be deployed in other consuming tenants. -## Standard Container Types (non-trial) +## Standard container types (nontrial) -A standard container type in SharePoint Embedded defines the relationship, access privileges, and billing profile between an application and its containers. It establishes how the application interacts with the containers, including access permissions, and is associated with a billing profile for non-trial purposes. Each tenant can have 25 container types at a time. +A standard container type can be used in production environments. Each tenant can have 25 container types at a time. Standard container types don't have the same restrictions as trial container types, but they still have limits. For more information, see [SharePoint Embedded Limits](../development/limits-calling.md). + +To learn more about the supported pay-as-you-go meters, refer to the [SharePoint Embedded meters](../administration/billing/meters.md) article. ### Billing profile -SharePoint Embedded is a consumption-based Pay-as-you-go (PAYG) offering meaning you pay only for what you use. SharePoint Embedded provides two billing models that the tenant developing the SharePoint Embedded application can select for respective container types, tailoring it to their unique business requirements. The two billing models are Standard and Pass-through billing. +SharePoint Embedded is a consumption-based Pay-as-you-go (pay-as-you-go) offering meaning you pay only for what you use. SharePoint Embedded provides two billing models that the tenant developing the SharePoint Embedded application can select for respective container types, tailoring it to their unique business requirements. The two billing models are Standard and Passthrough billing. -### Standard Container Type - with billing profile +### Standard container type - with billing profile With the standard billing profile, all consumption-based charges are directly billed to the tenant who owns or develops the application. The admin in the developer tenant must establish a valid billing profile when creating a standard container type. ![Standard](../images/1bill521.png) -Each developer tenant can create up to five container types consisting of 1 trial container type and 4 standard container types or 5 standard container types. -Standard container types are created using the [New-SPOContainerType](/powershell/module/sharepoint-online/new-spocontainertype) cmdlet. +There are limits around the number of container types that each tenant can have. For more information, see [SharePoint Embedded Limits](../development/limits-calling.md). + +### Roles and Permissions + +- The admin who sets up the billing relationship for SharePoint Embedded needs to have owner or contributor permissions on the Azure subscription. +- The admin needs to have a SharePoint Embedded Administrator or Global Administrator role to operate billing cmdlets. -You need the following to create a standard container type: +### Azure Subscription -- Use SharePoint PowerShell. You must be a SharePoint Embedded Administrator or Global Administrator to run this cmdlet. If you're a SharePoint Administrator, grant yourself the SharePoint Embedded Admin role as well to execute these cmdlets. -- An Azure subscription and a resource group must be present in the Azure portal for regular billing. -- An App registration must be created in Microsoft Entra ID. +For the standard billing container type, the Global Administrator needs to: -To create a standard container type using an Azure billing profile, use the following cmdlets: +- [Create an Azure subscription in your tenancy](/azure/cloud-adoption-framework/ready/azure-best-practices/initial-subscriptions) +- [Create a resource group](/azure/azure-resource-manager/management/manage-resource-groups-portal) attached to the Azure subscription -```powershell -New-SPOContainerType [-ContainerTypeName] [-OwningApplicationId] [-ApplicationRedirectUrl] [] -``` +After [creating the container type](#creating-container-types) with `standard` billing classification, you need to attach a billing profile to the container type. + +### Set the billing profile -Once the container type is created, add the Azure billing profile. +The billing profile for your container type is created using **SharePoint Online Management Shell**: + +1. Download and install the [latest version of SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588) +1. Open SharePoint Online Management Shell from **Start** screen, type **sharepoint**, and then select **SharePoint Online Management Shell**. +1. Connect to SPO service using `Connect-SPOService` cmdlet by providing admin credentials associated with tenancy. For information, see [how to use Connect-SPOService](/powershell/module/sharepoint-online/connect-sposervice). +. +To create the standard billing profile for your container type, use the following cmdlet: ```powershell Add-SPOContainerTypeBilling –ContainerTypeId -AzureSubscriptionId -ResourceGroup -Region ``` > [!NOTE] -> The user or admin who sets up a billing relationship for SharePoint Embedded must have owner or contributor permissions on the Azure subscription. +> The admin who sets up a billing relationship for SharePoint Embedded must have owner or contributor permissions on the Azure subscription, and be assigned the SharePoint Embedded Administrator or Global Administrator role. > > Every container type must have an owning application. > @@ -126,82 +134,59 @@ Add-SPOContainerTypeBilling –ContainerTypeId -AzureSubscript > > An Azure subscription can be attached to any number of container types. > -> If the cmdlet above fails with a SubscriptionNotRegistered error, it is because **Microsoft.Syntex** is not registered as a resource provider in the subscription. The cmdlet will send a resource provider registration request on your behalf but it will take a few minutes to be completed. Please wait 5-10 minutes and try again until the cmdlet succeeds. - -### Standard Container Type - pass-through billing - -With pass-through billing, consumption-based charges are billed directly to the tenant registered to use the SharePoint Embedded application (consuming tenant). Admins in the developer tenant don't need to set up an Azure billing profile when creating a pass-through SharePoint Embedded container type. - -![Pass Through](../images/2bill521.png) - -For container types intended to be directly billed to a customer use the flag `-IsPassThroughBilling`. For the direct to customer billed container type, there's no need to attach a billing profile. +> If the cmdlet above fails with a SubscriptionNotRegistered error, it is because **Microsoft.Syntex** isn't registered as a resource provider in the subscription. The cmdlet sends a resource provider registration request on your behalf but it takes a few minutes to be completed. Wait 5-10 minutes and try again until the cmdlet succeeds. -To create a pass through billing, standard container type, use the following cmdlet: +To update the billing profile for a standard container type, use the following cmdlet: ```powershell -New-SPOContainerType [-ContainerTypeName] [-OwningApplicationId] [-ApplicationRedirectUrl] [-IsPassThroughBilling] [] +Set-SPOContainerType -ContainerTypeId [-AzureSubscriptionId ] [-ResourceGroup ] ``` -Once the container type is [registered](../getting-started/register-api-documentation.md) in the consuming tenant, the consuming tenant admin (SharePoint Admin or Global Admin) needs to set up the billing profile in the consuming tenant to use the SharePoint Embedded application. +> [!NOTE] +> Billing setup for standard container types is done via the SharePoint Online Management Shell. In the future, this operation will be available as a Microsoft Graph operation. -#### Set Up Billing Profile in Consuming Tenant +### Standard container type - passthrough billing -1. In [Microsoft 365 admin center](https://admin.microsoft.com/), select **Setup**, and the view the **Billing and licenses** section. Select **Activate pay-as-you-go services.** +With passthrough billing, consumption-based charges are billed directly to the tenant registered to use the SharePoint Embedded application (consuming tenant). Admins in the developer tenant don't need to set up an Azure billing profile when creating a passthrough SharePoint Embedded container type. - ![Microsoft 365 admin center Files and Content](../images/SyntexActivatePAYGSetup.png) +![Pass Through](../images/2bill521.png) -1. Select **Go to Pay as you go services**. -1. Select **Apps** under **Syntex services for**, select **Apps** and **SharePoint Embedded** - - ![Microsoft 365 admin center SharePoint Embedded Billing setting](../images/SyntexPAYGActivateSPE.png) +For container types intended to be directly billed to a customer use the `directToCustomer` billing classification during [container type creation](#creating-container-types). For the passthrough billing container types, there's no need to attach a billing profile. - > [NOTE] - The subscription configured in the Syntex services will reflect the consuming charges in the Azure billing portal. +Once the container type is [registered](../getting-started/register-api-documentation.md) in the consuming tenant, the consuming tenant admin (SharePoint Administrator or Global Administrator) needs to set up the billing profile in the consuming tenant to use the SharePoint Embedded application. -1. [Register the container type](#registering-container-types) using the App only authentication token. +#### Set up billing profile in consuming tenant -## Configuring Container Types +1. In [Microsoft 365 admin center](https://admin.microsoft.com/), select **Setup**, and the view the **Billing and licenses** section. Select **Activate pay-as-you-go services.** -The Developer Admin can set selected settings on the SharePoint Embedded container types created by using this PowerShell cmdlet. + ![Microsoft 365 admin center Files and Content](../images/SyntexActivatePAYGSetup.png) -This cmdlet allows admins to set [Microsoft 365 content discoverability](../development/content-experiences/user-experiences-overview.md) and [sharing](../development/sharing-and-perm.md) settings on container types. The setting applies to all container instances of the container type: +1. Select **Go to Pay as you go services**. +1. Select **Apps** under **Syntex services for**, then select **SharePoint Embedded** in the Apps panel -```powershell -Set-SPOContainerTypeConfiguration -ContainerTypeId 4f0af585-8dcc-0000-223d-661eb2c604e4 -DiscoverabilityDisabled $False -``` + ![Microsoft 365 admin center SharePoint Embedded Billing setting](../images/SyntexPAYGActivateSPE.png) -## Viewing Container Types + > [!NOTE] + > The subscription configured in the Syntex services will reflect the consuming charges in the Azure billing portal. -The Developer Admin can view all the SharePoint Embedded container types they created on their tenant using `Get-SPOContainerType`. This cmdlet retrieves and returns the list of container types created for a SharePoint Embedded Application in the tenant. +## Configuring container types -```powershell -Get-SPOContainerType [] -``` +The Developer Admin may apply configuration when calling the [Create fileStorageContainerType](/graph/api/filestorage-post-containertypes) endpoint. Alternatively, they may call the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) endpoint to reconfigure an existing container type. -Example output of the `Get-SPOContainerType` cmdlet +> [!IMPORTANT] +> Updating settings on a container type may take up to **24 hours** for the new values to be replicated on all consuming tenants. If a consuming tenant applied overrides on container type settings, the new values aren't applied and the overrides remain in place. Some settings only apply to new content and not to existing content for the container type (for example, storage size, discoverability enabled, and others). -```powershell -ContainerTypeId : 4f0af585-8dcc-0000-223d-661eb2c604e4 -ContainerTypeName : ContosoLegal -OwningApplicationId : a735e4af-b86e-0000-93ba-1faded6c39e1 -Classification : Standard -AzureSubscriptionId : 564e9025-f7f5-xxx9-9ddd-4cdxxxx1755 -ResourceGroup : prod-resources -Region : EastUS -``` +For information on all the settings supported by container types, see [fileStorageContainerTypeSettings resource type](/graph/api/resources/filestoragecontainertypesettings). -## Registering Container Types +## Viewing container types -To create and interact with containers, you must [register](../getting-started/register-api-documentation.md) the container type within the Consuming Tenant. The owning application defines the permissions for the container type by invoking the [registration API](../getting-started/register-api-documentation.md). +The Developer Admin can view all the SharePoint Embedded container types they created on their tenant using the [List fileStorageContainerType](/graph/api/filestorage-list-containertypes) endpoint. -## Deleting Container Types +## Registering container types -Developer admins can delete both trial and standard container types. To delete a container type, you must first remove all containers of that container type, including from the deleted container collection. To remove containers, refer to [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md). -Once all the containers are deleted, Developer admins can delete the container type using `Remove-SPOContainerType`. +To create and interact with containers, you must [register](../getting-started/register-api-documentation.md) the container type within the Consuming Tenant. The owning application defines the permissions for the container type by invoking the [Create fileStorageContainerTypeRegistration](/graph/api/filestorage-post-containertyperegistrations) endpoint. -```powershell -Remove-SPOContainerType [-ContainerTypeId ] -``` -## SharePoint Embedded meters +## Deleting container types -To learn more about the supported pay-as-you-go meters, refer to the [SharePoint Embedded meters](../administration/billing/meters.md) article. +The Developer Admin can delete both trial and standard container types in their tenant. To delete a container type, you must first remove all containers of that container type, including from the deleted container collection. To remove containers, refer to [Consuming Tenant Admin](../administration/consuming-tenant-admin/cta.md). +Once all the containers are deleted, Developer admins can delete the container type using the [Delete fileStorageContainerType](/graph/api/filestorage-delete-containertypes) endpoint. diff --git a/docs/embedded/getting-started/register-api-documentation.md b/docs/embedded/getting-started/register-api-documentation.md index 320893e72..7a5b7120b 100644 --- a/docs/embedded/getting-started/register-api-documentation.md +++ b/docs/embedded/getting-started/register-api-documentation.md @@ -1,44 +1,40 @@ --- -title: Register File Storage container Type Application Permissions +title: Register file storage container type application permissions description: Register the container type. -ms.date: 03/03/2025 +ms.date: 08/11/2025 ms.localizationpriority: high --- # Register file storage container type application permissions -In order for a SharePoint Embedded application to interact with containers in a consuming tenant, the container type must first be registered in the consuming tenant. Container type registration happens when the owning application invokes the registration API to specify what permissions can be performed against its container type. The registration API also grants access to other Guest Apps to interact with the owning application's containers. For example, a SharePoint Embedded application can grant permissions to another application--a Guest App so that the Guest App can perform backup operations against its containers. +In order for a SharePoint Embedded application to interact with containers in a consuming tenant, the container type must first be registered in the consuming tenant. Container type registration happens when the owning application invokes the registration API to specify how applications can access its container type. The registration API also grants access to other Guest Apps to interact with the owning application's containers. For example, a SharePoint Embedded application can grant permissions to another application--a Guest App so that the Guest App can perform backup operations against its containers. -Since the registration API controls the permissions that a SharePoint Embedded application can perform against the container in the consuming tenant, this call should be one of the first APIs invoked. Failure to do so results in access denied errors when invoking other APIs against the container and/or the content in the containers. +Since the [container type registration API](/graph/api/filestorage-post-containertyperegistrations) controls the access to a container type in the consuming tenant, it's the first endpoint invoked by a SharePoint Embedded application on a consuming tenant. Failure to do so results in access denied errors when invoking other APIs against containers and/or content in the containers. There are no restrictions on how many times the registration API can be invoked. How often the registration API is invoked and when it's invoked is dependent on the SharePoint Embedded application. However, the last successful call to the registration API determines the settings used in the consuming tenant. ## Authentication and authorization requirements -For the container type's owning application to act on a consuming tenant, some pre-requisites must be completed: +For the container type's owning application to act on a consuming tenant, some prerequisites must be completed: - the owning app must have a service principal installed on the consuming tenant; and - the owning app must be granted admin consent to perform container type registration in the consuming tenant. -> [!NOTE] -> Only the owning application of the container type can invoke the registration API in the consuming tenant. - -Both requirements can be satisfied by having a tenant administrator of the consuming tenant [grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal) to the container type's owning application. +You can satisfy these requirements by having the consuming tenant's Global Administrator [grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal) to the container type's owning application. -The container type registration API requires the `Container.Selected` app-only permission for SharePoint (see [Exceptional access patterns](../development/auth.md#exceptional-access-patterns)). You will need to use the [client credentials grant flow](/entra/identity-platform/v2-oauth2-client-creds-grant-flow) and [request a token with a certificate](/entra/identity-platform/v2-oauth2-client-creds-grant-flow#second-case-access-token-request-with-a-certificate) to use the registration API. +The [container type registration API](/graph/api/filestorage-post-containertyperegistrations) requires the `FileStorageContainerTypeReg.Selected` user-delegated or app-only permission. When the owning application calls the container type registration API on behalf of a user, the user must be assigned the [SharePoint Embedded Administrator](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) or the [Global Administrator](/entra/identity/role-based-access-control/permissions-reference#global-administrator) roles. When the owning application calls the container type registration API without a user context, it needs to request a token using the [client credentials grant flow](/entra/identity-platform/v2-oauth2-client-creds-grant-flow). > [!NOTE] -> The registration API is **NOT** a Microsoft Graph API but a SharePoint API. This API will be ported to Microsoft Graph in the future. +> The container type registration API is currently in preview and subject to change. To request admin consent from a tenant administrator in the consuming tenant, you may direct them to the [admin consent endpoint](/entra/identity-platform/v2-admin-consent). For the right endpoints on national clouds, see [Microsoft identity platform endpoints on national clouds](/entra/identity-platform/authentication-national-cloud#microsoft-entra-authentication-endpoints): ```http -https://login.microsoftonline.com//adminconsent?client_id= +https://login.microsoftonline.com/{ConsumingTenantId}/v2.0/adminconsent?client_id={OwningAppId}&scope=https://graph.microsoft.com/.default ``` You may configure the admin consent endpoint to fit your needs, including handling errors and successful grants. For more information, see [Admin consent URI](/entra/identity-platform/v2-admin-consent). - ## Container type Permissions The registration API determines what permissions a SharePoint Embedded application can perform against containers and content in containers for the specified container type. @@ -46,8 +42,8 @@ The registration API determines what permissions a SharePoint Embedded applicati | Permission | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | None | Has no permissions to any containers or content of this container type. | -| ReadContent | Can read content of containers of this container type. | -| WriteContent | Can write content to containers for this container type. This permission can't be granted without the ReadContent permission. | +| 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. | @@ -57,53 +53,28 @@ The registration API determines what permissions a SharePoint Embedded applicati | 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. | +| 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. | -## HTTP request - -```http -PUT {RootSiteUrl}/_api/v2.1/storageContainerTypes/{containerTypeId}/applicationPermissions -``` - -> [!NOTE] -> This is NOT a Graph API -> -> `{RootSiteURL}` is the SharePoint URL of the consuming tenant. For example, https://contoso.sharepoint.com. - -### Request body - -In the request body, supply a JSON representation of the container type permissions for the SharePoint Embedded applications. - -### Response - -If successful, this method returns a `200 OK` response code and the container type permissions configured for the SharePoint Embedded applications in the response body. - -| HTTP Code | Description | -| :--------: | ----------- | -| 400 | Bad request. | -| 401 | Request lacks valid authentication credentials. | -| 403 | Provided authentication credentials are valid but insufficient to perform the requested operation. Examples: the calling app isn't the owning app of the container type. | -| 404 | Container type doesn't exist. | - ## Examples ### Register the container type in a consuming tenant with permissions only for the Owning App -Register the container type in the consuming tenant and grant full permissions to the Owning Application (AppId 71392b2f-1765-406e-86af-5907d9bdb2ab) for Delegated and AppOnly calls. +Register the container type `de988700-d700-020e-0a00-0831f3042f00` in the consuming tenant and grant `full` permissions to the owning application `71392b2f-1765-406e-86af-5907d9bdb2ab` for delegated and app-only calls. #### Request -```json -PUT {RootSiteUrl}/_api/v2.1/storageContainerTypes/{containerTypeId}/applicationPermissions +```http +PUT https://graph.microsoft.com/beta/storage/fileStorage/containerTypeRegistrations/de988700-d700-020e-0a00-0831f3042f00 Content-Type: application/json { - "value": [ + "applicationPermissionGrants": [ { "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "delegated": ["full"], - "appOnly": ["full"] + "delegatedPermissions": ["full"], + "applicationPermissions": ["full"] } ] } @@ -112,15 +83,35 @@ Content-Type: application/json #### Response ```json -HTTP/1.1 200 OK -Content-type: application/json +HTTP/1.1 201 Created +Content-Type: application/json { - "value": [ + "@odata.type": "#microsoft.graph.fileStorageContainerTypeRegistration", + "id": "de988700-d700-020e-0a00-0831f3042f00", + "name": "Test Container Type", + "owningAppId": "71392b2f-1765-406e-86af-5907d9bdb2ab", + "billingClassification": "trial", + "billingStatus": "valid", + "registeredDateTime": "08/11/2025", + "expirationDateTime": "08/11/2025", + "etag": "RVRhZw==", + "settings": { + "@odata.type": "microsoft.graph.fileStorageContainerTypeRegistrationSettings", + "sharingCapability": "disabled", + "urlTemplate": "https://app.contoso.com/redirect?tenant={tenant-id}&drive={drive-id}&folder={folder-id}&item={item-id}", + "isDiscoverabilityEnabled": true, + "isSearchEnabled": true, + "isItemVersioningEnabled": true, + "itemMajorVersionLimit": 50, + "maxStoragePerContainerInBytes": 104857600, + "isSharingRestricted": false + }, + "applicationPermissionGrants": [ { "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "delegated": ["full"], - "appOnly": ["full"] + "delegatedPermissions": ["full"], + "applicationPermissions": ["full"] } ] } @@ -128,20 +119,20 @@ Content-type: application/json ### Register the container type in a consuming tenant with permissions for a Guest App -Register the container type in the consuming tenant and grant full permissions to the Owning Application (AppId 71392b2f-1765-406e-86af-5907d9bdb2ab) for Delegated and AppOnly calls. In addition, grant a Guest App (AppId 89ea5c94-7736-4e25-95ad-3fa95f62b6) read and write permissions only for Delegated calls. +Register the container type `de988700-d700-020e-0a00-0831f3042f00` in the consuming tenant and grant full permissions to the owning application `71392b2f-1765-406e-86af-5907d9bdb2ab` for delegated and app-only calls. In addition, grant a guest app `89ea5c94-7736-4e25-95ad-3fa95f62b6` both `read` and `write` permissions only for delegated calls. #### Request -```json -PUT /storagecontainerTypes/{containerTypeId}/applicationPermissions +```http +PUT https://graph.microsoft.com/beta/storage/fileStorage/containerTypeRegistrations/de988700-d700-020e-0a00-0831f3042f00 Content-Type: application/json { - "value": [ + "applicationPermissionGrants": [ { "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "delegated": ["full"], - "appOnly": ["full"] + "delegatedPermissions": ["full"], + "applicationPermissions": ["full"] }, { "appId": "89ea5c94-7736-4e25-95ad-3fa95f62b6", @@ -155,15 +146,35 @@ Content-Type: application/json #### Response ```json -HTTP/1.1 200 OK -Content-type: application/json +HTTP/1.1 201 Created +Content-Type: application/json { - "value": [ + "@odata.type": "#microsoft.graph.fileStorageContainerTypeRegistration", + "id": "de988700-d700-020e-0a00-0831f3042f00", + "name": "Test Container Type", + "owningAppId": "71392b2f-1765-406e-86af-5907d9bdb2ab", + "billingClassification": "trial", + "billingStatus": "valid", + "registeredDateTime": "08/11/2025", + "expirationDateTime": "08/11/2025", + "etag": "RVRhZw==", + "settings": { + "@odata.type": "microsoft.graph.fileStorageContainerTypeRegistrationSettings", + "sharingCapability": "disabled", + "urlTemplate": "https://app.contoso.com/redirect?tenant={tenant-id}&drive={drive-id}&folder={folder-id}&item={item-id}", + "isDiscoverabilityEnabled": true, + "isSearchEnabled": true, + "isItemVersioningEnabled": true, + "itemMajorVersionLimit": 50, + "maxStoragePerContainerInBytes": 104857600, + "isSharingRestricted": false + }, + "applicationPermissionGrants": [ { "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab", - "delegated": ["full"], - "appOnly": ["read"] + "delegatedPermissions": ["full"], + "applicationPermissions": ["full"] }, { "appId": "89ea5c94-7736-4e25-95ad-3fa95f62b6", diff --git a/docs/embedded/getting-started/spembedded-for-vscode.md b/docs/embedded/getting-started/spembedded-for-vscode.md index 343a842f5..6421e9732 100644 --- a/docs/embedded/getting-started/spembedded-for-vscode.md +++ b/docs/embedded/getting-started/spembedded-for-vscode.md @@ -7,7 +7,7 @@ ms.localizationpriority: high # SharePoint Embedded for Visual Studio Code -The SharePoint Embedded Visual Studio Code extension helps developers get started for free with SharePoint Embedded application development. +The SharePoint Embedded Visual Studio Code extension helps developers get started for free with SharePoint Embedded application development. > [!IMPORTANT] > To start building with SharePoint Embedded, you'll need administrative access to a Microsoft 365 tenant. @@ -34,7 +34,7 @@ To use the extension, you must sign in to a Microsoft 365 tenant with an adminis ![authorize and authenticate the extension to your M365 Entra tenant](../images/vsx-images/auth-allow-extension-uri.png) - Review the requested permissions carefully, then select **Accept** on the pop-up window prompting admin consent - + ![review before consenting to the permissions the extension is asking for](../images/vsx-images/n3vsx-grant-admin-consent.png) After successful authorization, select open on the dialog to be redirected to VSCode: @@ -53,7 +53,7 @@ Once signed in, you're prompted to create a [container type with trial configura ![create container type](../images/vsx-images/n5a-name-ct.png) > [!NOTE] -> SharePoint Embedded for Visual Studio Code only supports container types with trial configuration at this time. Other container types with standard or pass-through billing configurations must be created using the SharePoint Online PowerShell Module. +> SharePoint Embedded for Visual Studio Code only supports container types with trial configuration at this time. Other container types with standard or passthrough billing configurations must be created using the SharePoint Online PowerShell Module. ## Create a Microsoft Entra ID App