Postfachzugriff über Microsoft Graph
Zum Versenden von E-Mails aus einem Flow reicht das Mailmodul von Business Central – darauf setzt der Schritt E-Mail senden auf. Sobald ein Flow mehr braucht als Versand, etwa die Rechnungen lesen, die in einem freigegebenen Postfach eintreffen, deren Anhänge holen oder verarbeitete Nachrichten in einen Unterordner verschieben, führt der Weg über Microsoft Graph und den Schritt HTTP-Anfrage.
Von allein lässt Graph keinen Flow in ein Postfach. Du registrierst dazu erst eine App in Microsoft Entra ID, gibst ihr Zugriff auf genau ein Postfach und hinterlegst Client-ID und Secret in AutoFlow-Anmeldedaten. Diese Seite führt durch die komplette Einrichtung.
Graph-Mailberechtigungen gelten standardmäßig für die gesamte Organisation: Eine App mit Mail.Read liest jedes Postfach deines Tenants. AutoFlow kann das nachträglich nicht einschränken – die Begrenzung gehört nach Exchange Online. Schritt 4 darfst du also nicht überspringen.
Voraussetzungen
- Ein Microsoft-365-Tenant, in dem das Zielpostfach in Exchange Online liegt (ein freigegebenes Postfach genügt und braucht keine eigene Lizenz).
- Jemand mit der Rolle Anwendungsadministrator (oder Globaler Administrator) in Entra ID, um die App zu registrieren.
- Jemand mit der Rolle Exchange-Administrator oder Mitgliedschaft in der Rollengruppe Organisationsverwaltung, um die App auf das eine Postfach zu begrenzen.
- Das PowerShell-Modul für Exchange Online auf einem Admin-Rechner für Schritt 4 (
Install-Module ExchangeOnlineManagement).
Unterwegs sammelst du drei Werte ein. Halte sie bereit, bis die Anmeldedaten angelegt sind:
| Wert | Woher er kommt |
|---|---|
| Verzeichnis-ID (Mandant) | Übersicht der App-Registrierung |
| Anwendungs-ID (Client) | Übersicht der App-Registrierung |
| Wert des Client-Secrets | Entsteht in Schritt 2, wird nur einmal angezeigt |
Schritt 1 – App registrieren
- Öffne das Microsoft Entra Admin Center und gehe auf Identität → Anwendungen → App-Registrierungen → Neue Registrierung.
- Vergib einen sprechenden Namen, zum Beispiel
AutoFlow – Rechnungspostfach. - Wähle unter Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis (Einzelmandant).
- Lass Umleitungs-URI leer. AutoFlow meldet sich Maschine-zu-Maschine an; an dieser App meldet sich nie eine Person an.
- Wähle Registrieren.
Kopiere auf der Übersicht, die sich anschließend öffnet, die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant).
Schritt 2 – Client-Secret erzeugen
- Öffne in der App Zertifikate & Geheimnisse → Geheime Clientschlüssel → Neuer geheimer Clientschlüssel.
- Beschreibe ihn (
AutoFlow-Anmeldedaten) und wähle eine Gültigkeit. Entra erlaubt höchstens 24 Monate. - Wähle Hinzufügen und kopiere sofort die Spalte Wert – sie ist nur sichtbar, solange du auf der Seite bleibst. Die Geheimnis-ID ist nicht das Secret; AutoFlow braucht den Wert.
Trag das Ablaufdatum in einen Kalender ein, in den dein Team auch wirklich schaut. Läuft das Secret ab, scheitert jeder Flow mit diesen Anmeldedaten schon beim Token-Abruf, bis du ein neues Secret erzeugst und einträgst.
AutoFlow-Anmeldedaten authentifizieren sich am Token-Endpunkt mit einem Client-Secret. Zertifikate werden nicht unterstützt – lege also ein Secret an, auch wenn deine Tenant-Richtlinie sonst Zertifikate bevorzugt.
Schritt 3 – Weg der Berechtigung wählen
Es gibt zwei Wege, einer Entra-App Zugriff auf Mail zu geben, und sie verhalten sich grundverschieden.
| RBAC für Anwendungen (empfohlen) | API-Berechtigungen in Entra | |
|---|---|---|
| Konfiguriert in | Exchange Online | Entra Admin Center |
| Reichweite | Die Postfächer, die du benennst | Jedes Postfach im Tenant |
| Status | Das aktuelle Modell von Microsoft | Für sich allein nur sinnvoll, wenn die App wirklich alles sehen soll |
Beide Systeme wirken additiv: Eine tenantweite Berechtigung in Entra lässt sich durch einen Exchange-Bereich nicht nachträglich einengen – die App kommt dann trotzdem überall hin. Für den Zugriff auf ein einzelnes Postfach vergibst du die Berechtigung deshalb ausschließlich in Exchange Online und lässt die API-Berechtigungen der App-Registrierung leer.
Trägt deine App-Registrierung aus einem früheren Versuch bereits Graph-Anwendungsberechtigungen wie Mail.Read oder Mail.Send, entferne sie unter API-Berechtigungen, bevor du weitermachst.
Die Exchange-Rollen aus dem nächsten Schritt entsprechen eins zu eins den Graph-Berechtigungen:
| Exchange-Rolle | Erlaubt | Wofür |
|---|---|---|
Application Mail.Read | Mail.Read | Nachrichten und Anhänge lesen. |
Application Mail.ReadWrite | Mail.ReadWrite | Lesen sowie verschieben, kennzeichnen, löschen. |
Application Mail.Send | Mail.Send | Als das Postfach senden. |
Application Mail Full Access | Mail.ReadWrite + Mail.Send | Lesen, schreiben und senden in einer Zuweisung. |
Application MailboxFolder.Read | MailboxFolder.Read.All | Ordner auflisten. |
Wähle die engste Rolle, die deinen Flow abdeckt. Ein Flow, der nur eingehende Rechnungen abholt, braucht Application Mail.Read und sonst nichts.
Schritt 4 – App auf ein Postfach begrenzen (in PowerShell)
Dieser Schritt läuft komplett in PowerShell auf einem Admin-Rechner. Weder das Exchange Admin Center noch das Entra-Portal haben eine entsprechende Oberfläche – die folgenden Befehle lassen sich nirgends in eine Webseite eintippen. In den Browser wechselst du nur, um zwei IDs nachzuschlagen und hier einzusetzen.
Öffne ein PowerShell-Fenster und installiere das Exchange-Online-Modul, falls es noch fehlt:
Install-Module ExchangeOnlineManagement -Scope CurrentUser
Melde dich anschließend als Administrator an. Für die Anmeldung öffnet sich ein Browserfenster; danach bleibst du für den Rest dieses Schritts in PowerShell:
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName admin@contoso.com
4a. Exchange auf die App zeigen lassen
Exchange braucht einen eigenen Verweis auf den Dienstprinzipal der App, und dafür zwei IDs, die du im Browser nachschlägst: Entra Admin Center → Unternehmensanwendungen → deine App. Kopiere dort die Anwendungs-ID und die Objekt-ID – nicht unter App-Registrierungen, deren Objekt-ID ein anderer Wert ist.
Zurück in PowerShell:
New-ServicePrincipal `
-AppId 71487acd-ec93-476d-bd0e-6c8b31831053 `
-ObjectId 6233fba6-0198-4277-892f-9275bf728bcc `
-DisplayName "AutoFlow Rechnungspostfach"
Taucht die App unter Unternehmensanwendungen gar nicht auf, existiert noch kein Dienstprinzipal. Öffne dann in der App-Registrierung die Seite API-Berechtigungen und wähle einmal Administratorzustimmung erteilen (bei leerer Berechtigungsliste), um ihn anzulegen.
4b. Bereich definieren
Ein Verwaltungsbereich ist ein Filter über Postfacheigenschaften. Für ein einzelnes Postfach filterst du auf dessen Adresse:
New-ManagementScope `
-Name "AutoFlow Rechnungspostfach" `
-RecipientRestrictionFilter "PrimarySmtpAddress -eq 'rechnungen@contoso.com'"
Rechnest du damit, dass später weitere Postfächer dazukommen, richte den Bereich stattdessen auf eine E-Mail-aktivierte Sicherheitsgruppe und nimm die Postfächer dort auf:
$Gruppe = Get-Group -Identity "AutoFlow Postfaecher"
New-ManagementScope `
-Name "AutoFlow Postfaecher" `
-RecipientRestrictionFilter "MemberOfGroup -eq '$($Gruppe.DistinguishedName)'"
Es zählen nur direkte Gruppenmitglieder. Postfächer, die nur über eine verschachtelte Gruppe Mitglied sind, bleiben außerhalb des Bereichs.
4c. Rolle zuweisen
New-ManagementRoleAssignment `
-App 6233fba6-0198-4277-892f-9275bf728bcc `
-Role "Application Mail.Read" `
-CustomResourceScope "AutoFlow Rechnungspostfach"
Wiederhole das für jede Rolle, die der Flow braucht – eine Zuweisung pro Rolle, alle auf denselben Bereich.
4d. Nachprüfen
Test-ServicePrincipalAuthorization `
-Identity 6233fba6-0198-4277-892f-9275bf728bcc `
-Resource rechnungen@contoso.com | Format-Table
Für die zugewiesenen Rollen muss InScope auf True stehen. Führe denselben Befehl gegen ein Postfach aus, das die App nicht erreichen soll, und überzeuge dich, dass dort False zurückkommt – genau darum geht es in diesem Schritt.
Exchange hält die Berechtigungen einer App 30 Minuten bis 2 Stunden im Cache. Test-ServicePrincipalAuthorization umgeht den Cache und zeigt sofort den echten Stand; ein echter Graph-Aufruf kann sich nach einer Änderung an Rolle oder Bereich aber noch eine Weile wie vorher verhalten.
Schritt 5 – AutoFlow-Anmeldedaten anlegen
Öffne AutoFlow-Anmeldedaten über Tell-Me, wähle Neu und fülle die Karte:
| Feld | Wert |
|---|---|
| Code | Zum Beispiel GRAPH-RECHNUNG. |
| Beschreibung | Graph-Zugriff auf rechnungen@contoso.com. |
| Test-URL | https://graph.microsoft.com/v1.0/users/rechnungen@contoso.com/mailFolders/inbox |
| Authentifizierungstyp | OAuth 2.0 Client Credentials |
| OAuth-Token-URL | https://login.microsoftonline.com/<mandanten-id>/oauth2/v2.0/token |
| OAuth-Client-ID | Die Anwendungs-ID (Client) aus Schritt 1. |
| Client-Secret | Der Wert des Secrets aus Schritt 2. |
| OAuth-Scope | https://graph.microsoft.com/.default |
| OAuth-Grant-Type | Client Credentials |
| Transport der Client-Anmeldedaten | Request-Body (formcodiert) |
Der Scope lautet wörtlich https://graph.microsoft.com/.default – nicht die einzelnen Berechtigungsnamen. Entra liest ihn als „alles, wozu diese App berechtigt ist“.
Anmeldedaten auf das Postfach festnageln
Trag unter Basis-URLs einen Eintrag ein:
https://graph.microsoft.com/v1.0/users/rechnungen@contoso.com
Das ist ein zweites, unabhängiges Sicherheitsnetz. AutoFlow schickt die Anmeldedaten an keine URL, die nicht mit diesem Präfix beginnt – eine vertippte oder kopierte Schritt-URL auf ein anderes Postfach wird abgewiesen, bevor die Anfrage Business Central verlässt. Nebenbei kannst du in den Schritten kurze relative URLs wie /messages verwenden.
Speichere die Karte und wähle Test. Eine 200 bedeutet: Das Token wurde ausgestellt und Exchange hat die App ins Postfach gelassen. Alles andere findest du unter Fehlersuche.
Schritt 6 – Das Postfach aus einem Flow ansprechen
Füge einen Schritt HTTP-Anfrage ein, wähle unter Anmeldedaten die neuen Anmeldedaten aus und arbeite mit relativen URLs.
Die zehn neuesten ungelesenen Nachrichten lesen:
| Feld | Wert |
|---|---|
| Anfragemethode | GET |
| Anfrage-URL | /messages?$filter=isRead eq false&$top=10&$orderby=receivedDateTime desc |
Gib die Antwort an einen Parser-Schritt, um Absender, Betreff und Nachrichten-IDs herauszuziehen, und iteriere mit einer For-Each-Schleife darüber.
Einen Anhang holen:
| Feld | Wert |
|---|---|
| Anfragemethode | GET |
| Anfrage-URL | /messages/{{message.id}}/attachments |
Das Feld contentBytes jedes Anhangs ist Base64 – genau die Form, die der Schritt E-Mail senden für Inline-Anhänge erwartet.
Eine Nachricht als gelesen markieren (braucht Application Mail.ReadWrite):
| Feld | Wert |
|---|---|
| Anfragemethode | PATCH |
| Anfrage-URL | /messages/{{message.id}} |
| Anfragetext | { "isRead": true } |
Als das Postfach senden (braucht Application Mail.Send):
| Feld | Wert |
|---|---|
| Anfragemethode | POST |
| Anfrage-URL | /sendMail |
| Anfragetext | { "message": { "subject": "{{doc.no}} verarbeitet", "body": { "contentType": "HTML", "content": "<p>Erledigt.</p>" }, "toRecipients": [ { "emailAddress": { "address": "{{customer.email}}" } } ] } } |
Setze bei jeder Anfrage mit Text den Header Content-Type: application/json. Auf sendMail antwortet Graph mit 202 Accepted und leerem Text.
Pflege
- Secret rotieren, bevor es abläuft: neues Secret in der App-Registrierung erzeugen, den Wert in die Anmeldedaten eintragen, speichern. Flows übernehmen es beim nächsten Lauf; danach kannst du das alte Secret in Entra löschen.
- Postfach ergänzen, wenn du über eine Gruppe begrenzt hast: Postfach in die Gruppe aufnehmen. In Entra und in AutoFlow ändert sich nichts – erweitere aber die Basis-URL der Anmeldedaten oder lege zweite Anmeldedaten an, damit die Allow-List die neue Adresse nicht blockiert.
- App stilllegen: App-Registrierung löschen. Exchange entfernt den Verweis auf den Dienstprinzipal und dessen Rollenzuweisungen automatisch; der Verwaltungsbereich bleibt stehen und lässt sich mit
Remove-ManagementScopelöschen.
Fehlersuche
| Was du siehst | Was meist dahintersteckt |
|---|---|
Test scheitert am Token-Endpunkt mit invalid_client | Das Client-Secret ist falsch, abgelaufen, oder du hast die Geheimnis-ID statt des Werts kopiert. |
Test scheitert mit unauthorized_client oder AADSTS700016 | Client-ID oder Mandanten-ID in der Token-URL passen nicht zur App. |
403 mit ErrorAccessDenied | Das Token stimmt, aber Exchange lässt die App nicht in dieses Postfach. Prüfe die Adresse mit Test-ServicePrincipalAuthorization – meist trifft der Bereichsfilter nicht, oder die Änderung steckt noch im Cache. |
403 mit Authorization_RequestDenied | Die App hat für diesen Aufruf überhaupt keine Berechtigung. Prüfe, ob die zugewiesene Rolle die Operation abdeckt – Lesen ist nicht Schreiben, und Schreiben ist nicht Senden. |
404 mit ResourceNotFound oder MailboxNotEnabledForRESTAPI | Die Adresse in der URL führt zu keinem Exchange-Online-Postfach: Tippfehler, ein E-Mail-Kontakt statt eines Postfachs, oder ein Postfach, das noch lokal liegt. |
| Die Anfrage wird ohne HTTP-Status abgewiesen | Die URL des Schritts passt nicht zur Basis-URL der Anmeldedaten. Vergleiche Zeichen für Zeichen – ein abschließender / oder eine andere Postfachadresse genügt. |
| Die App erreicht Postfächer, die sie nicht erreichen sollte | Auf der App-Registrierung liegen noch tenantweite Graph-Berechtigungen. Entferne sie unter API-Berechtigungen; der Exchange-Bereich kann sie nicht überstimmen. |
Siehe auch
- AutoFlow-Anmeldedaten – Speicher für Anmeldedaten, Allow-List der Basis-URLs und Umgang mit Geheimnissen.
- Schritt HTTP-Anfrage – der Schritt, der den Aufruf macht.
- Schritt E-Mail senden – Versand über die Mailkonten von Business Central, wenn es Graph gar nicht braucht.