Microsoft 365

Microsoft 365 ist eine von zwei Quellarten. Die Anmeldung erfolgt über OAuth2 mit Authorization Code Flow und PKCE als Public Client. Ein Client-Secret wird weder benötigt noch gespeichert; Microsoft-Passwörter fragt die Anwendung nie ab.

Status: Die OAuth-Implementierung ist mit Mocks getestet. Eine echte Anmeldung gegen Microsoft 365 wurde nicht live verifiziert (kein Testkonto, keine Entra-App im Test).

1. App in Entra registrieren

https://entra.microsoft.com öffnen → Anwendungen → App-Registrierungen → Neue Registrierung.
Name frei wählen, z. B. M365 to Exchange Sync (self-hosted).
Kontotypen: Nur Konten in diesem Organisationsverzeichnis für einen Tenant; Konten in einem beliebigen Organisationsverzeichnis nur für mehrere Tenants (dann in der Anwendung tenant_id = organizations).
Im ersten Schritt keine Redirect-URI eintragen.
Registrieren.

Notieren: Anwendungs-(Client-)ID → Feld „Client-ID“ bzw. OAUTH_DEFAULT_CLIENT_ID; Verzeichnis-(Tenant-)ID → Feld „Tenant-ID“. Ein Client-Secret darf nicht angelegt werden.

2. Plattform und Redirect-URI

Authentifizierung → Plattform hinzufügen → Mobile- und Desktopanwendungen. Redirect-URI exakt eintragen, mit dem Port der Anwendung:

http://127.0.0.1:8000/api/v1/oauth/callback

Regeln, die Microsoft durchsetzt:

http:// ist nur für Loopback erlaubt (127.0.0.1, [::1], localhost).
Jede andere Adresse muss https:// sein und exakt registriert werden; Wildcards sind nicht möglich.
Schema, Host, Port und Pfad müssen zeichengenau passen. Ein abweichender Port oder ein zusätzlicher Schrägstrich führt zu AADSTS50011.

Der Wert im Tenant und der Wert in Entra müssen identisch sein. Bei einem Ausweichport entweder APP_PORT fest setzen oder die URI in Entra anpassen.

3. API-Berechtigung

API-Berechtigungen → Berechtigung hinzufügen → APIs, die meine Organisation verwendet → Office 365 Exchange Online → Delegierte Berechtigungen → IMAP.AccessAsUser.All.

Angefragt wird ausschließlich https://outlook.office.com/IMAP.AccessAsUser.All.
openid, profile und offline_access ergänzt MSAL selbst; sie dürfen nicht zusätzlich übergeben werden.
Der Graph-Scope Mail.Read ist kein Ersatz.
Ist der delegierte IMAP-Scope im Picker nicht sichtbar, ist der delegierte Flow für diesen Tenant nicht möglich (Tenant-/Lizenzthema). App-only-Berechtigungen (IMAP.AccessAsApp) unterstützt die Anwendung nicht.

4. Zustimmung erteilen

API-Berechtigungen → Administratorzustimmung für den Tenant erteilen. Ohne Zustimmung erscheint beim Login AADSTS65001. Bei einer Multitenant-Registrierung muss jeder Kunden-Admin zustimmen.

5. Tenant in der Anwendung anlegen

Feld	Bedeutung
Name	freier Anzeigename
Tenant-ID	Verzeichnis-ID (GUID) oder `organizations`
Client-ID	Anwendungs-ID; leer lassen, wenn zentral konfiguriert
Redirect-URI	exakt wie in Entra registriert

Alternativ zentral in der .env: OAUTH_DEFAULT_CLIENT_ID=<client-id>. Ist die zentrale Client-ID gesetzt, dürfen Tenants ohne eigene Client-ID angelegt werden. Fehlen beide, lehnt die Anwendung die Anmeldung mit client_id_required ab.

6. Konto verbinden

Unter „Microsoft-Konten“ ein Konto mit der Postfach-UPN anlegen.
„Mit Microsoft anmelden“ wählen; der Browser öffnet die echte Microsoft-Seite (kein Dialog der Anwendung).
Mit dem Postfachkonto anmelden, MFA durchlaufen, der Berechtigung zustimmen.
Microsoft leitet auf /api/v1/oauth/callback zurück. Die Anwendung tauscht den Code, prüft Tenant und UPN und speichert den Token-Cache verschlüsselt.
Status prüfen: connected, has_token_cache = true.

Angemeldet werden muss das Postfachkonto selbst oder ein Konto mit IMAP-Zugriff darauf. Weicht die angemeldete UPN von der hinterlegten UPN ab, bricht die Anwendung mit oauth_user_mismatch ab und speichert nichts.

7. Erneute Anmeldung

Eine neue Autorisierung ist nötig, wenn das Refresh-Token ungültig wurde — etwa nach Passwortwechsel, widerrufenen Sitzungen oder einer Conditional-Access-Richtlinie. Der Status steht dann auf reauth_required, und Jobs mit diesem Konto starten nicht.

Konto öffnen und „Erneut anmelden“ wählen. Der Flow läuft mit force_reauth=true, damit der Konto-Picker erscheint.
Anmelden und zustimmen, danach Status prüfen: connected, has_token_cache = true.

Eine serverseitige Erneuerung ohne Browser ist über „Token erneuern“ möglich, solange das Refresh-Token gültig ist. Schlägt sie fehl, ist eine erneute Anmeldung nötig.

8. Typische Fehler

Meldung	Ursache	Abhilfe
`AADSTS50011`	Redirect-URI stimmt nicht exakt	URI in Entra und im Tenant angleichen
`AADSTS65001`	Zustimmung fehlt	Administratorzustimmung erteilen
`AADSTS90002`	Tenant-ID unbekannt	Tenant-ID prüfen (`oauth_provider_unavailable`)
`AADSTS70008`	Code abgelaufen oder verbraucht	Anmeldung neu starten
`oauth_user_mismatch`	anderes Konto angemeldet	Konto-UPN korrigieren
`oauth_tenant_mismatch`	Anmeldung in fremdem Tenant	Tenant-ID der App prüfen
`oauth_denied`	Zustimmung verweigert	Vorgang wiederholen und zustimmen
`reauth_required`	Refresh-Token ungültig	Konto erneut autorisieren
IMAP-Test fehlschlägt, OAuth ok	IMAP am Postfach deaktiviert	`Set-CASMailbox -Identity <UPN> -ImapEnabled $true`

Anbieterdetails wie AADSTS… erscheinen nur im Serverprotokoll, nicht im Browser. Netzwerkfehler setzen den Kontostatus nicht auf reauth_required.

9. Sicherheit und Grenzen

Kein Microsoft-Passwort wird abgefragt oder gespeichert; kein Endpunkt gibt Access- oder Refresh-Tokens aus. Der Token-Cache liegt pro Konto getrennt und Fernet-verschlüsselt in der Datenbank. Der Flow-Zustand (State, PKCE-Verifier) liegt nur im Prozessspeicher, ist einmalig verwendbar und läuft nach 10 Minuten ab; ein Neustart macht laufende Anmeldungen ungültig. Die Anwendung ändert die OAuth-Konfiguration nicht selbstständig.

Nicht unterstützt: App-only-/Client-Credentials-Flow (IMAP.AccessAsApp), Device Code Flow (implementiert ist ausschließlich der Authorization Code Flow mit PKCE und fester Redirect-URI) und Zusicherungen zu Shared Mailboxes ohne Berechtigungstest.