Orimize Academy
Portal öffnen
Integrationen IIC

Outlook App-only Authentifizierung

Microsoft-Entra-App-Registrierung mit Client Credentials für den Lesezugriff auf ein Outlook-Postfach.

Aktualisiert: 2026-08-13 12 Minuten Lesezeit Zielgruppe: Administratoren

Zweck

Für den Eingang von Rechnungen aus einem Outlook-Postfach wird eine Microsoft-Entra-App-Registrierung mit App-only Client Credentials verwendet. Es gibt keinen Benutzer-Login. Die Anwendung holt ein Token und liest das angegebene Postfach über Microsoft Graph.

Offizielle Referenzen:

Voraussetzungen

  • Zugriff auf den Microsoft-Entra-Tenant des E-Mail-Kontos.
  • Rolle zum Erstellen von App-Registrierungen, zum Beispiel Application Administrator oder Cloud Application Administrator.
  • Ein Administrator, der Microsoft-Graph-Application-Permissions per Admin Consent freigeben darf.
  • Zielpostfach, zum Beispiel rechnung@example.com oder der SMTP-Alias einer Shared Mailbox.

1. App Registration anlegen

  1. Öffne Microsoft Entra App registrations.
  2. Wähle New registration.
  3. Setze einen Namen, zum Beispiel orimize-outlook-invoice-input.
  4. Wähle Accounts in this organizational directory only.
  5. Lasse Redirect URI leer. Es wird kein Benutzer-Login verwendet.
  6. Wähle Register.

Danach notieren:

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

2. Client Secret erstellen

  1. Öffne in der App Registration Certificates & secrets.
  2. Wähle New client secret.
  3. Vergib eine Beschreibung, zum Beispiel orimize-outlook.
  4. Wähle eine Laufzeit passend zur Secret-Rotation.
  5. Kopiere direkt nach dem Erstellen den Secret-Wert aus der Spalte Value.

Der Wert wird nur einmal angezeigt. Benötigt wird dieser Value, nicht die Secret-ID.

3. Microsoft Graph API Permissions setzen

  1. Öffne API permissions.
  2. Wähle Add a permission.
  3. Wähle Microsoft Graph.
  4. Wähle Application permissions, nicht Delegated permissions.
  5. Füge je nach Nachbearbeitung hinzu:
    • Nur Lesen ohne Änderung der Mail: Mail.Read
    • Als gelesen markieren oder in einen Ordner verschieben: Mail.ReadWrite
  6. Entferne unnötige Default-Permissions, falls vorhanden.
  7. Wähle Grant admin consent for ….

Ohne Admin Consent schlägt der Zugriff später mit 403 fehl.

4. Zugriff auf das Zielpostfach einschränken

Application-Permissions für Mail können ohne Einschränkung tenantweit auf Postfächer wirken. In Produktion sollte die App nur die wirklich benötigten Mailboxen erreichen.

Empfohlen:

  1. Erstelle in Microsoft 365 / Exchange Online eine mail-enabled Security Group für erlaubte Postfächer.
  2. Füge das Zielpostfach dieser Gruppe hinzu.
  3. Erstelle eine Exchange-Online Application Access Policy für die App-ID.

Siehe Limiting application permissions to specific Exchange Online mailboxes.

Benötigte Angaben

Diese Werte entstehen aus der Entra-Einrichtung und dem Zielpostfach. Sie werden für die App-only-Anbindung benötigt:

AngabeHerkunft
Verzeichnis-ID (tenant_id)Directory (tenant) ID der App Registration
Anwendungs-ID (client_id)Application (client) ID der App Registration
Client Secret (client_secret)Secret-Wert aus Certificates & secrets, Spalte Value
Postfach (user_email)SMTP-Adresse des Zielpostfachs
Ordner (mail_folder)inbox oder der sichtbare Anzeigename des Mailordners
Nur ungelesene Mails (only_unread)true oder false
Maximale Nachrichten pro Lauf (max_messages_per_run)zum Beispiel 50
Nachbearbeitung (post_process_action)none, mark_read oder move
Zielordner (move_to_folder)nur bei post_process_action=move, Anzeigename des Zielordners

Die Anwendung authentifiziert sich mit Client Credentials gegen https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token und dem Scope https://graph.microsoft.com/.default. Anschließend wird das Postfach über users/{user_email} gelesen. Die E-Mail-Adresse muss deshalb exakt die SMTP-Adresse des Postfachs sein.

Verarbeitet werden Nachrichten mit PDF-Anhängen. Jede PDF wird als eigene Eingangsrechnung übernommen.

Funktionstest

  1. Sende eine Test-Mail an das konfigurierte Postfach.
  2. Füge eine kleine PDF-Datei als Anhang hinzu.
  3. Stelle sicher, dass die Mail im konfigurierten Ordner liegt.
  4. Prüfe, ob die PDF übernommen wird und ob die Nachbearbeitung (mark_read oder move) wie vorgesehen greift.

Bei only_unread=true wird eine bereits gelesene Test-Mail nicht erneut verarbeitet. Bei post_process_action=none bleibt die Mail auffindbar.

Troubleshooting

  • 401 / invalid_client: tenant_id, client_id oder client_secret falsch. Secret-Wert statt Secret-ID verwenden.
  • 403 / Authorization_RequestDenied: Admin Consent fehlt oder falscher Permission-Typ. Es müssen Application permissions sein, nicht Delegated permissions.
  • 403 / ErrorAccessDenied: App hat keine Mail-Permissions oder eine Application Access Policy erlaubt das Postfach nicht.
  • 404 Mail folder not found: mail_folder oder move_to_folder muss inbox oder der sichtbare Anzeigename des Ordners sein.
  • Keine Nachrichten gefunden: only_unread=true, falscher Ordner, Mail hat keine Anhänge oder keine PDF-Anhänge.