Lately I have been busy developing a SharePoint Framework (SPFx) web part which should call an Azure AD secured Web API and display information coming from this Web API. The SharePoint Framework simplifies working with APIs secured with Azure AD through the AadHttpClient.

The development of the SPFx web part was done for a big enterprise customer. In these environments you often don’t get a global administration role in the Azure tenant. I had to request Resource groups, where I could add the needed services. Next to this I had to request an Azure AD App registration (with the default app permissions). So I had no direct influence how this was created for me.

SPFx Web API permission requests

When you want to use the AadHttpClient to call an Azure AD secured Web API, you will need to add Web API permission requests to your package-solution.json file as described here. This documentation only shows how to ask permissions for the Graph API, but for your custom Web API you should add the following request in the package-solution.json file:

  "$schema": "",
  "solution": {
    "name": "blog-client-side-solution",
    "id": "bc4561f2-b2b8-4ddf-a227-747956d2543c",
    "version": "",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "webApiPermissionRequests": [
        "resource": "BlogAppRegistration",
        "scope": "user_impersonation"
  "paths": {
    "zippedPackage": "solution/blog-webpart.sppkg"

The part you need to add is the webApiPermissionRequests part. The resource property is pointing to your App registration name, in my situation ‘BlogAppRegistration’. The scope should be ‘user_impersonation’. The will allow your web part to call the Web API as the currently logged in user.

After deploying my SPFx package to the tenant App catalog and approving the Web API permission requests in the SharePoint Admin Center, I bumped at some error messages in the API management page. After some research I bumped into a really great blog post from fellow MVP Waldek Mastykarz. This blog post describes some common issues when working with SharePoint Framework Web API permissions. Following this blog helped me to get rid of the most issues.

Still one issue…

Yes, I was still having one issue:

An OAuth permission with the scope user_impersonation could not be found.
Error message when trying to approve API permission request for a resource that doesn't exist anymore

Waldek was also mentioning this issue, but his resolution was not the case in my situation. After reading the comments of the blog post, one of the comments from Vincent Biret was heading me in the right direction. He was stating that when the App registration is created with the new preview experience within the Azure portal, the user_impersonation scope is not added by default. Because I had no influence in how the App registration was created I started to dig into this.

App registration

At this point in time the Azure Active Directory blade has two App registration options: legacy and preview. Let’s create a legacy App registration:

When we now go to the preview App registrations and open our newly created App registration and click on the option ‘Expose an API’ you can see there is a user_impersonation scope created automatically:

Now let’s create an App registration in the preview option:

Totally different experience, but an App registration is created. Now let’s go to the ‘Expose an API’ option:

As you can notice the Application ID Uri is missing and there are no scopes available.

Add the user_impersonation scope

So in order to be able to approve the API permission in the SharePoint Admin Center API permissions page and to get rid of the error message we get there, we need to add the user_impersonation scope.

Click the Add a scope button on the ‘Expose an API’. In the right pane a message appears that you first need to supply an Application URI. You can use the supplied URI or change it:

Click ‘Save and continue’.

Supply the information for the user_impersonation scope:

Click ‘Add scope’. The option Who can consent, depends on your situation if users can consent the application or only Admins.


Accessing Web APIs secured by the Azure AD from your SPFx customisation has really been simplified by the SharePoint Framework. Microsoft did a really great job in providing the AadHttpClient, making your job as a developer a lot easier. The Azure portal and its options is growing every day and sometimes using the new (preview) options can give you some surprises. I hope this blog will help you out when you are on your journey creating great customisations using the SharePoint Framework.