Using Service-to-Service (S2S) Authentication

[アーティクル]
06/03/2024

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

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.

Note

For more information about OAuth 2.0 flows, see OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform in the Microsoft Entra ID documentation.

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.

API	Online	On-premises
Business Central automation APIs	version 17.0	versions 18.11 and 19.5
Business Central APIs v1.0	version 18.3	versions 18.11 and 19.5
Business Central APIs v2.0	version 18.3	versions 18.11 and 19.5
Business Central custom APIs	version 18.3	versions 18.11 and 19.5
Business Central web services	version 18.3	versions 18.11 and 19.5

Main usage scenarios

Two main scenarios are enabled with S2S authentication:

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.
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.

Note

When you use S2S authentication, you can now use the integration session to create scheduled tasks. This is supported on 21.2 and later versions of Business Central online.

Business Central on-premises prerequisite

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

Important

The ValidAudiences parameter of the Business Central must include the endpoint https://api.businesscentral.dynamics.com. If it doesn't, you'll get the error Authentication_InvalidCredentials on API requests, or the error securitytokeninvalidaudienceexception in the application log when you try to download symbols from Visual Studio.

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.

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.

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.

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

Select API permissions > Add a permission > Microsoft APIs.
Select Dynamics 365 Business Central.

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.

(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.

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

The Microsoft Entra application Card opens.
In the Client ID field, enter the Application (Client) ID for the registered application in Microsoft Entra ID from task 1.
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.
Set the State to Enabled.
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.
(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.

Important

When getting access tokens, it's important to keep security in mind. For example, ensure that you don't expose the tokens. You can do that in two ways:

Make the method you are using non-debuggable. Here's an example of how to use the non-debuggable property for protecting access tokens:

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

Set the showMyCode property to false for the extension.

Tip

You can also see this sample in the BCTech Github repo.

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}}

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

次の方法で共有

Using Service-to-Service (S2S) Authentication

Feature availability

Main usage scenarios

Business Central on-premises prerequisite

Set up service-to-service authentication

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

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

Calling API and web services OAuth2Flows

フィードバック

その他のリソース

次の方法で共有

Using Service-to-Service (S2S) Authentication

Feature availability

Main usage scenarios

Business Central on-premises prerequisite

Set up service-to-service authentication

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

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

Calling API and web services OAuth2Flows

Related information

フィードバック

その他のリソース