eTASK SMTP-Mailversand mit OAuth 2.0 einrichten

In diesem Artikel

1. Ziel dieser Anleitung

2. Voraussetzungen

3. Übersicht der Einrichtungsschritte

4. Schritt 1: App-Registrierung in Azure erstellen

5. Schritt 2: Client Secret (Geheimer Clientschlüssel) erstellen

6. Schritt 3: API-Berechtigungen konfigurieren

7. Schritt 4: Objekt-ID der Enterprise Application ermitteln

8. Schritt 5: Exchange Online Konfiguration via PowerShell

9. Schritt 6: eTASK Portal-Konfiguration

10. Schritt 7: OAuth-Authentifizierung aktivieren

11. Schritt 8: Testmail versenden

12. Fehlersuche

13. Weitere wichtige Informationen

14. Zusammenfassung der benötigten Werte

15. Weitere Ressourcen

Ziel dieser Anleitung

Diese Anleitung zeigt Ihnen, wie Sie den E-Mail-Versand in eTASK auf OAuth 2.0 Authentifizierung umstellen. Dies ist notwendig, da Microsoft die Basic SMTP Authentifizierung (Username/Passwort) schrittweise abschaltet.

Voraussetzungen

Bevor Sie mit der Einrichtung beginnen, stellen Sie sicher, dass:

• ✅ Sie über Administratorrechte im eTASK FM-Portal verfügen

• ✅ Sie Zugriff auf das Azure Portal (Microsoft Entra ID) haben

• ✅ Sie über globale Administrator-Rechte in Microsoft 365 verfügen

• ✅ PowerShell mit Exchange Online Management-Modul verfügbar ist

• ✅ Eine dedizierte E-Mail-Adresse für den SMTP-Versand existiert (z.B. smtp@ihredomain.de)

Übersicht der Einrichtungsschritte

Die Einrichtung erfolgt in drei Hauptbereichen:

1. Azure App-Registrierung: Erstellen einer Anwendungsregistrierung für OAuth

2. Exchange Online Konfiguration: Vergabe der Berechtigungen via PowerShell

3. eTASK Portal-Konfiguration: Hinterlegen der OAuth-Parameter

Schritt 1: App-Registrierung in Azure erstellen

Ziel: Eine Anwendungsregistrierung in Microsoft Entra ID (Azure AD) erstellen, die OAuth-Token für den SMTP-Versand ausstellen kann.

Vorgehensweise:

1. Melden Sie sich im Azure Portal an: https://portal.azure.com

2. Navigieren Sie zu Microsoft Entra ID (früher Azure Active Directory)

3. Wählen Sie im Menü App-Registrierungen

4. Klicken Sie auf + Neue Registrierung

5. Füllen Sie das Formular aus:

   • Name: z.B. "eTASK SMTP OAuth"

   • Unterstützte Kontotypen: Nur Konten in diesem Organisationsverzeichnis

   • Umleitungs-URI: Leer lassen

6. Klicken Sie auf Registrieren

Wichtige Werte notieren:

Auf der Übersichtsseite der neu erstellten App finden Sie:

• Anwendungs-ID (Client) → Diese benötigen Sie später als <AnwendungsID>

• Verzeichnis-ID (Mandant) → Diese benötigen Sie später als <VerzeichnisID>

Ergebnis: Die App-Registrierung wurde erstellt und Sie haben die Client-ID und Tenant-ID notiert.

Schritt 2: Client Secret (Geheimer Clientschlüssel) erstellen

Ziel: Ein Geheimnis erstellen, mit dem sich eTASK bei Azure authentifizieren kann.

Vorgehensweise:

1. Bleiben Sie in Ihrer App-Registrierung

2. Navigieren Sie im Menü zu Zertifikate & Geheimnisse

3. Klicken Sie auf + Neuer geheimer Clientschlüssel

