Authentifizierung (On-Premises)

Bei einer On-Premises-Installation von Business Central ist der Zugriff auf die Webservices nicht auf OAuth 2.0 beschränkt. Diese Seite beschreibt, wie sich BREEZE und andere Systeme dort anmelden. Für Business Central Online gilt die Seite OAuth 2.0 Einrichtung (nur für SaaS).

Unterschied zwischen SaaS und On-Premises

Microsoft hat die Anmeldung mit Webdienstzugriffsschlüssel (Basic Auth) im Oktober 2022 nur in Business Central Online abgeschaltet. On-Premises akzeptiert Business Central weiterhin beide Verfahren:

• Benutzer und Passwort: Die Anmeldung erfolgt mit einem BC-Benutzer und dessen Kennwort oder Webdienstzugriffsschlüssel.
• OAuth 2.0: Die Anmeldung erfolgt wie bei SaaS über eine App-Registrierung in Microsoft Entra ID.

BREEZE anbinden

BREEZE verbindet sich mit einer On-Premises-Installation über den Verbindungstyp Dynamics 365 BC (on Prem). Dieser Verbindungstyp meldet sich mit Benutzer und Passwort an. OAuth 2.0 bietet BREEZE nur beim Verbindungstyp Dynamics 365 BC (SaaS) an. Die Felder der Verbindung beschreibt die BREEZE-Dokumentation unter Verbindungen.

Voraussetzungen

• Die BC-Serverinstanz verwendet den Anmeldeinformationstyp NavUserPassword oder AccessControlService. Nur bei diesen Typen nehmen die Webservices Benutzer und Passwort entgegen.
• Die Webservices sind per HTTPS (SSL) erreichbar. Bei dieser Anmeldung werden die Zugangsdaten mit jeder Anfrage übertragen.
• Der OData-Port der Serverinstanz (oft 7048) ist vom BREEZE-System aus erreichbar.
• Die API-Funktionen sind in der Serverinstanz aktiviert, siehe Besonderheiten bei BC onPrem.

Einrichtung in Business Central

1. Einen eigenen Benutzer für die Schnittstelle anlegen. Der Benutzer benötigt eine BC-Benutzerlizenz.
2. Dem Benutzer die benötigten Berechtigungssätze zuweisen, siehe Berechtigungssätze.
3. Auf der Benutzerkarte im Abschnitt Webdienstzugriff einen Webdienstzugriffsschlüssel erzeugen. Bei AccessControlService ist der Schlüssel erforderlich. Bei NavUserPassword kann stattdessen auch das Kennwort des Benutzers verwendet werden. Der Schlüssel ist trotzdem vorzuziehen, weil er nur für Webservices gilt und ein Ablaufdatum haben kann.
4. In BREEZE in der Verbindung den Benutzernamen unter Benutzer und den Webdienstzugriffsschlüssel (oder das Kennwort) unter Passwort eintragen und die Verbindung mit Verbindung Prüfen testen.

Andere Systeme: OAuth 2.0 auch On-Premises

Systeme, die die Breeze Interface API direkt aufrufen, können sich On-Premises auch mit OAuth 2.0 (Client-Credentials-Flow) anmelden. Dafür muss die BC-Serverinstanz für Microsoft Entra ID mit OpenID Connect konfiguriert sein, und der Serverparameter ValidAudiences muss https://api.businesscentral.dynamics.com enthalten.

Die Schritte in Microsoft Entra ID und in Business Central entsprechen dann der Seite OAuth 2.0 Einrichtung (nur für SaaS). Die Voraussetzungen auf der Serverseite beschreibt Microsoft unter Microsoft Learn: Service-to-Service-Authentifizierung.

Empfehlung

• BREEZE: ein eigener Benutzer mit Webdienstzugriffsschlüssel über den Verbindungstyp Dynamics 365 BC (on Prem).
• Andere Systeme: OAuth 2.0, wenn die Serverinstanz ohnehin mit Microsoft Entra ID betrieben wird. Dann hängt kein Kennwort an der Schnittstelle, und Microsoft empfiehlt dieses Verfahren. Ohne Microsoft Entra ID ist ein eigener Benutzer mit Webdienstzugriffsschlüssel der einfachere Weg.

Microsoft führt den Webdienstzugriffsschlüssel in der Dokumentation als veraltet und empfiehlt OAuth 2.0. Abgeschaltet ist er bisher nur in Business Central Online. Bei einem Wechsel nach Business Central Online muss die Anmeldung deshalb auf OAuth 2.0 umgestellt werden, in BREEZE auf den Verbindungstyp Dynamics 365 BC (SaaS).