Mailversand über Microsoft 365 mit OAuth einrichten

Exchange Online nimmt E-Mails per SMTP bald nur noch mit OAuth an. SwissMentor meldet sich dafür mit einer Anwendung aus Microsoft Entra an statt mit Benutzername und Passwort. Diese Seite beschreibt die Einrichtung in Microsoft 365. Den Rest übernimmt der Betrieb Ihrer SwissMentor-Installation.

Voraussetzungen

Ein Versandpostfach in Exchange Online, zum Beispiel mailversand@beispiel.ch.
Ein Microsoft-365-Konto Ihrer Organisation mit der Entra-Rolle Globaler Administrator. Damit sind die Schritte in Microsoft Entra und in Exchange Online möglich.

Vorgehen

1. Anwendung registrieren

Im Microsoft Entra Admin Center App registrations > New registration öffnen.
Namen eingeben, bei Supported account types Single tenant only wählen, Redirect URI leer lassen.
Mit Register bestätigen.

Beispiel mit fiktiven Daten: Anwendung in Microsoft Entra registrieren

In der Übersicht die Application (client) ID (1) und die Directory (tenant) ID (2) notieren.

Beispiel mit fiktiven Daten: Client-ID und Tenant-ID in der Übersicht der Anwendung

2. Client-Secret erstellen

Certificates & secrets > New client secret öffnen.
Eine Beschreibung eingeben, zum Beispiel «SwissMentor Mailversand». Bei Expires eine Gültigkeit wählen, zum Beispiel 365 Tage. Mit Add bestätigen.
Den Wert in der Spalte Value (1) sofort kopieren. Später zeigt Entra ihn nicht mehr an.

Die Secret ID (2) wird nicht gebraucht.

Beispiel mit fiktiven Daten: Value und Secret ID eines Client-Secrets

Läuft das Secret ab, werden keine E-Mails mehr versendet. Vorher ein neues erstellen und in SwissMentor ersetzen.

3. Berechtigung erteilen

API permissions > Add a permission öffnen.
Unter APIs my organization uses den Eintrag Office 365 Exchange Online wählen, dann Application permissions > SMTP.SendAsApp (1). Mit Add permissions bestätigen.
Grant admin consent (2) klicken und im Microsoft-Fenster mit Accept bestätigen. Der Status wechselt auf «Granted».

Beispiel mit fiktiven Daten: Berechtigung SMTP.SendAsApp mit erteilter Administratorzustimmung

Add permissions fordert die Berechtigung nur an. Bis zur Zustimmung steht in der Spalte Status «Not granted for …». Ohne diese Zustimmung erhält SwissMentor keinen Zugang. Bleibt der Status nach Refresh unverändert, Grant admin consent erneut klicken. Kontrolle: Unter Enterprise applications > Anwendung > Permissions muss SMTP.SendAsApp aufgeführt sein. Steht dort «No admin consented permissions», fehlt die Zustimmung.

Weitere Berechtigungen braucht es nicht. User.Read (Microsoft Graph) legt Entra bei jeder neuen Anwendung an. Sie wird nicht gebraucht und kann entfernt werden.

4. Anwendung in Exchange Online berechtigen

Unter Enterprise applications die Anwendung öffnen und die Object ID (1) notieren. Es ist nicht dieselbe wie unter App registrations.

Beispiel mit fiktiven Daten: Object ID der Enterprise-Anwendung

Die übrigen Schritte gehen nur in PowerShell:

Install-Module ExchangeOnlineManagement
Connect-ExchangeOnline

$appId    = '<Application (client) ID>'
$objectId = '<Object ID der Enterprise-Anwendung>'
$mailbox  = 'mailversand@beispiel.ch'

New-ServicePrincipal -AppId $appId -ObjectId $objectId -DisplayName 'SwissMentor Mailversand'
$sp = Get-ServicePrincipal -Identity $appId

Add-MailboxPermission -Identity $mailbox -User $sp.Identity -AccessRights FullAccess
Set-CASMailbox -Identity $mailbox -SmtpClientAuthenticationDisabled $false

5. Senden mit der Adresse der Benutzer erlauben

