REST API integration in S2S (Service to Service)
REST API integration in S2S (Service to Service)
The consumption of the Business Central REST APIs via OAuth2 authentication has as a prerequisite an AAD user who has been associated with a paid license of Business Central.
With Business Central 2021 release wave 1, release 18.3 or later, Microsoft introduces S2S authentication: https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication S2S authentication uses the Client Credentials OAuth 2.0 flow, which enables access to resources through the use of an application identity: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow S2S authentication therefore does not use a set of ‘UserID / Password’ credentials but an ‘Application (Client) ID’ (i.e. a system user) and a Client Secret (strong password) and does not require an outlay of additional BC licenses.
The prerequisites for configuring the integration are:
- Access to a Business Central environment
- Access to the AAD subscription used by Dynamics 365 Business Central instances.
The main S2S configuration steps include:
- Registration of an application in the Azure Active Directory tenant dedicated to the authentication of API calls to Business Central.
- The creation and assignment of the correct access rights of the Azure AD application in Business Central.
“HOW-TO” STEPS
- Log in to the Azure portal (https://portal.azure.com) and create a new ‘App Registration’.
- Assign a name to the App, set the Supported Account Types to Single Tenant and the Redirect URI to: https://businesscentral.dynamics.com/OAuthLanding.htm (case sensitive)
- Click ‘Register’ and copy the Application (client) ID generated after registration.
- Click on API permissions 🡪 Add a permission.
From the list of Microsoft APIs, select Dynamics 365 Business Central.
Set the type of permission on the Application permissions panel
- Select the API.ReadWrite.All permission.
- Access to data is limited by the permissions that will subsequently be assigned to this application account in Business Central.
- On API permissions, confirm (Yes) the Grant admin consent for the API permissions just issued.
- The Grant (which triggers the automatic creation of a Service Principal) can only be provided by users who belong to the Global Administrator, Application Administrator or Cloud Application Administrator role.
- Click on the Certificates & Secrets menu and then click on New client secret. Select the desired expiration time (maximum 24 months) and click on Add.
- Copy the information relating to the generated Client secret, in particular its Value
- Click on the Authentication menu and select both Access Tokens and ID Tokens
- In Business Central on the Azure Active Directory Applications setup page, add a new record. Set the Client Id for the Azure application created above. 7
- Configure the permissions related to the application.
EXAMPLE
The following example shows how to invoke the ‘companies’ automation endpoint to recover the list of companies contained in the Business Central environment through the Postman application.
The communication sequence consists of 4 frames:
- #1 – Get access Token – Request
- #2 – Get access Token – Response
- #3 – Use Access Token to Call API – Request
- #4 – Use Access Token to Call API – Response
The example 4 frames are shown below
#1 – Get access Token – Request (chiamata POST per la generazione del token OAuth2.0):
POST:
https://login.microsoftonline.com/<TenantId>/oauth2/v2.0/token
HEADER:
Content-Type: application/x-www-form-urlencoded
BODY:
grant_type=client_credentials
scope=https://api.businesscentral.dynamics.com/.default
client_id=<client ID>
client_secret=<client secret>
#2 – Get access Token – Response
(the acquired access token is used for the next call to BC)
#3 – Use Access Token to Call API – Request
The GET invocation of the automation endpoint ‘companies’ follows the following syntax: GET https://api.businesscentral.dynamics.com/v2.0/ Percorsienvironment name} /api/microsoft/automation/2.0/companies
#4 – Use Access Token to Call API – Response
The endpoint response reports the presence of only one company: ‘CRONUS IT’