4. Geben Sie eine Beschreibung ein: z.B. "eTASK SMTP Secret"

5. Wählen Sie eine Gültigkeitsdauer (empfohlen: 24 Monate oder länger)

6. Klicken Sie auf Hinzufügen

Wichtig: Kopieren Sie sofort den Wert des Geheimnisses und speichern Sie ihn sicher.

• Wert → Dies ist Ihr <ClientSecret>

• ⚠️ Dieser Wert wird nur einmal angezeigt und kann nicht erneut abgerufen werden!

Ergebnis: Sie haben ein Client Secret erstellt und sicher gespeichert.

Schritt 3: API-Berechtigungen konfigurieren

Ziel: Der App die Berechtigung erteilen, E-Mails im Namen von Postfächern zu senden.

Vorgehensweise:

1. Bleiben Sie in Ihrer App-Registrierung

2. Navigieren Sie zu API-Berechtigungen

3. Klicken Sie auf + Berechtigung hinzufügen

4. Wählen Sie Von meiner Organisation verwendete APIs

5. Suchen Sie nach Office 365 Exchange Online und wählen Sie es aus

6. Wählen Sie Anwendungsberechtigungen (nicht delegierte Berechtigungen)

7. Suchen Sie nach SMTP und aktivieren Sie SMTP.SendAsApp

8. Klicken Sie auf Berechtigungen hinzufügen

9. Wichtig: Klicken Sie auf Administratoreinwilligung für [Ihre Organisation] erteilen

10. Bestätigen Sie mit Ja

Überprüfung: Bei der Berechtigung "SMTP.SendAsApp" sollte jetzt ein grüner Haken unter "Status" erscheinen.

Ergebnis: Die App hat die Berechtigung, E-Mails über SMTP zu versenden.

Schritt 4: Objekt-ID der Enterprise Application ermitteln

Ziel: Die Objekt-ID der Enterprise Application ermitteln, die für die Exchange-Konfiguration benötigt wird.

Vorgehensweise:

1. Bleiben Sie in Ihrer App-Registrierung

2. Auf der Übersichtsseite finden Sie unter dem App-Namen einen Link:
   "Verwaltete Anwendung in lokalem Verzeichnis"

3. Klicken Sie auf diesen Link (Sie wechseln dadurch zur Enterprise Application)

4. Auf der Übersichtsseite der Enterprise Application finden Sie die Objekt-ID

5. Kopieren Sie diese Objekt-ID → Dies ist Ihre <ObjektID>

Hinweis: Die Objekt-ID der Enterprise Application ist nicht identisch mit der Anwendungs-ID aus Schritt 1!

Ergebnis: Sie haben die Objekt-ID der Enterprise Application notiert.

Schritt 5: Exchange Online Konfiguration via PowerShell

Ziel: Die App-Registrierung mit Exchange Online verknüpfen und Berechtigungen auf das SMTP-Postfach vergeben.

Voraussetzung prüfen:

Prüfen Sie, ob das Exchange Online Management-Modul installiert ist:

Get-Module -ListAvailable -Name ExchangeOnlineManagement

Falls nicht installiert, führen Sie als Administrator aus:

Install-Module -Name ExchangeOnlineManagement

Vorgehensweise:

1. Öffnen Sie PowerShell als Administrator

2. Verbinden Sie sich mit Exchange Online:

Connect-ExchangeOnline

Sie werden aufgefordert, sich mit einem globalen Administrator-Konto anzumelden.

3. Erstellen Sie den Service Principal für Ihre App:

New-ServicePrincipal -AppId "<AnwendungsID>" -ServiceId "<ObjektID>"

Ersetzen Sie:

• <AnwendungsID> mit der Anwendungs-ID aus Schritt 1

• <ObjektID> mit der Objekt-ID aus Schritt 4

Beispiel:

New-ServicePrincipal -AppId "12345678-1234-1234-1234-123456789abc" -ServiceId "87654321-4321-4321-4321-abcdef123456"