SwissMentor versendet Nachrichten mit der Adresse des Benutzers, der sie schreibt. Nachrichten von Benutzern ohne E-Mail-Adresse gehen über die Einstellung E-Mail Absenderadresse bei nicht-beantwortbaren E-Mails (NoReply) in der Systemkonfiguration. Systemmeldungen gehen über die No-Reply-Adresse der Installation, die der Betrieb setzt. Für jede Absenderadresse ausser dem Versandpostfach braucht die Anwendung die Berechtigung SendAs. Exchange Online vergibt SendAs nur pro Postfach. Fehlt sie, lehnt Exchange die E-Mail mit SendAsDenied ab.

Sind beide No-Reply-Adressen das Versandpostfach selbst, brauchen diese E-Mails kein SendAs. Die Einstellung E-Mail Versand «MAIL FROM» Adresse ersetzt SendAs nicht, Exchange prüft die sichtbare Absenderadresse. Für Nachrichten von Benutzern mit eigener E-Mail-Adresse ist SendAs immer nötig. Wählen Sie dafür Variante 5a oder 5b.

5a. Alle bestehenden Postfächer

Get-Mailbox -RecipientTypeDetails UserMailbox,SharedMailbox -ResultSize Unlimited |
  ForEach-Object { Add-RecipientPermission -Identity $_.Identity -Trustee $sp.Identity -AccessRights SendAs -Confirm:$false }

Gilt nur für Postfächer, die es beim Ausführen gibt. Für neue Mitarbeitende den Befehl erneut ausführen.

5b. Nur bestimmte Postfächer

'noreply@beispiel.ch', 'sekretariat@beispiel.ch', 'anna.muster@beispiel.ch' |
  ForEach-Object { Add-RecipientPermission -Identity $_ -Trustee $sp.Identity -AccessRights SendAs -Confirm:$false }

Benutzer ohne SendAs können aus SwissMentor keine E-Mails versenden. Wurde bisher mit Benutzername und Passwort versendet, zeigt Get-RecipientPermission -Trustee <bisheriges Versandkonto> die Postfächer, für die das bisherige Konto SendAs hatte.

Exchange Online übernimmt FullAccess und SendAs mit Verzögerung, oft 30 bis 60 Minuten. In dieser Zeit wechseln sich erfolgreiche Anmeldungen und Fehler wie mailbox logon failure oder SendAsDenied ab. Bestehende Berechtigungen prüfen Sie mit Get-RecipientPermission -Identity <Postfach> und Get-MailboxPermission -Identity <Postfach>.

6. Werte an den Betrieb übermitteln

Senden Sie dem Betrieb Ihrer SwissMentor-Installation:

Directory (tenant) ID
Application (client) ID
Value des Client-Secrets und das Ablaufdatum
Adresse des Versandpostfachs und die No-Reply-Adresse

Tenant-ID und Client-ID sind nicht vertraulich. Das Client-Secret nicht per E-Mail senden. Tragen Sie es auf secret.swissmentor.com ein und senden Sie nur den erzeugten Link. Der Link kann nur einmal geöffnet werden.

Einrichtung prüfen

Sobald der Betrieb die Umstellung bestätigt, in SwissMentor eine Nachricht an sich selbst senden. Kommt sie als E-Mail an, ist die Einrichtung abgeschlossen.

Kommt keine E-Mail an, zeigt System-Administration > E-Mail Dashboard im Register Fehlgeschlagen die Nachricht mit der Fehlermeldung.

Fehlermeldungen

Meldung	Ursache
`AADSTS700016`	Client-ID falsch, oft die Secret ID statt der Client-ID
`AADSTS7000215`	Client-Secret falsch oder abgelaufen
`AADSTS90002`	Tenant-ID falsch
`535 5.7.3 Authentication unsuccessful`	Schritt 3 oder 4 unvollständig
`430 4.2.0 STOREDRV; mailbox logon failure`	Zugriff auf das Versandpostfach fehlt (Schritt 4) oder ist noch nicht wirksam
`SendAsDenied`	SendAs für die Absenderadresse fehlt (Schritt 5)