Business Central OAuth User impersonation setup guide

How to add an OAuth user impersonation authentication between DynamicWeb and Business Central

Setting up OAuth 2.0 authentication for Business Central endpoints

To integrate DynamicWeb with your cloud hosted Business Central, you will need a valid OAuth authentication of either the Service-to-Service type or the User impersonation type. This guide will take you trough the steps required to establish a user impersonation authentication.

Creating a registration in Microsoft Entra

The first step in adding User impersonation authentication is to add a registration in Microsoft Entra. To add a registration, launch Microsoft Entra, go to Applications > App registrations and click "New registration".

In here, copy the "Application (client) ID" and the "Directory (tenant) ID" . The ID's will be used later in the setup process.

Adding an API permission

Go to API permissions and click "add permission". Select the "Dynamics 365 Business Central" API, choose "Delegated permissions".

Select "user_impersonation" in the checkbox marked on the screenshot and finish by clicking "Add permission" in the bottom left corner.

The permissions tied to the access token in the end will thus depend on the permissions of the impersonated Business Central user.

User permissions

The exact permissions tied to an OAuth User impersonation authentication is defined by the Business Central User Permissions Sets configured for the user to whom the credentials belong.

Which permissions are relevant and needed are of course highly dependent on the scenario and on your organization. To see the permissions of a Business Central user, open your BC application, search for users and open the user card of the particular user. Here the User Group Memberships and User Permission Sets are listed and (if the user is permitted to do so) configured.

A good rule of thumb is that membership of the D365 BUS PREMIUM user group allows a user to read and write most of what is needed in any integration scenario.

Adding a Client secret

Next, go to "Certificates & secrets" to add a client secret.

Make sure to copy the value (not to be confused with the ID) as it will never be shown again and is needed later in the process.

Platform configuration

Next, add a redirect URI in Manage > Authentication > Add a platform and choose "Web". Entra will then ask you to enter the redirect URI of the application.

The redirect URI needs to be in the following format with your host website in the URI instead of "yourwebsite.com".

https://yourwebsite.com/Admin/Public/Module/EndpointManagement/EndpointAuthorization.aspx

Please notice that the HTTPS protocol is required for redirect URI's in Microsoft Entra - with the exception of using a localhost redirect URI.

Adding the authentication in DynamicWeb

After the app registration, API permission and client secret has been added in Microsoft Entra, you can use the authentication in DynamicWeb either in an endpoint collection or directly on a stand alone request.

To add the authentication to a collection, go to Integration > Connections and add a new endpoint collection.

Set the authentication type to OAuth 2.0 - User impersonation. Fill in the Directory Id, Application Id and Client secret fields with the copied values from Microsoft Entra and insert the URL https://api.businesscentral.dynamics.com.

Clicking Save will bring forth the Get Token button, that redirects you to a Microsoft log-in screen, from where you must login with the credentials of the Business Central user, you wish to impersonate.

In some cases, the browser might block the pop-up with the Business Central login page. Make sure to allow pop-ups from DynamicWeb if that is the case.

After successful login, the "Access Token" field should now show an encrypted version of the access token.

Clicking "Save and close" should now enable you to interact with Business Central endpoints using the established OAuth 2.0 authentication.

Once the access token expires the OAuth 2.0 library will make a silent token refresh request so it can be obtained without a login.