4. Vergeben Sie die Berechtigung auf das SMTP-Postfach:

Add-MailboxPermission -Identity "<SMTPUSER>" -User "<ObjektID>" -AccessRights FullAccess

Ersetzen Sie:

• <SMTPUSER> mit der E-Mail-Adresse, die für den SMTP-Versand verwendet werden soll (z.B. smtp@etask.de)

• <ObjektID> mit der Objekt-ID aus Schritt 4

Beispiel:

Add-MailboxPermission -Identity "smtp@ihredomain.de" -User "87654321-4321-4321-4321-abcdef123456" -AccessRights FullAccess

5. Beenden Sie die PowerShell-Sitzung:

Disconnect-ExchangeOnline

Ergebnis: Die App-Registrierung ist mit Exchange Online verknüpft und hat Zugriff auf das SMTP-Postfach.

Schritt 6: eTASK Portal-Konfiguration

Ziel: Die OAuth-Parameter im eTASK Portal hinterlegen.

Vorgehensweise:

1. Melden Sie sich als Administrator am eTASK FM-Portal an

2. Navigieren Sie zur Systemkonfiguration (Systemsteuerung → Portal-Optionen → Systemkonfiguration)

3. Suchen Sie nach den folgenden Parametern und setzen Sie diese:

4. Speichern Sie die Konfiguration

Wichtig:

• Die Parameter SMTPOAUTHCLIENTID, SMTPOAUTHCLIENTSECRET und SMTPOAUTHTENANTID sind neue Parameter und müssen ggf. als neue Systemparameter angelegt werden

• Stellen Sie sicher, dass der Parameter SMTPPASSWORD leer bleibt oder entfernt wird, da dieser bei OAuth nicht mehr benötigt wird

Ergebnis: Die OAuth-Konfiguration ist im Portal hinterlegt.

Schritt 7: OAuth-Authentifizierung aktivieren

Ziel: Den OAuth-Modus für den SMTP-Versand aktivieren.

Vorgehensweise:

1. Suchen Sie in der Systemkonfiguration nach dem Parameter SMTPUSEOAUTH

2. Falls der Parameter nicht existiert, legen Sie ihn an

3. Setzen Sie den Wert auf 1 (aktiviert) oder true

4. Speichern Sie die Konfiguration

Hinweis:

• Bei SMTPUSEOAUTH = 1 oder true → OAuth wird verwendet

• Bei SMTPUSEOAUTH = 0 oder false → Basic Authentication (Username/Passwort) wird verwendet

Ergebnis: OAuth-Authentifizierung für SMTP ist aktiviert.

Schritt 8: Testmail versenden

Ziel: Überprüfen, ob der E-Mail-Versand mit OAuth funktioniert.

Vorgehensweise:

1. Navigieren Sie im Portal zu Systemsteuerung → Portal-Optionen → Portal-Verwaltung → Portalsteuerung → Testeinstellungen

2. Klicken Sie auf Testmail senden

3. Geben Sie eine gültige E-Mail-Adresse ein

4. Klicken Sie auf Senden

5. Prüfen Sie, ob die E-Mail ankommt

Bei Erfolg:

• ✅ Sie sollten eine Bestätigungsmeldung sehen

• ✅ Die Testmail sollte im Posteingang ankommen

• ✅ In den E-Mail-Headern sollte OAuth als Authentifizierungsmethode erkennbar sein

Bei Fehler:

• ❌ Prüfen Sie die Fehlermeldung im Portal

• ❌ Kontrollieren Sie alle Parameter in der Systemkonfiguration

• ❌ Überprüfen Sie die Berechtigungen in Azure und Exchange Online

• ❌ Siehe Abschnitt "Fehlersuche" unten

Ergebnis: Der SMTP-Versand mit OAuth funktioniert.

Fehlersuche

Problem: Testmail wird nicht versendet

