OAuth in Business Central - Azure App Registration, Permissions & typische Fehler (endlich verständlich)

Ein typischer Projektmoment:

„Wir brauchen nur schnell eine API-Anbindung."

Zwei Stunden später sieht die Realität so aus:

AADSTS700016
401 Unauthorized
403 Forbidden
"The user does not have the following permissions..."

Der Developer ist frustriert.
Der Admin ist ratlos.
Der Projektleiter fragt: „Warum dauert das so lange?"

Und das Spannende ist:

OAuth ist nicht kompliziert - aber es ist gnadenlos konsequent.

In diesem Artikel schauen wir uns an, wie OAuth in Microsoft Dynamics 365 Business Central wirklich funktioniert, warum es fast immer an Permissions scheitert und wie man Azure App Registrations sauber konfiguriert.

1) OAuth in Business Central ist kein „BC-Thema" - es ist Azure AD

Das ist der wichtigste Mindset-Shift überhaupt.

Viele Developer und Admins denken:

„Ich gebe der App Rechte in Business Central und dann geht's."

In Wirklichheit brauchst du zwei Welten, die beide stimmen müssen:

1. Azure AD / Entra ID (wer darf Token holen)
2. Business Central (wer darf Daten sehen)

Das ist kein „entweder-oder".
Das ist ein Und.

Wenn eine Seite nicht passt, bekommst du:

• 401 Unauthorized
• 403 Forbidden
• Token invalid
• oder kryptische AADSTS-Fehlercodes

Viele Projekte scheitern genau hier - weil sie nur eine Hälfte konfigurieren.

2) Die 2 OAuth-Arten, die in BC relevant sind

Bevor du überhaupt anfängst, musst du eine fundamentale Entscheidung treffen:

Arbeitet deine Integration mit User-Kontext oder ohne?

Daraus ergeben sich zwei völlig unterschiedliche OAuth-Flows:

a) Delegated Permissions (User-Kontext)

Das bedeutet:

• Ein echter User loggt sich ein
• Token enthält User-Identität
• Business Central prüft die Rechte dieses Users

Typisch für:

• Web Apps
• Power Apps mit User Login
• Tools, die „im Namen des Users" arbeiten
• interaktive Szenarien

Wichtig:
Der User muss in BC existieren und Rechte haben.

b) Application Permissions (Client Credentials)

Das bedeutet:

• Kein User
• Die App selbst ist „der User"
• Permissions laufen über BC Service Principal / Application User

Typisch für:

• Middleware
• Background Integration
• ETL-Prozesse
• „Nachts Daten synchronisieren"
• Headless Integrationen

Wichtig:
Hier musst du in BC einen Application User anlegen - sonst geht nichts.

💡 Seitennotiz:
Das ist exakt das gleiche Prinzip wie bei GuiAllowed in AL:
Headless Kontext ist in BC nicht nur beim Code so - sondern auch bei OAuth.

3) Azure App Registration - das Setup, das wirklich zählt

Jetzt wird es konkret.

Hier ist die Schritt-für-Schritt-Anleitung, die du in fast jedem Projekt brauchst.

Schritt 1: App registrieren

Du gehst in Azure Portal → App Registrations → New Registration.

Was du hier entscheiden musst:

