Common issues when working with SharePoint Framework API permissions

SharePoint Framework API permissions significantly simplify connecting to APIs securing with Azure AD. There are however a few things that you need to watch out for or you will be stuck.

Easily connect to APIs secured with Azure AD

Authentication is hard. Security is necessary, to ensure that your organization's data stays safe. But at the same time, it makes you spend more time than necessary trying to connect to your organization's APIs. You have to decide which OAuth flow you need, what kind of Azure AD application to create, how to securely store the access token, not to mention to ensure that the whole setup will work with multiple web parts on the same page requesting access tokens simultaneously.

For building SharePoint Framework solutions, Microsoft simplifies working with APIs secured with Azure AD through the AadHttpClient. The AadHttpClient abstracts away obtaining and managing OAuth access tokens allowing you to focus on building your solution. It just works.

Common pitfalls when working connecting to APIs secured with Azure AD in SharePoint Framework solutions

The AadHttpClient is invaluable and using it saves you a lot of time. Still, there are a number of things that you should be aware of, not to get stuck when using it in your solutions. Here are a few of them.

Unknown Azure AD application

After loading the page, one of the web parts or extensions shows an error similar to the following:

AADSTS50001: The application named af71d8fc-bcb5-4e89-9415-71c8a1f1f585 was not found in the tenant named d4a29dc3-64ad-425a-971e-0acdea1bfa30.  This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant.  You might have sent your authentication request to the wrong tenant.
Azure AD error AADSTS50001 displayed by a SharePoint Framework web part

This error occurs when your API is secured with an Azure AD application registered in a different Azure AD than the one used by your Office 365 tenant, while this application hasn't been consented by the administrator to be used in your organization.

To fix this issue, complete the consent flow, by in the web browser navigating to the API URL, signing in with your Office 365 account and consenting to the usage of the API in your organization. You can confirm that the administrator has consented to using the application, by in the Azure Portal, navigating to Azure AD Enterprise applications.

Azure AD application used to secure the API listed among Enterprise applications

Insufficient permissions to view the page

When trying to consent the usage of an API secured with Azure AD in your organization, you get the following error:

You do not have permission to view this directory or page.
The 'You do not have permission to view this directory or page.' displayed in the web browser

This is most likely caused by the fact, that an Azure AD application with the same App ID URI is already registered in your organization. You should be able to confirm this by navigating in the Azure Portal to Azure AD Enterprise applications.

Azure AD application used to secure the API listed among Enterprise applications

To fix this issue, either change the App ID URI of the Azure AD application used to secure your API or delete the old application from the Azure AD used by your Office 365 tenant.

Invalid Issuer URL

When trying to consent to the usage of the API in your tenant, you get the following error:

AADSTS50020: User account 'admin@contoso.onmicrosoft.com' from identity provider 'https://sts.windows.net/d4a49dc3-629d-4d5a-972e-0ac1e3dbfa30/' does not exist in tenant 'Contoso Dev' and cannot access the application 'af71d8fc-bcb5-4e39-9425-71c8a2f1d585' in that tenant. The account needs to be added as an external user in the tenant first. Sign out and sign in again with a different Azure Active Directory user account.
Azure AD error AADSTS50020 when trying to consent the usage of an Azure AD application

When securing the API using Azure AD, most likely you used the Express mode to create the Azure AD application. As a result, Azure AD configured the Issuer URL of this application to the Azure AD where the application is registered and which is different than the Azure AD used by your Office 365 tenant. As a result, Azure AD doesn't allow the application to be used by accounts from other Azure ADs.

To fix this issue, in the API authentication configuration, change the Azure AD configuration mode to Advanced, and clear the Issuer URL.

Empty Issuer URL property for an Azure AD application

Single-tenant Azure AD application

When trying to consent to the usage of the API in your tenant, you get the following error:

AADSTS700016: Application with identifier 'af71d8fc-bcb5-5e89-9425-71c8a1f1f585' was not found in the directory 'd4a79dc3-629d-4f5a-87be-0ac0eadbfa30'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant
Azure AD error AADSTS700016 displayed in the browser

The IDs will of course be different and specific to your Azure AD and application. This error is being caused by you trying to use the API in the context of your Office 365 tenant, while the Azure AD application used to secured the API is registered as a single-tenant application in a different Azure AD than the one used by Office 365.

To fix this issue, change the application to be multi-tenanted in its registration settings.

Azure AD application configured to be multi-tenanted

Service principal not found

When trying to grant API permission or approve API permission request, you get the following error:

A service principal with the name contoso-api could not be found.

or this one:

Specified clientId was not found.
The 'Specified clientId not found' error displayed on the API management page

You're trying to grant API permissions to an Azure AD application that is registered in a different Azure AD than the one used by your Office 365 tenant, while the administrator hasn't consented to using the application yet.

To fix this issue, complete the consent flow, by in the web browser navigating to the API URL, signing in with your Office 365 account and consenting to the usage of the API in your organization.

API permission listed among the tenant-wide granted permissions

Scope user_impersonation not found

When trying to grant API permissions, you get the following error:

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

This error is often caused when trying to grant permissions for an Azure AD application registered in a different Azure AD and which has been deleted. Unfortunately, deleting the Azure AD application in its original AD doesn't remove the existing references, so while the Azure AD used by your Office 365 tenant would still be showing the Azure AD application in its list of applications, you will not be able to grant it any permissions.

To fix this issue, create a new Azure AD application and use it to secure your API.

API permission listed among the tenant-wide granted permissions

API permissions not granted

After loading the page, one of the web parts or extensions shows an error similar to the following:

AADSTS65001: The user or administrator has not consented to use the application with ID 'e6029062-a9cb-461d-924d-c3ab57a9c449' named 'SharePoint Online Client Extensibility Web Application Principal'. Send an interactive authorization request for this user and resource.
Azure AD error AADSTS65001 displayed by a SharePoint Framework web part

A common cause for this error is caused by the API permissions required by the component not being granted in the API management page. You should double check which permissions and to which APIs your component requires, and if they are granted in the API management.

API permission listed among the tenant-wide granted permissions

Insufficient CORS configuration

After loading the page, one of your components shows an error similar to the following:

NetworkError when attempting to fetch resource.
SharePoint Framework web part showing the 'NetworkError when attempting to fetch resource.' error

This error is caused by insufficient CORS configuration on the API that you're calling. Because your component is communicating with the API client-side, the API must specify the domain of your SharePoint tenant in its CORS configuration or the request will be blocked by the web browser with the aforementioned error.

To fix the issue, navigate to the CORS settings of your Azure Function and add your SharePoint Online domain to the list of approved origins.

Azure Function CORS configuration

Summary

SharePoint Framework API permissions significantly simplify connecting to APIs securing with Azure AD. To successfully secure an API using Azure AD and communicate with it from a SharePoint Framework solution, you need to be aware of a number of settings or you will be stuck trying to decipher the cryptic error messages.

Comments

comments powered by Disqus