Service to service authentication in Business Central – Usage and license terms

Business Central 18.3 is just around the corner, and it comes with a long-awaited feature: support for OAuth client credentials flow, aka service-to-service authentication.

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 favor 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. This is only for SaaS and NOT for on-premise! For on-prem environments, the web service access key will still be an option.

The upcoming update 18.3 closes a gap in the OAuth story. At this moment Business Central SaaS already supports OAuth for delegated permissions. Version 18.3 adds application permissions as another option. An option many were waiting for.

The official documentation can be found here: https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication.

In this blog post, I want to explain the difference between delegated permissions and application permissions in relation to the usage scenarios and license terms. The next blog posts will show how to set it up and how to use it, including code examples.

Delegated permissions

Delegated permissions are used by apps that have a signed-in user (a human being). The user must have a user account in Business Central and consents to the permissions the app requests. As a result, the app is delegated to act as the signed-in user when it makes calls to Business Central APIs. In other words, the app itself does not have permissions, but the permissions of the app user are used.

The process to consent to the permissions requires a user interface. The user needs to log in and he will be asked if he trusts the application to access Business Central on his behalf. There are different ways to achieve this user interaction, known as authorization flows. A flow is simply a series of steps to let the user log in, request the permission, consent to the permission and finally retrieve the required authorization grant.

Most people are struggling with the user interaction. The series of steps involves forwarding the user to Azure to log in and to provide a redirect URI to catch the authorization code returned by Azure after the login procedure. This is way more complicated compare to just a username and password.

Application permissions

Application permissions are used by apps that run without a signed-in user. For example background services or websites that face non Business Central users. The application has its own account in Business Central, with its own set of permissions. The steps to request the permissions is known as the client credentials flow, whereas client stands for the external application or background service.

Usage scenarios

It’s quite important to understand when to use delegated permissions or application permissions.

As a rule of thumb, delegated permissions should be used if the external application is used by Business Central users. Access to Business Central should take place with respect to the permissions of that user. But this is also the biggest hurdle towards OAuth. The application needs to implement one of the delegated permissions flows and apply them for every single user.

Many external applications are using a single user to get access to Business Central. With the web service access key it was quite easy to set up a connection with basic authentication. Moving to OAuth, where every user needs to log in requiring extra user interaction proved to be a challenge to many Business Central partners. Also because the OAuth2 implementation in Azure Active Directory has so many options that it’s quite hard to find the correct settings.

That’s the reason why many were waiting for the client credentials flow because that flow is much easier to implement. No user interaction required, just one call to retrieve that access token, and that’s it.

But then… license terms…

If an application connects to Business Central with a single account, then that’s considered multiplexing. In itself, this is not prohibited. However, it does not reduce the number of required licenses. All users accessing Business Central need to be properly licensed. No matter if they access Business Central with their own credentials or by sharing a single user.

The Dynamics 365 Licensing Guide distinguishes between internal and external users.

Internal users are all users who are providing business processes, like employees, contractors, agents, etc. They need to be licensed for Business Central.

External users are described as “customers and suppliers not performing business processes on behalf of the organization”. These external users do not require a user license to access Dynamics 365 (including Business Central). In fact, they come for free with the internal user license.

The licensing guide also describes multiplexing as pooled connections, using a non-interactive Dynamics 365 user account. A non-interactive user account can access the system only via the web service layer. Internal users accessing Dynamics 365 indirectly, using a pooled connection, must also be properly licensed. Even if they don’t have their own user account! External users however are free to use a pooled connection.

This opens many scenarios, for example the web shop scenario where the web shop application needs to access Business Central, but there is no Business Central user.

Another scenario would be a background service uploading files to Business Central to be processed by users.

In these scenarios, a non-interactive user account should be used rather than a normal user account. But Business Central did not have such non-interactive user account. And that is going to change.

In Business Central 2020 release wave 20 (version 17) the Azure Active Directory Application page was introduced in Business Central. This will be used to configure a non-interactive user account. Behind the scenes, it creates a new record in the user table with license type = Application.

Permissions and limitations

In the AAD Application card, you can set up the permissions for this application user. Try to limit the permissions to the very minimum that is required by the external application to perform his tasks. It is not possible to assign SUPER permissions to an application account. The application account will also not be able to start a background process. These are two limitations that make sense considering the role of the external user that is supposed to connect to Business Central using this application account.

Final thoughts

The application account enables the OAuth client credentials flow, making it much easier to retrieve an access token and call Business Central APIs.

But be careful!

The permissions assigned to the application account are shared by all sessions using this account to access Business Central. This could potentially lead to the situation that an internal user gets more permissions than he should. Or more permissions than he has with his personal user account, if he has one.

It’s recommended to create specific apps with the least required permissions. Do not share or mix application accounts for different purposes. There is no limit as to how many application accounts you can create. And they are for free, there is no license cost involved.

As I explained above, using the application account does not reduce the number of required licenses for internal users. The application account enables the scenario for external users, that is what it has been designed for in the first place.

I would like to finish with a list of usage scenarios:

• Webshop integration
  • Retrieving price information and actual inventory
  • Creating sales quotes and orders
• Uploading files to Business Central with a background process like Azure Functions
  • Attachments from incoming emails
  • Bank statement files
  • New files in a SharePoint document library
• Vendor portal
  • Creating purchase quotes
• Production portal
  • Register finished items
  • Register item usage
• Timesheet app
  • Entering time spent on a job

The Production portal and Timesheet app are examples of scenarios where the users are considered internal users because they are working for the organization. However, it might be useful to use an application account to connect to Business Central and not bother the user with the OAuth authorization flow. The timesheet app could even be used by contractors, not having an Azure Activate Directory account at all. But what they have in common is that they need one set of permissions to enter the information. In that case an application account with proper permissions would be much easier to use. BUT… because these users are internal the organization needs to buy licenses for these users anyway!

I hope the above was clear enough to give you the information you need to choose the proper OAuth authorization flow while still complying with the license terms!