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:

• Register an application in your Azure Active Directory tenant for authenticating API calls against Business Central.
• Grant access for that Azure AD application in Business Central.

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.

• Register an application in your Azure Active Directory tenant for authenticating API calls against Business Central.

Testing with Postman

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

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

Enter the required parameters in postman as follows:

• Web Service/API URL
• Type – Auth 2.0
• Add authorization data to – Request Headers
• Header Prefix – Bearer
• Grant Type – Client Credentials
• Access Token URL - https://login.microsoftonline.com/{TenantID}/oauth2/v2.0/token
• Client ID
• Client Secret
• Scope - https://api.businesscentral.dynamics.com/.default
• Client Authentication – Send client credentials in body

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:

• Web Service/API URL
• Type – Auth 2.0
• Add authorization data to – Request Headers
• Header Prefix – Bearer
• Grant Type – Authorization Code
• Auth URL - https://login.windows.net/{TenantID}oauth2/authorize?resource=https://api.businesscentral.dynamics.com
• Access Token URL - https://login.windows.net/{TenantID}/oauth2/token?resource=https://api.businesscentral.dynamics.com
• Client ID
• Client Secret
• Scope - https://api.businesscentral.dynamics.com/.default
• Client Authentication – Send client credentials in body

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.