By Natalie Williams on Thursday, 25 August 2022
Category: Dynamics 365

Dynamics 365 Business Central OAuth2 Protocol

Many API integrations with Business Central SaaS are using the web service access key for basic authentication. But the 2022 release wave 1 (version 20) will remove this feature in favour of OAuth2. Since 2020 release wave 2 (version 17) a warning is displayed on the User card that the web service access key will be deprecated. Version 18.3 has been officially released and is available for the SaaS platform. So, you can test this new authentication method now. It will soon be the only authentication method available as access with Web Service key is deprecated. This is only for SaaS and NOT for on-premises. For on-prem environments, the web service access key will still be an option.  

There are two ways to access Web Services/APIs in Business Central.

1. OAuth2 protocol with Service-to-Service (S2S) Authentication – This method uses application/service account to authenticate the web service/API request. Service-to-Service (S2S) authentication is suited for scenarios where integrations are required to run without any user interaction. Operation permissions will be determined by service-to-service setup.

To enable OAuth2 protocol with service-to-service authentication, you'll have to do the Following steps:

Please find step-by-step official documentation here - https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication

Request Flow:

​2. OAuth2 protocol WITHOUT Service-to-Service (S2S) Authentication – It uses AD account instead of application/service account to authenticate the web service/API request. Therefore, AD account will be used to perform operations (create, read, modify, and delete) in Business Central and user permissions apply.


Please find step-by-step official documentation here - https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app

Request Flow:

Testing with Postman

Please see the parameters listed below which are required for OAuth2.

Parameter Value
Client ID The Application (client) ID that was assigned during the app registration in Azure AD. If you didn’t copy it, then you can always find it in the app overview in the Azure Portal.
Secret The secret that was created during the app registration in Azure AD. If you didn’t copy it, then you need to create a new application as there is no way to access the previously created secret.
Scope https://api.businesscentral.dynamics.com/.default

This points to the permission that you selected during registration: API.ReadWrite.All or Automation.ReadWrite.All
Tenant ID The tenant id is the GUID or domain name of the Azure AD of the Business Central environment that the application wants to call. It's the Azure AD in which the service principal was created when the application was granted consent.

It’s possible to use a GUID or to use the primary domain name of the Azure AD.
Environment The name of the Business Central environment that the application wants to access, e.g., Production, Sandbox, etc. This is not a parameter for getting the OAuth access token, but it must be part of the API URL.


OAuth2 protocol WITH Service-to-Service (S2S) Authentication

Enter the required parameters in postman as follows:

Step 1 – Click Get New Access Token button. It will use application account to authenticate and authorize the request. It will also send the access token back to postman.

Step 2 – Send web service request (GET, POST) with new access token and check the response from web service call.  

OAuth2 protocol WITHOUT Service-to-Service (S2S) Authentication

Enter the required parameters in postman as follows:

Step 1 – Click Get New Access Token button. It will open a new window to login with AD user account.  

Step 2 – Login with AD user account which will authenticate the user and authorize the request. It will also send the access token back to postman.  

Step 3 – Send web service request (GET, POST) with new access token and check the response from web service call.  

Related Posts