Einstellungen und Vorschauprofile

OAuth: Preview mit Business Central verbinden

OAuth ist die Anmeldung über Microsoft Entra ID. AL Report Creator erhält dabei einen zeitlich begrenzten Zugangsschlüssel (Token), mit dem die Vorschau und der Dataset Viewer auf Business Central zugreifen. Dein Microsoft-Passwort gibst Du nur bei Microsoft ein. Diese Verbindung ist unabhängig von Deinem AL-Report-Creator-Konto und dessen API-Key.

Die folgenden Schritte gelten für Business Central Online. In der Zielumgebung muss die Preview Service App installiert sein; starte dafür ALRC: Manage Preview Service. Für die einmalige Einrichtung der Microsoft-App benötigst Du Unterstützung durch Eure Entra-/Business-Central-Administration.

Welche Anmeldung passt?

• Mit Deinem Microsoft-Konto (oauthInteractive): Für die normale Arbeit in VS Code. Du meldest Dich im Browser an; Business Central verwendet Deine Benutzerberechtigungen.
• Mit einem Anwendungskonto (oauthClientCredentials): Die Verbindung verwendet eine registrierte App und ein Client Secret statt Deiner persönlichen Anmeldung. Die App benötigt eigene Berechtigungen in Business Central.

1. Anmeldung mit Deinem Microsoft-Konto vorbereiten

1. Die Administration registriert im Microsoft Entra Admin Center unter App-Registrierungen eine App für Euer Organisationsverzeichnis. Notiere die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant) aus der Übersicht.
2. Unter Authentifizierung → Erweiterte Einstellungen wird Öffentliche Clientflows zulassen aktiviert. Der hier verwendete Device-Code-Flow benötigt keine Umleitungs-URL und kein Client Secret.
3. Unter API-Berechtigungen wird für Dynamics 365 Business Central die delegierte Berechtigung user_impersonation hinzugefügt. Die Administration erteilt die in Eurer Organisation erforderliche Zustimmung.
4. Dein BC-Benutzer benötigt Zugriff auf die Umgebung, den gewünschten Mandanten und die Berichtsdaten sowie den Berechtigungssatz SPO ARC PREVIEW.

2. VS Code konfigurieren

Ergänze in .vscode/settings.json das folgende Objekt in den vorhandenen Einstellungen. BC Cloud Sandbox muss exakt dem name Deiner AL-Konfiguration in .vscode/launch.json entsprechen. Ersetze die Beispiel-IDs durch die Werte aus Entra und Sandbox durch den Namen Deiner BC-Umgebung.

{
  "al-report-creator.preview.launchOverrides": {
    "BC Cloud Sandbox": {
      "kind": "cloud",
      "tenantId": "11111111-1111-1111-1111-111111111111",
      "environmentName": "Sandbox",
      "clientId": "22222222-2222-2222-2222-222222222222",
      "auth": { "mode": "oauthInteractive" }
    }
  }
}

tenantId bezeichnet hier Euer Microsoft-Verzeichnis, nicht den BC-Mandanten wie „CRONUS“. Den BC-Mandanten wählst Du beim ersten Zugriff aus; alternativ trägst Du dessen Namen als company im Profil ein. tokenUrl und scope kannst Du bei dieser Standardkonfiguration weglassen.

3. Erste Vorschau öffnen

1. Öffne einen AL-Report und starte ALRC: Preview Report.
2. VS Code zeigt einen Anmeldecode und den Einstieg zur Microsoft-Anmeldung. Wähle Open Browser, gib dort bei Bedarf den angezeigten Code ein und melde Dich mit Deinem BC-Benutzer an. Bestätige gegebenenfalls die Mehrfaktor-Anmeldung.
3. Wechsle zurück zu VS Code und wähle bei Bedarf den BC-Mandanten. Anschließend wird die Vorschau geladen.

Das Access Token wird in VS Code SecretStorage gespeichert. Nach seinem Ablauf ist eine erneute Anmeldung erforderlich. Eine automatische Erneuerung per Refresh Token ist derzeit nicht implementiert, auch wenn der angeforderte Standard-Scope offline_access enthält.

Alternative: Anwendungskonto mit Client Secret

Die Administration registriert eine App, erstellt unter Zertifikate & Geheimnisse ein Client Secret und gewährt die Anwendungsberechtigung API.ReadWrite.All für Business Central samt Administratorzustimmung. In BC wird dieselbe Client-ID unter Microsoft Entra-Anwendungen aktiviert und erhält SPO ARC PREVIEW sowie die benötigten Berichtsdaten-Berechtigungen. Für Preview-Webservice-Aufrufe ist Automation.ReadWrite.All nicht erforderlich.

Verwende im obigen Beispiel die IDs dieser App und ändere ausschließlich den Anmeldemodus:

"auth": { "mode": "oauthClientCredentials" }

AL Report Creator fragt beim ersten Zugriff nach dem Wert des Client Secrets (nicht nach dessen ID) und speichert ihn in SecretStorage. Trage das Secret niemals in settings.json oder launch.json ein. Es gibt bei dieser Variante keine Browseranmeldung; die Extension fordert das Token mit dem gespeicherten Secret an. Behalte das Ablaufdatum des Secrets im Blick.

Wenn die Anmeldung nicht klappt

• App nicht gefunden: Prüfe tenantId und clientId; beide müssen zur vorgesehenen Registrierung gehören.
• Zustimmung fehlt oder Device Code ist gesperrt: Lass die API-Berechtigungen, öffentlichen Clientflows und Anmelderichtlinien durch Eure Administration prüfen.
• Anmeldung erfolgreich, Zugriff verweigert: Prüfe die BC-Berechtigungen des Benutzers beziehungsweise der App, den BC-Mandanten und die installierte Preview Service App.
• Client Secret ungültig: Prüfe, ob der Secret-Wert statt der Secret-ID verwendet wurde und ob das Secret noch gültig ist.

On-Premises benötigt eine passend eingerichtete Entra-Anbindung des BC-Servers; die Cloud-Konfiguration oben allein reicht dafür nicht aus. Weiterführend: Microsoft: öffentliche Clientflows, Microsoft: Anwendungskonten für Business Central.