SharePoint Framework (SPFx): An introduction to Isolated webpart
Introduction
After the introduction of SPFx version 1.6.0, there were several improvements which were made, out of which, one was the easy way of consuming Graph API or Custom API Secured with Azure AD. But there was a downside of it as well. It was that any script running in the tenant gets access to the API. This has been addressed in SPFx version 1.7.0 by introducing domain isolated webpart.
Purpose
Purpose of this article is to explain how an existing SPFx webpart can be upgraded from version 1.6.0 to 1.7.0 & how to isolate a webpart to run in a different domain so that API can be exposed in a most secured way inside the tenant.
Theory
For consuming API secured with Azure AD, Azure AD Application is registered along with the permission required to access specific resource. It also has a reply URL which its send response along with access token. In earlier versions (before SPFx 1.6.0 release), one has to specify URL of the pages where SPFx webpart will be added in reply URL section. There were two major disadvantages of this method, one was all webpart on the page will get access to those API & secondly, it is a tedious process to add URL of all pages in the reply URLs parameter. Not all admin will have idea upfront on where these webparts will be added inside the tenant.
These challenges have been addressed in SPFx v 1.7.0. The idea is to run the webpart in an iframe i.e. to run it in different domain so that only this domain receives the access token and resources.
Architectural Flow
Below is a diagrammatic representation of SharePoint isolated web part deployment and authentication process.
Below are the process flow which explains the pictorial process flow.
- Once the SPFx webpart package, i.e. sppkg package is successfully uploaded in the app catalog, a request for the specific resource required for SPFx webpart to run is setup in API Management page.
2 & 3) If Tenant Admin approves the request, a specific application is created\registered in Azure Active directory with all the configuration required to pass the access token & other resources to SPFx webpart.
- The SPFx webpart once added in any page inside the tenant can then request access token and consume API secured with Azure active directory.
Implementation of Domain isolated webpart
In this article, we will take an existing webpart which is build in SPFx version 1.6.0 and upgrade it to SPFx version 1.7.0 so that we can utilize the new functionality of domain isolation. Further, we will make necessary changes in the file and check how the domain isolation has been performed.
Upgrade SPFx solution from SPFx 1.6.x to 1.7.0 version
This section can be skipped if the web part is already build in version 1.7.0. Also note that there are multiple ways of upgrading a SPFx solution, this section explains one of them.
Here, we are downloading an existing a webpart solution from technet gallery. Link here
Unzip the package and run below code in windows powershell by navigating to the path where solution is unzipped. Open the solution in Visual Studio code.
code .Open the package.json file and change the version related to SPFx to 1.7.0 since this webpart is build with no framework there isn't any react js file referred as dependencies. If there are react components defined in the dependencies the below changes need to be done.
- modify the react & react-dom to version 16.3.2
- modify the @types/react to v16.4.2
- modify the @types/react-dom package to v16.0.5
Since this package is not built yet, there is no Node Modules folder. If there is other solution that have been taken (not the one in this example), then node_modules and lock files package-lock.json need to be removed if present.
Open package-solution.json file and add additional key "isDomainIsolated" and set it to true. This denotes that the webpart should render in an iframe.
Run the below code to run the package manager installation.
npm i
We will deploy this solution in a similar way it was done in the following article under section package the solution and upload to appcatalog
Examining the domain isolated webpart
After successfully uploading the package to appcatalog, go to SharePoint Admin Center (https://<<yourdomain>>-admin.sharepoint.com), click on the "Try the Preview" if it is a classic mode. Navigate to API Management. Register the Application by approving the requested resource.
Once the tenant admin approves the request, a specific Application is created \ registered in the Azure active directory which acquires the required permission to access resource.
This can be verified by navigating to Azure active directory admin center. (admin center should be in modern view) & Click on Azure Active Directory.
Click on Azure active directory -> App registrations -> SharePoint Online Client Extensibility Web Application Prinicple (Click on View all Application if it appears)
An Application with a name similar to SPFx solution name should appear.
**Along with the creation process, Reply URLs are configured for application. These are the domain separated URLs which are then pointed out as source for API transaction for passing access token and other related resources between SPFx webpart and Azure AD secured API.
**
This can be verified by opening the application registration created for our application and under settings, we can see the reply URLs in the adjacent blades.
The isolated domain created in this case is https://ramakrishnandev-app7B62F30B81FC4C8583B50740E920EF9B.sharepoint.com & the part highlighted in bold in the url is same as the Product ID of SPFx solution that was uploaded in appcatalog.
After adding this webpart to one of the site pages, we can see that it is actually rendering inside an iframe.
Graph API called in this case also points to the domain separated location. Refer the screen shot below
Conclusion
Thus, in this article, we saw how to create a isolated webpart and how access token can be passed securely to a specific SPFx webpart rather than exposing it to all the webpart on the page. It also shows how Azure AD secured API can be exposed in the most secured way.