Mögliche Ursachen und Lösungen:

1. Fehlermeldung: "Authentication failed"

   • Prüfen Sie, ob das Client Secret korrekt kopiert wurde

   • Prüfen Sie, ob das Client Secret abgelaufen ist

   • Erstellen Sie ggf. ein neues Client Secret in Azure

2. Fehlermeldung: "Access denied" oder "Permission denied"

   • Prüfen Sie, ob die API-Berechtigung "SMTP.SendAsApp" erteilt wurde

   • Prüfen Sie, ob die Administratoreinwilligung erteilt wurde

   • Prüfen Sie, ob der Service Principal in Exchange Online erstellt wurde

   • Prüfen Sie, ob die Mailbox-Permission korrekt gesetzt wurde

3. Fehlermeldung: "Invalid tenant"

   • Prüfen Sie, ob die Tenant-ID (Verzeichnis-ID) korrekt ist

   • Stellen Sie sicher, dass Sie die richtige Azure AD Organisation verwenden

4. Fehlermeldung: "Invalid client"

   • Prüfen Sie, ob die Client-ID (Anwendungs-ID) korrekt ist

   • Stellen Sie sicher, dass die App-Registrierung nicht gelöscht wurde

5. Keine Fehlermeldung, aber E-Mail kommt nicht an

   • Prüfen Sie den Spam-Ordner des Empfängers

   • Prüfen Sie die E-Mail-Logs in Exchange Online Admin Center

   • Prüfen Sie, ob die Absenderadresse (MAILFROMADDRESS) korrekt ist

Logs überprüfen

Falls verfügbar, prüfen Sie die eTASK-Logs auf detaillierte Fehlermeldungen:

• Windows Event Log

• eTASK Application Logs

• IIS-Logs

Weitere wichtige Informationen

Client Secret Ablauf

Wichtig: Das Client Secret hat ein Ablaufdatum. Planen Sie rechtzeitig die Erneuerung:

1. Erstellen Sie ca. 1 Monat vor Ablauf ein neues Client Secret in Azure

2. Aktualisieren Sie den Parameter SMTPOAUTHCLIENTSECRET im Portal

3. Testen Sie den E-Mail-Versand

4. Löschen Sie das alte Secret erst nach erfolgreicher Umstellung

Sicherheitshinweise

• ⚠️ Speichern Sie das Client Secret sicher (z.B. in einem Passwort-Manager oder Key Vault)

• ⚠️ Teilen Sie das Client Secret niemals über unsichere Kanäle

• ⚠️ Dokumentieren Sie, wer Zugriff auf die Azure App-Registrierung hat

• ⚠️ Prüfen Sie regelmäßig die Berechtigungen in Azure

Unterschiede zu Basic Authentication

Mit OAuth 2.0:

• ✅ Kein Passwort mehr im Portal hinterlegt

• ✅ Höhere Sicherheit durch Token-basierte Authentifizierung

• ✅ Zentrale Verwaltung der Berechtigungen in Azure

• ✅ Compliance mit Microsoft-Sicherheitsrichtlinien

• ✅ Keine Deaktivierung durch Microsoft bei Sicherheitsupdates

Technische Details

Das OAuth Token wird dabei mit dem Verfahren OAuth 2.0 Client Credentials Grant mittels MSAL (Microsoft Authentication Library) geholt. eTASK verwendet intern die Bibliothek MailKit für den SMTP-Versand mit OAuth-Unterstützung.

Zusammenfassung der benötigten Werte

Zur schnellen Referenz hier alle benötigten Werte:

Weitere Ressourcen

• Microsoft Dokumentation: Authenticate an IMAP, POP or SMTP connection using OAuth

• Microsoft Dokumentation: App-only authentication for unattended applications

Viel Erfolg mit der OAuth-Einrichtung!

Bei Fragen wenden Sie sich bitte an den eTASK Support.