Using Service-to-Service (S2S) Authentication

Service-to-Service (S2S) authentication is suited for scenarios where integrations are required to run without any user interaction. S2S authentication uses the Client Credentials OAuth 2.0 Flow. This flow enables you to access resources by using the identity of an application.

In contrast, OAuth delegate flows, like authorization code, implicit grant flow and resource owner password credentials can be configured to require multifactor authentication (MFA). This configuration prevents integration from running unattended, because MFA is required to acquire the access token from Microsoft Entra ID.

Feature availability

The following table describes in which versions S2S authentication was made available for online or on-premises environments.

Main usage scenarios

Two main scenarios are enabled with S2S authentication:

1. Company setup using automation API

   Automation APIs provide capability for automating company setup through APIs. The automation APIs are used to hydrate tenants, that is, to bring them to an initial state.

   The D365 Automation entitlements give access to APIs in the /api/microsoft/automation route by using the OAuth client credentials flow. An application token with the Automation.ReadWrite.All scope is needed for accessing Business Central Automation APIs.

2. External user and non-interactive user access to APIs and web services.

   S2S authentication enables both external user and non-interactive user access to Business Central online. Refer to license guide for scenarios and usage. An application token with the API.ReadWrite.All scope is needed for accessing Business Central APIs and web services.

Business Central on-premises prerequisite

Business Central on-premises must be configured for Microsoft Entra authentication with OpenID Connect.

For more information, go to Configure Microsoft Entra authentication with OpenID Connect.

Set up service-to-service authentication

To set up service-to-service authentication, you'll have to do two things:

• Register an application in your Microsoft Entra tenant for authenticating API calls against Business Central.

• Grant access for that application in Business Central.

These tasks are described in the sections that follow.

Task 1: Register a Microsoft Entra application for authentication to Business Central

Complete these steps to register an application in your Microsoft Entra tenant for service-to-service authentication.

1. Sign in to the Azure portal.

2. Register an application for Business Central in Microsoft Entra tenant.

   Follow the general guidelines at Register your application with your Microsoft Entra tenant.

   When you add an application to a Microsoft Entra tenant, you must specify the following information:

   Setting	Description
   Name	Specify a unique name for your application.
   Supported account types	Select either Accounts in this organizational directory only (Microsoft only - Single tenant) or Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant).
   Redirect URI	(optional) This setting is only required if you want to use the Business Central web client to grant consent to the API (see task 2). Otherwise, you can grant consent using the Azure portal. To specify the redirect URL, set the first box to Web to specify a web application. Then, enter the URL for your Business Central on-premises browser client, followed by OAuthLanding.htm, for example: https://MyServer/BC240/OAuthLanding.htm or https://cronus.onmicrosoft.com/BC240/OAuthLanding.htm. This file is used to manage the exchange of data between Business Central and other services through Microsoft Entra ID. Important: The URL must match the URL of Web client, as it appears in the browser address. For example, even though the actual URL might be https://MyServer:443/BC240/OAuthLanding.htm, the browser typically removes the port number :443.

   When completed, an Overview displays in the portal for the new application.

   Note

   Copy the Application (client) ID of the registered application. You'll need this later. You can get this value from the Overview page.

3. Create a client secret for the registered application as follows:

   1. Select Certificates & secrets > New client secret.
   2. Add a description, select a duration, and select Add.

   Note

   Copy the secret's value for use in your client application code. This secret value is never displayed again after you leave this page.

   For the latest guidelines about adding client secrets in Microsoft Entra ID, see Add credentials in the Azure documentation.

4. Grant the registered application API.ReadWrite.All and Automation.ReadWrite.All permission to the Dynamics 365 Business Central API as follows:

   1. Select API permissions > Add a permission > Microsoft APIs.

   2. Select Dynamics 365 Business Central.

   3. Select Application permissions, select API.ReadWrite.All and Automation.ReadWrite.All, then select Add permissions.

      The API permissions page will include one of the following entries:

      API / Permission name	Type	Description
      Dynamics 365 Business Central / Automation.ReadWrite.All	Application	Full access to automation
      Dynamics 365 Business Central / API.ReadWrite.All	Application	Access to APIs and webservices

      For the latest guidelines about adding permissions in Microsoft Entra ID, see Add permissions to access your APIs in the Azure documentation.

   4. (optional) Grant admin consent on each permission by selecting it in the list, then selecting Grant admin consent for <tenant name>.

      This step isn't required if you'll be granting consent from the Business Central web client in task 2.

Task 2: Set up the Microsoft Entra application in Business Central

Complete these steps to set up the Microsoft Entra application for service-to-service authentication in Business Central.

