While developing an SPFx solution and you want to use an API, such as the Microsoft’s one like Graph API or SharePoint or other custom APIs, you have to register the permission needed in Microsoft Entra ID.
First of all you need to know which permissions you need, for example if you want to use an MGT (Microsoft Graph Toolkit) component, say for example the People component, you can see here what are the permissions needed.
If you have to consume a custom API published on Azure there would be a slightly more complex approach to enable the selection of the permissions, in this article I will focus on the Microsoft APIs ones.
Now you have to grant the permissions and there are two ways to achieve this:
- one is by manually grant the permissions (just to be aware of how things work).
- the correct way is to publish the SPPKG and grant the required permissions.
Manually grant the permissions
To grant the permissions, you need to:
- navigate to the azure portal
- open Microsoft Entra ID
- in the left panel click on app registrations
- click on “ All applications “
- select the app named: “ SharePoint Online Client Extensibility Web Application Principal ” which contains all the permissions granted to the SPFx solutions consuming APIs secured with Microsoft Entra ID.
- in the left panel click on “ API permissions “
- Add the permissions you need
To add the permissions there is a plus button with “Add a permission” text:
Clicking on the button a panel will open in the right side of the screen where you can select the permissions that you want to grant:
Once that you have selected the permission group where the permissions you need belong, you have to select if the permissions are delegated or application permissions, for example let’s select the Microsoft Graph permissions:
Sticking with the example of an MGT component we’ll use the “Delegated permissions”, once selected it you have to select the specific permissions that you want to grant:
Search or select the permissions and click the “Add permissions” button.
If no admin consent is required you’re ready to go, otherwise you have to perform another step to effectively grant the permissions, and you need an admin account to perform that.
NB: If you want to avoid your users to explicitly allow the application to access the required permissions you can grant the admin consent to avoid the step to the users.
In the next picture you can see that, for the permission People.Read.All, the column “Admin consent required” is set to “Yes” and that the status is “Not granted for {the application name}”, where the application name is the app registration name for which you’re adding the permissions:
To consent the permissions you have to click on the “Grant admin consent for {the application name}” which will open a dialog asking confirmation of the operation:
Once that you confirm clicking on the “Yes” button the admin consent will be given to all the permissions listed, in my case the result will be the following:
And now you’re all set and can start using the APIs!
The correct way
This approach is a lot easier than the previous and I think it’s the recommended one to go.
Once you know which are the permissions needed from your solution you’ll have to enhance the package-solution.json file adding the array property webApiPermissionRequests to the solution object where you need to add an entry for each permission needed. For example adding the permission to access Microsoft Graph APIs Calendars.Read permission it would be like the following:
{ "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json", "solution": { ...omitted for brevity... "webApiPermissionRequests": [{ "resource": "Microsoft Graph", "scope": "Calendars.Read" }] ...omitted for brevity... }}
Once that you have packaged your solution and are proceeding to the publication in the app catalog, and you have specified the APIs in the package-solution.json, you’ll be met by the following message:
Which tells you that there are API permissions to manage and you can do it right now or proceed later. Keep in mind that until you approve the required permissions the solution won’t work the way it’s supposed to.
Clicking on “ Go to API access page ” will redirect you to the SharePoint admin center API access page where there is a list of the pending requests and the already approved ones.
Selecting the pending request will show two buttons to Approve or Reject the API access:
Clicking “ Approve ” will open a panel where you have an overview of the requesting package and the required permissions:
Once clicked on “ Approve ” you will see that the requested API access will be moved in the “ Approved requests ” list:
Conclusion
I know this can be a lot but I know that you will get used to this and it will be easy to do in the future.
Hope this helps!
Top comments (2)
Great topic to write about!!!
It's something I had in my todo list to completely understand the "API Access" option in the SharePoint Central Administration. Thanks for writing about it and explaining so clear.
"Keep in mind that until you approve the required permissions the solution won’t work the way it’s supposed to."
The API permissions are SHARED across all SPFx solutions that have, and will be, installed. These permissions are not granted per app.
It is certainly a good idea to add error handling for the cases when a user adds your WebPart before the permissions are granted.
But it may also happen that malicious apps won't request any permissions, and will instead use any permissions requested by other solutions.
Why is it important? Malicious apps may steal your data.