> For the complete documentation index, see [llms.txt](https://docs.enginsight.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enginsight.com/docs/knowledge-base/konfiguration/wie-richte-ich-einen-enginsight-e-mail-server-fur-microsoft-365-uber-oauth2-ein.md). # Wie richte ich einen Enginsight E-Mail-Server für Microsoft 365 über OAuth2 ein? Die Einrichtung eines E-Mail-Servers in Enginsight ist notwendig, damit du bspw. E-Mails über das Zurücksetzen deines Passworts oder Benachrichtigungen über Alarme erhalten kannst. Der E-Mail-Server wird in der Enginsight Plattform unter **Einstellungen** → [E-Mail-Server](https://docs.enginsight.com/docs/manual/administration/einstellungen/email-server) konfiguriert. Wenn du einen E-Mail-Server für Microsoft 365 über OAuth2 konfigurieren möchtest, musst du zunächst in Microsoft Entra ID eine neue Anwendung registrieren, ihr die nötigen Berechtigungen erteilen und sie anschließend in Exchange Online für das sendende Postfach registrieren. Im folgenden Artikel zeigen wir dir, welche Schritte du dafür vornehmen musst. *** ## Voraussetzungen * Ein sendendes Exchange Online-Postfach, z.B. **, das gemäß den Vorgaben von Microsoft bereitgestellt und lizenziert ist. * Die Enginsight Plattform muss `login.microsoftonline.com` und `smtp.office365.com` per HTTPS erreichen können. Bei On-Premises-Installationen muss dieser ausgehende Datenverkehr in der Firewall bzw. im Proxy freigegeben sein. Eine funktionierende DNS-Auflösung und TLS sind ebenfalls Voraussetzung. * Administratorrechte, um die Anwendung in Microsoft Entra ID zu registrieren, die mandantenweite Administratorzustimmung zu erteilen sowie Service-Principals und Postfachberechtigungen in Exchange Online zu verwalten. *** ## Konfigurationen im Microsoft Entra ID-Portal {% stepper %} {% step %} ### Microsoft Entra Admin Center öffnen 1. Öffne `https://entra.microsoft.com` in einem Browser. Alternativ kannst du `https://portal.azure.com` öffnen und nach **Microsoft Entra ID** suchen. Die Seiten sind identisch. 2. Melde dich mit dem Administrator-Konto an. 3. Wenn du Zugriff auf mehrere Tenants (Mandanten) hast, nutze das **Einstellungen**-Symbol (:gear:) im oberen Menü, um zum Tenant zu wechseln, den du anbinden möchtest. Der Tenant-Name wird rechts oben angezeigt. {% endstep %} {% step %} ### Neue Anwendung registrieren Registriere Enginsight als neue Anwendung in Microsoft Entra-ID. Mehr Informationen hierzu findest du in der [offiziellen Hersteller-Dokumentation](https://learn.microsoft.com/de-de/entra/identity-platform/quickstart-register-app). {% hint style="warning" %} **Bitte beachte**: Enginsight übernimmt für Inhalte und Aktualität der Dokumentation von Drittanbietern keine Gewähr. {% endhint %} Gib dabei folgende Werte ein: * **Name**: Der Name ist frei wählbar und wird nur im Microsoft Entra ID-Portal angezeigt. Wir schlagen einen aussagekräftigen Namen wie *Enginsight E-Mail* vor. * **Unterstützte Kontotypen**: Wähle als unterstützten Kontotyp die Option **Nur einzelner Mandant – \** aus. In älteren Ansichten lautet diese Option **Nur Konten in diesem Organisationsverzeichnis**. * **Umleitungs-URIs**: Lasse dieses Feld leer. {% endstep %} {% step %} ### Client-ID und Tenant-ID erhalten Nach der Registrierung gelangst du auf die Übersichtsseite der neuen Anwendung. Hier findest du sowohl die **Client-ID** (auch **Application ID** oder **Anwendungs-ID**) als auch die **Tenant-ID** (auch **Directory ID** oder **Mandanten-ID**). Diese Informationen benötigst du später beim [Konfigurieren des E-Mail-Servers](#konfigurieren-des-e-mail-servers-in-enginsight) in der Enginsight Plattform. Die Client-ID benötigst du zudem für die [Registrierung der Anwendung in Exchange Online](#anwendung-in-exchange-online-registrieren). {% endstep %} {% step %} ### Client-Secret erstellen 1. Erstelle für die neue Anwendung ein **Client-Secret** (auch **App-Geheimnis**). Mehr Informationen hierzu findest du in der [offiziellen Hersteller-Dokumentation](https://learn.microsoft.com/de-de/entra/identity-platform/how-to-add-credentials?tabs=client-secret). {% hint style="warning" %} **Bitte beachte**: Enginsight übernimmt für Inhalte und Aktualität der Dokumentation von Drittanbietern keine Gewähr. {% endhint %} Gib dabei folgende Werte ein: * **Beschreibung**: Die Beschreibung ist frei wählbar. * **Läuft ab**: Gib eine Laufzeit für das Client-Secret an, wobei Microsoft Entra ID maximal 24 Monate erlaubt. Wähle die längste Laufzeit, die deine Sicherheitsrichtlinie zulässt, und notiere dir das Ablaufdatum. {% hint style="danger" %} **Bitte beachte**: Wenn das Client-Secret abläuft, stoppt die Synchronisierung des Enginsight SIEM mit Entra ID mit dem Fehler `AADSTS7000222` / `invalid_client`. In diesem Fall musst du das [Client-Secret austauschen](#austausch-eines-abgelaufenen-client-secrets). {% endhint %} 2. Kopiere das Client-Secret und speichere es dir an einem sicheren Ort ab. {% hint style="warning" %} **Bitte beachte**: Verwende den **Wert** (**Value**) des Client-Secrets. Die **Geheimnis-ID** (**Secret ID**) funktioniert an dieser Stelle nicht. {% endhint %} {% hint style="danger" %} **Bitte beachte**: Wenn du in Microsoft Entra-ID ein Client-Secret hinzufügst, wird dieses direkt nach der Erstellung **nur einmal angezeigt und dann nie wieder**. Achte also darauf, dass du dir dein Client-Secret sofort nach der Erstellung notierst. {% endhint %} {% endstep %} {% step %} ### API-Berechtigung erteilen Nun musst du der neuen Anwendung Berechtigungen für den Zugriff auf die **Office 365 Exchange Online API** erteilen. Mehr Informationen hierzu findest du auch in der [offiziellen Hersteller-Dokumentation](https://learn.microsoft.com/de-de/entra/identity-platform/quickstart-configure-app-access-web-apis). {% hint style="warning" %} **Bitte beachte**: Enginsight übernimmt für Inhalte und Aktualität der Dokumentation von Drittanbietern keine Gewähr. {% endhint %} Nimm folgende Schritte vor: 1. Navigiere zum Menüpunkt **API-Berechtigungen**. 2. Klicke auf **Berechtigung hinzufügen**. 3. Wähle **Office 365 Exchange Online** aus. 4. Wähle die Option **Anwendungsberechtigungen** aus. Mit Anwendungsberechtigungen kann Enginsight als Dienst ohne angemeldeten Benutzer agieren. 5. Nutze das Suchfeld und wähle die Berechtigung `SMTP.SendAsApp` aus. 6. Klicke auf **Berechtigungen hinzufügen**. 7. Klicke auf **Administratorzustimmung für \ erteilen** und bestätige mit **Ja**. 8. Klicke auf **Aktualisieren** und prüfe die Spalte **Status**. Hier muss jede Zeile ein grünes Häkchen und **für \ erteilt** anzeigen. #### Berechtigung `SMTP.SendAsApp` wird nicht angezeigt Wenn die Berechtigung `SMTP.SendAsApp` nicht angezeigt wird, überprüfe folgendes: * Stelle sicher, dass du dich unter **Von meiner Organisation verwendete APIs** → **Office 365 Exchange Online** befindest. Eine Suche in **Microsoft Graph** zeigt andere E-Mail-Berechtigungen an. * Stelle sicher, dass du **Anwendungsberechtigungen** ausgewählt hast. Die **delegierte Berechtigung** `SMTP.Send` gehört zu einem anderen, benutzerdelegierten Ablauf. * Wird **Office 365 Exchange Online** nicht angezeigt, prüfe den ausgewählten Tenant und deine Berechtigung, API-Berechtigungen hinzuzufügen. Gegebenenfalls muss ein Administrator diesen Schritt durchführen. {% endstep %} {% endstepper %} *** ## Konfigurationen in Exchange Online {% stepper %} {% step %} ### Benötigte IDs aus Microsoft Entra ID erhalten Für die weitere Konfiguration benötigst du folgende Werte: * Die **Client-ID** (auch **Application ID** oder **Anwendungs-ID**) aus [Schritt 3](#client-id-und-tenant-id-erhalten) weiter oben. Diese entspricht in PowerShell der `$appID` . * Die **Objekt-ID der Unternehmensanwendung**. Du findest sie in Microsoft Entra ID unter **Entra ID** → **Unternehmensanwendungen** → **\** → **Übersicht** → **Objekt-ID**. Diese entspricht in PowerShell der `$enterpriseObjectId` . {% hint style="danger" %} **Bitte beachte**: Bei der **Objekt-ID der Unternehmensanwendung** handelt es sich ***nicht*** um die Objekt-ID der registrierten Anwendung, die du unter **App-Registrierungen** → **\** → **Übersicht** → **Objekt-ID** findest! Verwendest du die Objekt-ID aus **App-Registrierungen**, kann `New-ServicePrincipal` mit dem Fehler `AADServicePrincipalNotFound` fehlschlagen. {% endhint %} {% endstep %} {% step %} ### Anwendung in Exchange Online registrieren Führe die folgenden Befehle in der Exchange Online PowerShell als Exchange-Administrator aus. {% hint style="info" %} Vergiss dabei nicht, die folgenden Platzhalter entsprechend zu ersetzen: * ``; z.B. ** * `` * `` * ``; z.B. ** {% endhint %} 
Install-Module ExchangeOnlineManagement -Scope CurrentUser
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName "<AdminBenutzername>"

$appId = "<ClientID>"
$enterpriseObjectId = "<ObjektIDUnternehmensanwendung>"
$mailbox = "<SendendesEmailPostfach>"

$exoSp = Get-ServicePrincipal | Where-Object { $_.AppId -eq $appId }

if (-not $exoSp) {
  New-ServicePrincipal `
    -AppId $appId `
    -ObjectId $enterpriseObjectId `
    -DisplayName "Enginsight Email"

  $exoSp = Get-ServicePrincipal | Where-Object { $_.AppId -eq $appId }
}

if (@($exoSp).Count -ne 1) {
  throw "Expected exactly one Exchange service principal."
}

$exoSp | Format-List DisplayName,AppId,ObjectId,Identity
Eine erfolgreiche Registrierung muss Folgendes zurückgeben: ``` DisplayName : Enginsight Email AppId : ObjectId : Identity : ``` {% endstep %} {% step %} ### Zugriff auf das sendende Postfach erteilen und prüfen {% hint style="warning" %} **Bitte beacht**e: Verwende ab diesem Punkt `$exoSp.Identity` für die Befehle zu den Postfachberechtigungen. Die Objekt-ID der Unternehmensanwendung kannst du nur dann als Trustee für das Postfach verwenden, wenn sie mit der zurückgegebenen Exchange-Identity übereinstimmt. {% endhint %} 1. Erteile dem Exchange Service Principal mit folgenden Befehlen die Berechtigungen `FullAccess` und `SendAs` für das sendende Postfach: ``` Add-MailboxPermission -Identity $mailbox ` -User $exoSp.Identity -AccessRights FullAccess Add-RecipientPermission -Identity $mailbox ` -Trustee $exoSp.Identity -AccessRights SendAs ``` 2. Prüfe mit folgenden Befehlen, ob die Berechtigungen korrekt erteilt wurden: ``` Get-MailboxPermission -Identity $mailbox -User $exoSp.Identity Get-RecipientPermission -Identity $mailbox -Trustee $exoSp.Identity ``` Die Ausgabe sollte folgende Werte enthalten: ``` Get-MailboxPermission ... AccessRights : {FullAccess} IsInherited : False Deny : False Get-RecipientPermission ... AccessRights : {SendAs} Inherited : False ``` {% endstep %} {% step %} ### SMTP AUTH prüfen 1. Prüfe mit folgenden Befehlen, ob SMTP AUTH für die Organisation und das sendende Postfach aktiviert ist: ``` Get-TransportConfig | Format-List SmtpClientAuthenticationDisabled Get-CASMailbox -Identity $mailbox | Format-List SmtpClientAuthenticationDisabled ``` Folgende Werte können ausgegeben werden: | Wert | Bedeutung | | ---------------------------- | -------------------------------------------------------- | | `False` | SMTP AUTH ist aktiviert. | | `True` | SMTP AUTH ist deaktiviert. | | Leer / `$null` beim Postfach | Das Postfach übernimmt die Einstellung der Organisation. | 2. Aktiviere mit folgenden Befehlen SMTP AUTH bei Bedarf gezielt für das sendende Postfach und prüfe die Aktivierung erneut: ``` Set-CASMailbox -Identity $mailbox ` -SmtpClientAuthenticationDisabled $false Get-CASMailbox -Identity $mailbox | Format-List SmtpClientAuthenticationDisabled ``` Alternativ kannst du SMTP AUTH im Microsoft 365 Admin Center unter **Benutzer** → **Aktive Benutzer** → **\** → **E-Mail** → **E-Mail-Apps verwalten** → **Authentifiziertes SMTP** aktivieren. {% hint style="warning" %} **Bitte beachte**: Sicherheitsstandards (Security Defaults) und weitere Sicherheitsrichtlinien des Tenants können SMTP AUTH ebenfalls beeinflussen. Aktiviere die Standardauthentifizierung (Basic Authentication) ***nicht*** als Workaround. {% endhint %} {% endstep %} {% endstepper %} *** ## Konfigurieren des E-Mail-Servers in Enginsight Nachdem du alle Einstellungen in Microsoft Entra ID und Exchange Online vorgenommen hast, kannst du den E-Mail-Server in der Enginsight Plattform konfigurieren. Nimm dazu folgende Schritte vor: {% stepper %} {% step %} Navigiere in der Enginsight Plattform zu **Einstellungen** → **E-Mail-Server** und klicke auf **Konfiguration hinzufügen**. Folge dem Einstellungsassistenten. {% endstep %} {% step %} Wähle **Microsoft 365** als **Anbieter** aus und klicke auf **Weiter**. {% endstep %} {% step %} Gib in der Ansicht **Verbindung** folgende Werte ein:
Feld in EnginsightWert
HostLasse den standardmäßig angegebenen Wert smtp.office365.com, wie er ist.
PortLasse den standardmäßig angegebenen Port 587, wie er ist.
VerschlüsselungLasse die standardmäßig ausgewählte Verschlüsselung STARTTLS, wie sie ist.
Zertifikatsprüfung überspringenLasse die Checkbox deaktiviert.
AuthentifizierungsmethodeLasse die standardmäßig ausgewählte Verschlüsselung OAuth2, wie sie ist.
Mandanten-IDGib die Tenant-ID (Verzeichnis-ID (Mandant)) des Microsoft 365-Mandanten an.
Client-IDGib die Client-ID der in Microsoft Entra ID registrierten Anwendung an.
Client-SecretGib das Client-Secret an, das du in Microsoft Entra ID für die neue Anwendung erstellt hast.
PostfachGib das sendende Postfach aus Microsoft Exchange Online ein, z.B. notifications@contoso.com.
Absender

Gib den Absender der E-Mails, die über den E-Mail-Server versendet werden, im Format "Enginsight" <no-reply@example.com> an.

Bitte beachte: Trage für den ersten Verbindungstest in Enginsight dieselbe Adresse als Postfach und als Absender ein. Eine abweichende Absenderadresse benötigt eine eigene SendAs-Berechtigung in Microsoft Exchange Online.

{% endstep %} {% step %} Klicke auf **Verbindung testen**. Es öffnet sich ein entsprechendes Fenster mit folgender Zusatzinformation: {% hint style="info" %} Der Test erfolgt mit den Verbindungs- und Authentifizierungsdaten, die du zuvor angegeben hast, auch wenn du diese noch nicht gespeichert hast. Wenn du Zugangsdaten bei deinem Anbieter neu angelegt hast, kann es mitunter einige Minuten dauern, bis diese greifen. Sollte der Verbindungstest daher fehlschlagen, wiederhole ihn etwas später erneut. {% endhint %} {% endstep %} {% step %} Klicke auf **Verbindung testen**, um den Verbindungstest zu starten und eine Test-E-Mail an die in deinem Benutzerkonto angegebene E-Mail-Adresse zu senden. {% hint style="danger" %} **Bitte beachte**: Ein erfolgreicher Test speichert die Konfiguration nicht. Verlässt du diese Ansicht ohne zu speichern, sind alle vorgenommenen Einstellungen verloren! {% endhint %} {% endstep %} {% step %} Wenn der Test erfolgreich ist, kannst du optional **Erweiterte Einstellungen** vornehmen, z.B. um ein **Verbindungslimit** und ein **Versandlimit** festzulegen. {% hint style="warning" %} **Bitte beachte**: Microsoft erlaubt maximal 3 gleichzeitige Verbindungen. {% endhint %} {% endstep %} {% step %} Klicke auf **Weiter**, um in der Übersicht eine Zusammenfassung aller Einstellungen zu erhalten und diese noch einmal zu überprüfen. {% endstep %} {% step %} Klicke auf **Änderungen speichern**, um deine Einstellungen zu übernehmen. {% endstep %} {% endstepper %} *** ## Austausch eines abgelaufenen Client-Secrets {% hint style="info" %} Wir empfehlen, eine Kalendererinnerung einige Wochen vor dem Ablaufdatum des Client-Secrets einzurichten. Das Microsoft Entra ID-Portal zeigt das Ablaufdatum in der Client-Secrets-Liste an und markiert abgelaufene Secrets rot. {% endhint %} Wenn das Client-Secret abgelaufen ist, musst du folgende Schritte vornehmen: {% stepper %} {% step %} Erstelle im Microsoft Entra ID-Portal ein neues Client-Secret für die betroffene Anwendung. {% endstep %} {% step %} Navigiere in der Enginsight Plattform zu **Einstellungen** → **E-Mail-Server** und klicke auf **Bearbeiten**. {% endstep %} {% step %} Füge das neue **Client-Secret** ein. {% endstep %} {% step %} Klicke auf **Verbindung testen**. {% endstep %} {% step %} Klicke auf **Änderungen speichern**, wenn der Test erfolgreich war. Warte, bis die Synchronisation zwischen Microsoft Entra ID und Enginsight erfolgreich abgeschlossen ist. {% endstep %} {% step %} Navigiere zurück zum Microsoft Entra ID-Portal und lösche das alte Client-Secret. {% endstep %} {% endstepper %} *** ## Troubleshooting | Fehler | Ursache | Behebung | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SMTP.SendAsApp` wird nicht gefunden | Die Berechtigung wurde in der falschen API gesucht. | Navigiere zu **Berechtigung hinzufügen** → **Von meiner Organisation verwendete APIs** → **Office 365 Exchange Online** → **Anwendungsberechtigungen**. Suche nicht in Microsoft Graph. | | `AADServicePrincipalNotFound` bei `New-ServicePrincipal` | Häufig wurde die falsche Objekt-ID verwendet. | Verwende die Objekt-ID aus **Unternehmensanwendungen** → **Enginsight Email** → **Übersicht**. Die Objekt-ID aus **App-Registrierungen** gehört zu einem anderen Objekt. | | `AADSTS7000215` / `invalid client secret` | Das Client-Secret ist falsch. Dies kann z.B. der Fall sein, wenn statt des **Werts** (**Value**) die **Geheimnis-ID** kopiert wurde. | Erstelle ein neues Client-Secret und kopiere den korrekten Wert. | | `AADSTS7000222` / abgelaufenes Client-Secret | Das Client-Secret ist abgelaufen. | Tausche das Client-Secret [wie zuvor beschrieben](#austausch-eines-abgelaufenen-client-secrets) aus. | | `AADSTS700016` / Anwendung nicht gefunden | Die Client-ID gehört nicht zu diesem Tenant oder die Tenant-ID ist falsch. | Überprüfe die Tenant-ID und die Client-ID im Microsoft Entra ID-Portal erneut. | | `535` / `authentication unsuccessful` | Die SMTP-Authentifizierung ist fehlgeschlagen. | Prüfe die Administratorzustimmung für `SMTP.SendAsApp`, die Token-Claims, den Exchange Service Principal, die Postfachberechtigungen und SMTP AUTH. | | `5.7.60` / `SendAs denied` | Für die Absenderadresse fehlt die Berechtigung `SendAs`. | Prüfe die Berechtigung `SendAs` für die exakte Absenderadresse. Nutze in Enginsight dieselbe Adresse für **Postfach** und **Absender**. | | [430 4.2.0 STOREDRV](#fehler-430-4.2.0-storedrv) / `Cannot open mailbox` | Exchange Online kann das Postfach im Kontext der Anwendung nicht öffnen. | Prüfe die Berechtigung `FullAccess`, die GUID des Postfachs, SMTP AUTH und die Verteilung der Berechtigungen. | | Timeout / `ENOTFOUND` / TLS-Fehler | Die Netzwerkverbindung zu Microsoft Entra ID oder Exchange Online ist gestört. | Prüfe DNS, HTTPS zu `login.microsoftonline.com`, TCP-Port **587** zu `smtp.office365.com` und die Zertifikatsprüfung. | ### Fehler `430 4.2.0 STOREDRV` Typische Fehlermeldungen sind: `STOREDRV; mailbox logon failure; Cannot open mailbox; AuthenticationContext has no rights on this session`. | Befund | Vorgehen | | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Die OAuth-Authentifizierung war möglicherweise bereits erfolgreich. | Prüfe, ob `AUTH XOAUTH2` den Code `235` zurückgegeben hat. In diesem Fall wurde das Token akzeptiert und der Fehler tritt erst bei der Übermittlung an das Postfach auf. | | Der Postfachspeicher kann das Postfach im Kontext der Anwendung nicht öffnen. | Prüfe `FullAccess`, das exakte Postfach und `SendAs` und warte die Verteilung der Berechtigungen ab. | ### GUID des Postfachs prüfen Prüfe mit folgendem Befehl, ob Exchange Online das erwartete Postfach öffnet: ``` Get-Mailbox -Identity $mailbox | Format-List PrimarySmtpAddress,RecipientTypeDetails,ExchangeGuid ``` Enthält eine SMTP-Fehlermeldung eine `mailboxGuid`, vergleiche sie mit der `ExchangeGuid`. Stimmen beide GUIDs überein, wird das erwartete Postfach geöffnet. ### Anzahl der Exchange Service Principals prüfen Für die Client-ID darf genau ein Exchange Service Principal existieren. Prüfe dies mit folgenden Befehlen: ``` $allSp = @(Get-ServicePrincipal | Where-Object { $_.AppId -eq $appId }) $allSp | Format-List DisplayName,AppId,ObjectId,Identity "Count: $($allSp.Count)" ``` Die erwartete Anzahl ist `1`. ***