Dynamics CRM OAuth User impersonation setup guide

How to add an OAuth user impersonation authentication between DynamicWeb and Dynamics CRM

Setting up OAuth 2.0 authentication for Business Central endpoints

To integrate DynamicWeb with your Dynamics CRM instance, 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.

Adjusting the manifest

To allow the OAuth token to flow between CRM and DynamicWeb, we need to adjust a couple of values inside the JSON manifest of the app.

Click Manifest in the left navigation pane, set both the "oauth2AllowIdTokenImplicitFlow" and "oauth2AllowImplicitFlow" values to true, and save the updated manifest.

Having the "signInAudience" parameter set to "AzureADMultipleOrgs" in the manifest may be relevant for preventing issues with permissions for certain users depending on how the CRM application is configured.

Adding an API permission

Go to API permissions in the left navigation pane and click Add a permission. Select the Dynamics ERP API.

In the following menu, choose Delegated permissions and check the "user_impersonation" checkbox. The permissions tied to the access token in the end will thus depend on the permissions of the impersonated CRM user.

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". Microsoft 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 Entra - with the exception of using a localhost redirect URI.

Check both the** "Access tokens"** and "ID tokens" checkboxes under Implicit grant and hybrid flows

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.