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.

Note

For more information about OAuth 2.0 flows, see OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform in the Azure Active Directory (Azure AD) 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 Azure Active Directory.

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:

  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.

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 Azure AD 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 Azure Active Directory 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 Azure Active Directory 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 an Azure AD application for authentication to Business Central

Complete these steps to register an application in your Azure AD tenant for service-to-service authentication.

  1. Sign in to the Azure portal.

  2. Register an application for Business Central in Azure Active Directory tenant.

    Follow the general guidelines at Register your application with your Azure Active Directory tenant.

    When you add an application to an Azure AD 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 Azure AD 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/BC210/OAuthLanding.htm or https://cronus.onmicrosoft.com/BC210/OAuthLanding.htm. This file is used to manage the exchange of data between Business Central and other services through Azure AD.

    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/BC210/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 Azure AD, 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 Azure AD, 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 Azure AD application in Business Central

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

  1. In the Business Central client, search for Azure Active Directory Applications and open the page.

  2. Select New.

    The Azure Active Directory Application Card opens.

  3. In the Client ID field, enter the Application (Client) ID for the registered application in Azure AD 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 EXTEND. MGT. - ADMIN provide access to most typical objects used with automation.

    The EXTEND. 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 Azure AD app.

    Tip

    Pre-consent can be done by adding the AAD 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 Azure AD 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 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.

@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 Azure Active Directory
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