1. In the Business Central client, search for Microsoft Entra applications and open the page.

2. Select New.

   The Microsoft Entra application Card opens.

3. In the Client ID field, enter the Application (Client) ID for the registered application in Microsoft Entra ID from task 1.

4. Fill in the Description field. If this application is set up by a partner, please enter sufficient partner-identifying information, so all applications set up by this partner can be tracked in the future if necessary.

5. Set the State to Enabled.

6. Assign permissions to objects as needed.

   For more information, Assign Permissions to Users and Groups.

   Important

   Applications can't be assigned the SUPER permission set. Make sure that applications follows least-privilege principle and only assign permissions required for the integration to work.

   Note

   The system permission sets and user groups called D365 AUTOMATION and EXTEN. MGT. - ADMIN provide access to most typical objects used with automation.

   The EXTEN. MGT. - ADMIN permission set was introduced in Business Central 2021 release wave 1 as a replacement for the D365 EXTENSION MGT permission set in earlier versions.

7. (optional) Select Grant Consent and follow the wizard.

   This step will grant consent to the API. This step is only required if you haven't granted consent from the Azure portal in task 1. You can only complete this step if you've configured a redirect URL in the registered Microsoft Entra app.

   Tip

   Pre-consent can be done by adding the Microsoft Entra application to the Adminagents group in the partner tenant. For more information, see Pre-consent your app for all your customers in the Graph documentation.

Calling API and web services OAuth2Flows

After the Microsoft Entra application has been set up and access has been granted, you're ready to make API and web service calls to Business Central.

For most cases, use the AcquireTokenByAuthorizationCode method from the OAuth 2.0 module. For more information, see Microsoft identity platform and OAuth 2.0 authorization code flow. To explore an example, see OAuth2Flows.

   [NonDebuggable]
   procedure GetAccessToken(var AccessToken: Text): Boolean
   begin
       ...
   end;

The following sample uses the Rest Client for Visual Studio Code using the Client Credentials OAuth 2.0 flow. Using the Rest Client makes it easy to see which HTTP calls are made both against Business Central and Azure Active Directory. Any HTTP client can be used to create the requests below. Or you can choose any library, like MSAL. Remember to specify the scope as https://api.businesscentral.dynamics.com/.default and the Token URL as https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token.

@tenantId = <tenant id>
@clientId = <client id>
@clientSecret = <client secret>
@baseUri = https://api.businesscentral.dynamics.com
@scope = {{baseUri}}/.default
@bcEnvironmentName = production
@url = {{baseUri}}/v2.0/{{bcEnvironmentName}}/api/v2.0

### Define entity, like customers, items, or vendors
@entityName =customers 

# @name auth
POST https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token HTTP/1.1
Content-type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={{clientId}}
&client_secret={{clientSecret}}
&scope={{scope}}

### Variable Response
@accessHeader = Bearer {{auth.response.body.$.access_token}}

# @name GetCompanies
GET {{url}}/companies HTTP/1.1
Authorization: {{accessHeader}}

### Variable Response
@companyId = {{GetCompanies.response.body.value.[0].id}}
@companyUrl = {{url}}/companies({{companyId}})
@displayName = MyItemDisplayName2

### Get entities

# @name GetEntities
GET {{companyUrl}}/{{entityName}} HTTP/1.1
Authorization: {{accessHeader}}

### Create entity

# @name CreateEntity
POST {{companyUrl}}/{{entityName}} HTTP/1.1
Content-Type:  application/json
Authorization: {{accessHeader}}

{
 "displayName" : "{{displayName}}"
}

### Get created entity

# @name GetCreatedEntity
GET {{companyUrl}}/{{entityName}}/?$filter=displayName eq '{{displayName}}' HTTP/1.1
Authorization: {{accessHeader}}

#### Variable Response
@entityId = {{GetCreatedEntity.response.body.value.[0].id}}

### Modify entity

# @name ModifyEntity
PATCH {{companyUrl}}/{{entityName}}({{entityId}})
Authorization: {{accessHeader}}
Content-Type:  application/json
If-Match: *

{
    "displayName" : "DeleteMe-{{displayName}}"
}

### Delete entity

# @name DeleteItem
Delete {{companyUrl}}/{{entityName}}({{entityId}})
Authorization: {{accessHeader}}

See Also

OAuth2 and Microsoft Entra ID
Client Credentials flow/S2S using MSAL library
C# samples using Client Credentials flow
OAuth 2.0 client credentials flow on the Microsoft identity platform
Samples and libraries for OAuth: Microsoft identity platform authentication libraries
Business Central Repository on GitHub - PowerShell samples using MSAL
Business Central API v2.0