• Name: Sprechender Name (z. B. „BC Integration Middleware")
• Tenant: Single Tenant vs. Multi Tenant

Wichtig:

Wenn du nur für deine eigene Firma integrierst: Single Tenant.
Wenn du eine SaaS-App baust: Multi Tenant.

Nach der Registrierung bekommst du:

• Application (client) ID
• Directory (tenant) ID

Die brauchst du später überall.

Schritt 2: API Permissions setzen

Das ist der Punkt, an dem die meisten falsch abbiegen.

Du gehst in API Permissions → Add a permission.

Dann musst du:

1. „APIs my organization uses" wählen
2. Nach „Dynamics 365 Business Central" suchen
3. Dann hast du zwei Optionen:
   • Delegated permissions (für User-Kontext)
   • Application permissions (für Headless)
4. Dann z. B. auswählen:
   • Financials.ReadWrite.All
   • oder granularer: API.ReadWrite.All

Aber Achtung:

Die Permissions alleine reichen nicht.

Solange nicht Admin Consent erteilt wurde, sind die Permissions nur „vorgemerkt" - aber nicht aktiv.

Schritt 3: Admin Consent geben

Typischer Projekt-Satz:

„Ich habe doch alles gesetzt, warum kommt immer noch 403?"

Antwort:

Weil ohne Admin Consent gilt:

• Permission existiert
• aber ist nicht aktiv

Du musst entweder:

• als Admin auf „Grant admin consent for Tenant" klicken
• oder der User muss beim ersten Login zustimmen (bei Delegated Permissions)

Wenn das fehlt, bekommst du:

AADSTS65001: The user or administrator has not consented

Schritt 4: Client Secret oder Certificate

Für Client Credentials (Application Permissions) brauchst du außerdem:

• Client Secret (einfacher, aber läuft ab)
• oder Certificate (sicherer, komplexer)

Wichtig:

Secrets laufen nach maximal 24 Monaten ab.
Wenn du das vergisst, bricht die Integration irgendwann einfach ab.

Plan also Secret Rotation von Anfang an ein.

4) Business Central Seite: App muss als User existieren

Hier kommt der Teil, den 80% vergessen.

Wenn du Client Credentials nutzt (also Application Permissions), dann musst du in Business Central:

1. Einen Application User / Service Principal anlegen
2. Diesem User Permission Sets geben
3. Ggf. Company-Zugriff beachten

Das machst du in BC unter:

Users → New → AAD User → Application ID eintragen

Dann:

• Permission Sets zuweisen (z. B. D365 AUTOMATION, API - FULL)
• Unternehmen zuordnen

Wichtig:

Azure regelt, ob du ein Token bekommst.
Business Central regelt, ob du damit Daten lesen/schreiben darfst.

Wenn du nur Azure konfigurierst, aber den BC-User vergisst, bekommst du:

403 Forbidden

Oder:

The user does not have the following permissions...

5) Der häufigste Denkfehler: „API Permissions ersetzen BC Permissions"

Das muss man sich wirklich groß an die Wand hängen:

Azure Permissions = darf Token holen
BC Permission Sets = darf Business-Daten lesen/schreiben

Beides muss passen.

Viele denken:

„Wenn ich in Azure Financials.ReadWrite.All setze, dann darf die App alles."

Falsch.

Auch mit diesem API Permission gilt in BC:

• User muss existieren
• User braucht Permission Sets
• Permission Sets müssen die richtigen Objekte freigeben

Das ist bewusst so designed - denn sonst könnte jede Azure-App ohne weitere Kontrolle auf BC-Daten zugreifen.

6) Typische Fehlerbilder (der Gold-Teil)

Jetzt wird es richtig praktisch.

Das sind die Fehlermeldungen, die du garantiert sehen wirst - und was sie bedeuten.

❌ 401 Unauthorized

Was es bedeutet:

Das Token ist ungültig oder fehlt komplett.

Häufige Ursachen:

• Falscher Client Secret
• Secret abgelaufen
• Falsche Tenant-ID
• Falscher Token-Endpunkt (v1 vs v2)
• Falsches Scope (z. B. https://api.businesscentral.dynamics.com/.default vergessen)
• Token nicht im Authorization: Bearer <token> Header übergeben

Fix:

Token-Request nochmal prüfen - oft ist die resource oder scope falsch.

❌ 403 Forbidden

Was es bedeutet:

Token ist gültig - aber der User darf das nicht.

Häufige Ursachen:

• App hat keinen User in BC
• Permission Sets fehlen
• Falsche Company
• API Page nicht veröffentlicht / Zugriff nicht erlaubt
• User ist deaktiviert

Fix:

In BC nachschauen: Existiert der Application User? Hat er die richtigen Permission Sets?

❌ AADSTS700016

Vollständige Meldung:

AADSTS700016: Application with identifier 'xyz' was not found in the directory 'abc'

Was es bedeutet:

Azure findet die Application ID nicht.

Häufige Ursachen:

• Falsche Application ID
• Falscher Tenant
• App in anderem Tenant registriert

Fix:

Tenant ID und Application ID nochmal abgleichen.

❌ AADSTS7000215

Vollständige Meldung:

AADSTS7000215: Invalid client secret is provided

Was es bedeutet:

Der Client Secret stimmt nicht.

Häufige Ursachen:

• Falscher Secret
• Secret abgelaufen
• Leerzeichen oder Zeilenumbrüche im Secret
• Falsches Zertifikat (bei Certificate-based Auth)

Fix:

Secret neu generieren und exakt kopieren.

❌ „The user does not have the following permissions…"

Was es bedeutet:

User ist in BC bekannt, aber hat nicht die nötigen Rechte.

Häufige Ursachen:

• Permission Sets nicht korrekt
• Permission Set nicht in richtiger Firma aktiv
• Objekt-Permissions fehlen (z. B. Read auf Table XY)

Fix:

Permission Sets prüfen - oft fehlt ein einzelnes Objekt.

7) Warum „es geht in Postman, aber nicht in Power Automate"

