Setting up SharePoint Embedded can be a bit confusing. Microsoft hasn't updated the documentation properly because it's still in Feature Preview.
That's where this article comes in handy. This 4-step guide is based on my experience and the current existing documentation. It helped me build my first application using SharePoint Embedded.
Follow these steps, and you'll be on your way to developing your solution using SharePoint Embedded features:
- Obtain a Microsoft 365 Tenant Admin Account
- Configure a new Entra ID Application
- Create a New Container Type
- Register the Container Type with the consuming tenant
Want to learn more about SharePoint Embedded? I've written more articles explaining what it is and how you can leverage its features to enhance your content management. Check them out here: https://intranetfromthetrenches.substack.com/t/sharepoint-embedded
Step 1 - Obtain a Microsoft 365 Tenant Admin Account
To create a new Container Type, you need the admin tenant account for Microsoft 365. Reach out to your IT team or the individuals managing your Microsoft 365 account to help you out.
Step 2 - Configure a new Entra ID Application
Step 2.1 - Create a new application
Here's how to create a new Entra ID (formerly known as Azure AD) application. It allows to authenticate and obtain the necessary permissions for accessing Microsoft Graph:
- Sign in to the Microsoft Entra admin center using the Microsoft 365 tenant admin account.
- Navigate to the Identity section on the left and select Applications. Then, click on App registrations and choose the New registration button at the top.
- On the Register an application page,
- Provide a unique name for the application.
- Under the Redirect URI (optional) section, select Single-page application from the Add a platform dropdown menu. Then, enter
http://localhost:3000
in the textbox.
- Click on the Register button at the bottom left corner of the page.
Step 2.2 - Setting the API Permissions for the application
This step is essential for configuring the permissions for the app. It will allow the creation and access to the Container Type and its containers. Likewise, for any other required permissions, make sure they are added accordingly.
Ensure to include the **Files.ReadWrite.All* permission if you plan to work with files before going with these steps.*
Here's how to proceed:
- Navigate to your application page.
- Click on the Manifest option under the Manage section in the left-hand side menu.
- Locate the property requiredResourceAccess. Under the Microsoft Graph group, with resourceAppId equal to 00000003-0000-0000-c000-000000000000, add the following items to allow application and delegated permissions for the FileStorageContainer.Selected claim.
{
"resourceAppId": "00000003-0000-0000-c000-000000000000",
"resourceAccess": [
{
"id": "085ca537-6565-41c2-aca7-db852babc212",
"type": "Scope"
},
{
"id": "40dc41bc-0f7e-42ff-89bd-d9516947e474",
"type": "Role"
}
]
}
- Next, add a new resourceAppId for SharePoint Online, which is 00000003-0000-0ff1-ce00-000000000000. Then, add the specified permissions. They enable application and delegated permissions for the Container.Selected claim.
{
"resourceAppId": "00000003-0000-0ff1-ce00-000000000000",
"resourceAccess": [
{
"id": "4d114b1a-3649-4764-9dfb-be1e236ff371",
"type": "Scope"
},
{
"id": "19766c1b-905b-43af-8756-06526ab42875",
"type": "Role"
}
]
}
- Confirm you have the same configuration as the following screenshot. Then, click on the Save button at the top,
- Click on API Permissions under the Manage section in the left-hand side menu.
- Scroll down to find the link to the Enterprise applications option at the bottom of the page, then click on it.
- Click the Grant admin consent button in the middle of the page to approve the permissions added in the manifest.
If you find the need to add more permissions after completing these steps, proceed as usual to add them. Afterwards, ensure that the SharePoint Embedded permissions are retained. If not, repeat these steps.
Step 2.3 - Creating a Client Secret
This step is optional but I encourage doing it. It will save you time when developing your applications. Here are the steps:
- Navigate to your application page.
- Click on Certificates and secrets under the Manage section on the left-hand side menu.
- On the Certificates & Secrets page, select the Client Secrets tab and then click on the New client secret button.
- Provide a description, and choose an expiration duration. Then click on the Add button at the bottom of the page.
Once the secret is created, it will be displayed only once. Be sure to copy it as the client secret into your local text file for later use in this module. Failure to do so will require generating a new secret and removing the previous one.
Step 2.4 - Create a self-signed certificate
To register the new Container Type in the consumer tenant, a certificate is necessary as part of the registration process.
Follow these steps for creating and configuring it in the application:
- Download the PowerShell script Create-OpenSslScript.ps1 from my Gist repository.
- Execute the script to generate the openssl script. It serves for creating the certificate public and private keys.
> $Path = "Set the location where public and private key files will be generated"
> $Name = "Set the name for the public and private key files"
> $OutFile = "Set the path and name for the openssl script to be generated"
> Create-OpenSslScript.ps1 -Path $Path -Name $Name -OutFile $OutFile
- You should have a new script similar to the following.
- Run the script using the openssl tool. In my case, it is located in my git installation folder, %PROGRAMFILES%\Git\mingw64\bin.
- Navigate to your application page.
- Click on Certificates and secrets under the Manage section on the left-hand side menu.
- On the Certificates & Secrets page, select the Certificates tab and then click on the Upload certificate button.
- Choose the previously generated *.crt file, then click on the Add button at the bottom of the page.
- Copy the Thumbprint displayed after uploading the certificate.
Step 3 - Create a New Container Type
This step involves generating a new Container Type, which can be done using the SharePoint Online PowerShell module.
Here's what you need to do:
- Obtain the SharePoint Online central administration URL. Something similar to
https://<your tenant name>-admin.sharepoint.com
. - Retrieve the application ID from the one created in Step 2.1.
- From your Azure tenant, open the Azure Subscription service. Locate the one where SharePoint Embedded is configured. Take note of the Id of the subscription service.
- From your Azure tenant, get the resource group name where SharePoint Embedded costs will be managed.
- Identify the region of the previous resource group.
- Download the following script, Create-SPOContainerType.ps1. Then, execute it, providing all the necessary data for creating a trial container.
> .\Create-SPOContainerType.ps1 -SpoAdminUrl "https://<your tenant name>-admin.sharepoint.com" `
-ContainerTypeName "MyFirstsContainerType" `
-EntraAppId "<your Entra ID application id>" `
-AzureSubscriptionId "<your Azure Subscription id>" `
-ResourceGroupName "<your Resource Group name>" `
-ResourceGroupRegion "<your Resource Group region>"
The PowerShell script will then display the details for your new Container Type. Be sure to copy the ContainerTypeId for future reference.
Container Type ID:
===========================================================
ContainerTypeId : 9ae8f98e-29fd-45a4-b6b6-5a514a7ffd50
ContainerTypeName : MyFirstsContainerType
OwningApplicationId : 520e6e65-1143-4c87-a7d3-baf242915dbb
Classification : Trial
AzureSubscriptionId : 7cf6d692-d6e1-4067-89e2-eef1e49b7a64
ResourceGroup :
Region :
Step 4 - Register the Container Type with the Consumer Tenant
The final step is to register the Container Type in the consumer tenant. I've prepared a PowerShell script to handle all the necessary operations.
Here's what you need to provide to the script:
- Obtain the application ID from the one created in Step 2.1.
- Retrieve the Container Type ID from Step 3.
- Find the location of the PEM file generated in Step 2.4.
- Obtain the certificate thumbprint obtained in Step 2.4.
- Obtain the consumer tenant ID and URL.
Now, download the following script, Register-SPOContainerType.ps1. Then, execute it, providing all the data.
> .\Register-SPOContainerType.ps1 -ClientId "<your Entra ID application id>" `
-ContainerTypeId "<your Container Type id>" `
-PemCertificationFilePath "<your local path to the PEM file>" `
-ConsumerTenantId "<your tenant id>" `
-ConsumerTenantUrl "https://<your tenant name>.sharepoint.com" `
-Thumbprint "<your Entra ID certificate thumbprint>"
After running the script, you'll have an app ready for managing and accessing the SharePoint Embedded containers.
Final thoughts
By following these steps, you can set up your SharePoint Embedded application for the first time. As you've seen, it's quite straightforward.
Have you something in mind to start developing? Share your thoughts below.
If you find this information useful, feel free to share it with your colleagues.
References
- Create-OpenSslScript.ps1: https://gist.github.com/jaloplo/724f28db17fab829457528fe8d5ad5ac
- Create-SPOContainerType.ps1: https://gist.github.com/jaloplo/2d99c237741a10e121462b86ba3cfb2a#file-create-spocontainertype-ps1
- Register-SPOContainerType.ps1: https://gist.github.com/jaloplo/6612a9842202fcf00099f41437086aad#file-register-spocontainertype-ps1
- SharePoint Embedded Container Types: https://github.com/SharePoint/sp-dev-docs/blob/main/docs/embedded/concepts/app-concepts/containertypes.md
- Setup and configure the SharePoint Embedded environment and web app project: https://learn.microsoft.com/en-us/training/modules/sharepoint-embedded-create-app/3-exercise-set-up-configure-sharepoint-embedded
- SharePoint-Embedded-Samples: https://github.com/microsoft/SharePoint-Embedded-Samples
- Microsoft identity platform and the OAuth 2.0 client credentials flow: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow
- Microsoft identity platform application authentication certificate credentials: https://learn.microsoft.com/en-us/entra/identity-platform/certificate-credentials
Top comments (7)
Nice work, it's hard to find content about Embedded, I can't wait to see for some aplications! Now, for some environment configs I suggest the use of VSCode SharePoint Embedded extension
Thanks for your comment @jpdosher. I've written 4 more articles about SharePoint Embedded. You can find them in my blog.
I also have a newsletter that lists SharePoint and Power Platform articles published in Dev.to. Here you can find the series.
Glad to chat about SharePoint Embedded if you want.
Thanks for the reply. For now I'll be focusing in create a POC for documents sharing... lets what happens
Did you replied the microsfot learn project? I got stuck in the back-end (I think) while trying to "npm run start", something like this:
Errors Files
1 node_modules/@types/node/module.d.ts:216
1 node_modules/@types/react/ts5.0/index.d.ts:3308
2 ../../../../node_modules/@types/requirejs/index.d.ts:38
178 ../../../../../node_modules/@types/react/ts5.0/index.d.ts:3308
ERROR: "build:backend" exited with 2.
I cleaned my dev environment (deleted node_modules and reinstalled) -I will try in my windows workstation now (using mac)
Put me more in context. If you like we can talk on LinkedIn or Twitter, whatever you prefer to be agile.
Ok, I request conection in LinkedIn. Again, tks for your time !!!
I'm replicating the learn tutorial and Andrew Cornell (from voitanos) tutorials. I got a bunch of errors while trying to run server-side api.
But now, I replicated in my windows workstation and works (for sure that it was depedencies overwriting)! Im at the midle of the implementantion (i've already configure azure Entra app)
Take care when adding API permissions. If you need to add an additional permision out of the SharePoint Embedded ones, check that they remain in the manifest file before testing your app.