Authentication (on-premises)
On an on-premises installation of Business Central, access to the web services is not limited to OAuth 2.0. This page describes how BREEZE and other systems authenticate there. For Business Central online, see OAuth 2.0 setup (for SaaS only).
Difference between SaaS and on-premises
In October 2022, Microsoft switched off authentication with web service access keys (Basic Auth) in Business Central online only. On-premises, Business Central still accepts both methods:
- User name and password: the caller signs in with a BC user and that user's password or web service access key.
- OAuth 2.0: the caller signs in through an app registration in Microsoft Entra ID, as with SaaS.
Connecting BREEZE
BREEZE connects to an on-premises installation through the connection type Dynamics 365 BC (on Prem). This connection type signs in with a user name and password. BREEZE offers OAuth 2.0 only with the connection type Dynamics 365 BC (SaaS). The connection fields are described in the BREEZE documentation under Verbindungen (German).
Prerequisites
- The BC server instance uses the credential type NavUserPassword or AccessControlService. Only these types let the web services accept a user name and password.
- The web services are reachable over HTTPS (SSL). With this method, the credentials travel with every request.
- The OData port of the server instance (often 7048) is reachable from the BREEZE system.
- API services are enabled on the server instance, see Besonderheiten bei BC onPrem (German).
Setup in Business Central
- Create a dedicated user for the interface. The user needs a BC user license.
- Assign the required permission sets to the user, see Permission sets.
- On the user card, in the Web Service Access section, generate a Web Service Access Key. With AccessControlService the key is required. With NavUserPassword the user's password works as well, but the key is still the better choice because it is valid for web services only and can have an expiration date.
- In the BREEZE connection, enter the user name under Benutzer and the web service access key (or the password) under Passwort, then test the connection with Verbindung Prüfen.
Other systems: OAuth 2.0 on-premises
Systems that call the Breeze Interface API directly can also authenticate on-premises with OAuth 2.0 (client credentials flow). This requires the BC server instance to be configured for Microsoft Entra ID with OpenID Connect, and the server parameter ValidAudiences must include https://api.businesscentral.dynamics.com.
The steps in Microsoft Entra ID and in Business Central are then the same as on OAuth 2.0 setup (for SaaS only). Microsoft describes the server-side prerequisites in Microsoft Learn: Using Service-to-Service (S2S) Authentication.
Recommendation
- BREEZE: a dedicated user with a web service access key, using the connection type Dynamics 365 BC (on Prem).
- Other systems: OAuth 2.0 if the server instance already runs with Microsoft Entra ID. No password is tied to the interface, and it is the method Microsoft recommends. Without Microsoft Entra ID, a dedicated user with a web service access key is the simpler option.
Microsoft lists the web service access key as deprecated in its documentation and recommends OAuth 2.0. So far it has been switched off in Business Central online only. When moving to Business Central online, authentication therefore has to change to OAuth 2.0, and in BREEZE to the connection type Dynamics 365 BC (SaaS).