Das ist ein absoluter Klassiker.

Du testest deine API in Postman - läuft perfekt.

Dann baust du einen Power Automate Flow - und plötzlich:

403 Forbidden

Warum?

Weil Power Automate oft einen anderen OAuth Flow nutzt.

Konkret:

• Postman: Du holst dir manuell ein Token mit Client Credentials
• Power Automate: Nutzt oft den Delegated Flow mit User-Login

Das bedeutet:

• Postman-Token = Application User
• Power Automate-Token = dein persönlicher User

Und wenn dein persönlicher User in BC nicht die gleichen Rechte hat wie der Application User, schlägt es fehl.

Lösung:

Entweder:

• Power Automate auch mit Client Credentials konfigurieren
• oder deinem User die gleichen Permission Sets geben

8) Best Practices (kurz, knackig)

Hier ein paar Dinge, die in Projekten oft vergessen werden:

✅ Secrets nie hartcodieren

Nutze:

• Azure Key Vault
• Environment Variables
• Secrets Manager

Nie direkt im Code oder in Config-Files.

✅ Secret Rotation planen

Secrets laufen ab - plan das von Anfang an ein.

Entweder:

• Automatisierte Rotation
• oder Kalender-Reminder 2 Monate vor Ablauf

✅ Minimal Permissions

Gib immer nur die Rechte, die wirklich gebraucht werden.

Nicht einfach pauschal D365 FULL ACCESS vergeben.

✅ Eigene Permission Sets für Integrationen

Erstelle spezifische Permission Sets wie:

• INTEGRATION - SALES API
• INTEGRATION - ITEM SYNC

Das macht Troubleshooting 10x einfacher.

✅ Logging (wer ruft was wann auf)

Besonders bei Headless Integrationen:

• Wer hat wann was aufgerufen?
• Welche Daten wurden verändert?

Sonst wird Debugging später zur Hölle.

✅ Trennung: Sandbox vs Production App Registrations

Nutze unterschiedliche App Registrations für:

• Development / Sandbox
• Production

Das verhindert, dass aus Versehen Production-Daten in Tests landen.

9) Mini-Checkliste (für den nächsten OAuth-Setup)

Wenn deine Integration nicht funktioniert, geh diese Liste durch:

Diese Checkliste löst in Projekten etwa 90% aller OAuth-Probleme.

Fazit

OAuth in Business Central ist nicht schwer.

Aber es ist ein Zwei-Schlüssel-System:

Azure entscheidet, ob du ein Token bekommst.
Business Central entscheidet, ob du damit arbeiten darfst.

Wenn du nur einen Schlüssel hast, kommst du nicht rein.

Viele Projekte scheitern genau hier - nicht weil OAuth kompliziert ist, sondern weil sie vergessen, beide Seiten zu konfigurieren.

Die gute Nachricht:

Wenn du einmal verstanden hast, wie die beiden Welten zusammenspielen, wird OAuth-Setup zur Routine.

Wenn OAuth-Setups in Projekten immer wieder eskalieren, liegt es fast nie an BC selbst - sondern an fehlender Struktur zwischen Azure und ERP-Rechten.