Setting up OAuth 2.0 authentication for Business Central endpoints

An integration with a cloud hosted Business Central requires authentication with OAuth 2.0, which can be of either the Service-to-service or User Impersonation type. This guide will you take you through the necessary steps in establishing a User impersonation OAuth for Business Central.  

To add a registration, launch Microsoft Entra, go to "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.

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.

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 provided 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.

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.

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.

The redirect can also be a localhost app though, as shown in the picture below.

After the app registration, API permission and client secret has been added in Microsoft Entra, we must setup the authentication in Dynamicweb.

To do so, go to Settings > Integration > Endpoint Management and click "Add authentication". 

Set the type to OAuth 2.0 - User impersonation. Fill in the fields with the copied values from Microsoft Entra and the URL https://api.businesscentral.dynamics.com.

Clicking "Save" will redirect you to the Business Central login page, where you must enter 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.

A successful login will redirect you back to the "Edit Authentication" page in Dynamicweb where an "Access token received" message should appear. The "Access Token" field should now also show a string.

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. 

In the case that you want to obtain an access token but do not have the credentials for a user in the Business Central enviroment, you can use the Authorization URL  depicted below.

When an authentication method provided with a the necessary fields is saved, a new field with an Authorization URL appears. This URL can be sent to someone who has a Microsoft login for the Business Central enviroment, who can then authenticate on behalf of you to let you obtain the Access Token.

This essentially means that person A configuring the OAuth2.0 in Dynamicweb can have person B with credentials to Business Central authenticate on behalf of them through the Authorization URL.  The authentication will the impersonate person B and this persons permissions in Business Central.