Mailversand im Shop via OAuth2

SellSite unterstützt den Mailversand über OAuth2. Damit entfällt die Notwendigkeit, ein Passwort in der Shop-Konfiguration zu hinterlegen. Stattdessen wird ein OAuth2-Token verwendet, das regelmäßig erneuert wird.

Aktuell werden zwei Anbieter unterstützt:

• Gmail – Mailversand per SMTP mit OAuth2-Authentifizierung
• Office 365 (Microsoft 365) – Mailversand über die Microsoft Graph API

Die Einrichtung erfolgt in vier Schritten:

1. OAuth2 Client im Mailserver einrichten
2. OAuth2 Client in SellSite konfigurieren
3. Authentifizierung durchführen
4. Verbindung testen

Richten Sie zunächst einen OAuth2 Client bei Ihrem Mail-Anbieter ein. Die genauen Schritte unterscheiden sich je nach Anbieter. Weiter unten finden Sie detaillierte Anleitungen für Gmail und Office 365.

Folgende Informationen werden im nächsten Schritt für die Konfiguration in SellSite benötigt:

• Client-ID – Identifikator der OAuth2-Anwendung
• Client-Secret – Geheimer Schlüssel der OAuth2-Anwendung

Zusätzlich muss der Mailserver die Möglichkeit bieten, eine Redirect-URL zu autorisieren. Diese URL wird in SellSite generiert und muss im Mailserver hinterlegt werden (siehe Schritt 3).

In SellSite müssen OAuth-Zugangsdaten angelegt und in der Shop-Konfiguration referenziert werden:

1. Rufen Sie den Menüpunkt Shops auf und öffnen Sie die Detailseite Ihres Shops.
2. Wählen Sie in der Sidebar den Punkt OAuth-Zugangsdaten aus.
3. Legen Sie neue Zugangsdaten an. Tragen Sie die Client-ID und das Client-Secret ein, die Sie im vorherigen Schritt erhalten haben. Den Namen können Sie frei wählen (z.B. "Mailversand").
4. Hinterlegen Sie die OAuth-Zugangsdaten in der Shop-Konfiguration. Die nötigen Einstellungen im Block mail sind abhängig vom verwendeten Mail-Anbieter (siehe unten).

Bei Gmail erfolgt der Mailversand per SMTP mit OAuth2-Authentifizierung. Tragen Sie folgende Einstellungen in der Shop-Konfiguration ein:

mail {
    host = "smtp.gmail.com"
    port = "587"
    protocol = "STARTTLS"
    sender = "meine-adresse@gmail.com"
    senderName = "Mein Shop"
    oauthTokenName = "Mailversand"
}

• host – SMTP-Host von Gmail
• port – 587 bei Verwendung von STARTTLS
• protocol – STARTTLS wird für OAuth2 über SMTP verwendet
• sender – Die Gmail-Adresse, die zum Versand berechtigt ist
• oauthTokenName – Der Name der OAuth-Zugangsdaten, die Sie in SellSite angelegt haben

Bei Office 365 erfolgt der Mailversand nicht per SMTP, sondern über die Microsoft Graph API. Tragen Sie folgende Einstellungen in der Shop-Konfiguration ein:

mail {
    host = "-"
    port = "587"
    protocol = "STARTTLS"
    sender = "meine-adresse@office365.com"
    senderName = ""
    oauthTokenName = "Mailversand"
    microsoftGraphApi.enabled = true
}

• host – Muss weiterhin definiert sein, wird aber nicht für den Versand genutzt. Tragen Sie hier "-" ein.
• sender – Die Microsoft-Mail-Adresse, die zum Versand berechtigt ist.
• senderName – Wird bei der Microsoft Graph API vom Mailserver bestimmt. Die Konfiguration mail.senderName hat daher bei Versand über die Microsoft Graph API keine Auswirkung auf den sichtbaren Absendernamen und kann leer gelassen werden.
• microsoftGraphApi.enabled – Muss auf true gesetzt werden, um den Versand über die Graph API zu aktivieren.

Standardmäßig verwendet SellSite die allgemeinen Microsoft-OAuth-Endpunkte (common). Falls Ihre Azure-Umgebung erfordert, dass die Authentifizierungs- und Token-URL auf einen bestimmten Azure-Mandanten (Tenant) beschränkt sein müssen, fügen Sie folgenden Abschnitt in der Shop-Konfiguration hinzu:

security.oauth.services.microsoft-graph-api-mail {
    authUrl = "https://login.microsoftonline.com/MANDANTEN_ID/oauth2/v2.0/authorize"
    authScope = "Mail.Send offline_access"
    tokenUrl = "https://login.microsoftonline.com/MANDANTEN_ID/oauth2/v2.0/token"
    label = "$OAuthService.microsoft-graph-api-mail"
}

Ersetzen Sie MANDANTEN_ID durch die ID Ihres Azure-Mandanten (Tenant-ID). Diese finden Sie im Azure Portal auf der Übersichtsseite von Microsoft Entra ID unter Mandanten-ID.

Nach der Konfiguration muss die OAuth2-Authentifizierung einmalig durchgeführt werden:

1. Öffnen Sie die Detailseite der OAuth-Zugangsdaten in SellSite. Dort finden Sie die Redirect-URL.
2. Tragen Sie diese Redirect-URL in den OAuth-Einstellungen Ihres Mail-Anbieters ein (bei Gmail unter "Authorized redirect URIs", bei Azure unter "Umleitungs-URIs").
3. Klicken Sie in SellSite auf Jetzt Autorisieren. Sie werden zu Ihrem Mail-Anbieter weitergeleitet, wo Sie sich anmelden und der Anwendung die Berechtigung erteilen müssen, E-Mails in Ihrem Namen zu versenden.
4. Nach erfolgreicher Authentifizierung werden Sie zurück zu SellSite geleitet. Die OAuth-Zugangsdaten sind nun aktiv, erkennbar an der grünen Hinweismeldung.

Mit dem Job Mail-Konfigurations-Test können Sie die Verbindung testen. Dieser Job versendet eine Test-E-Mail von der im Shop hinterlegten Absenderadresse an eine von Ihnen angegebene Empfängeradresse.

Die folgende Anleitung beschreibt die Einrichtung eines OAuth2 Clients in der Google Cloud Console für den Mailversand per Gmail.

1. Loggen Sie sich in der Google Cloud Console ein.
2. Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes aus.
3. Suchen Sie im Suchfeld nach Gmail API und aktivieren Sie diese.
4. Wählen Sie auf der Gmail-API-Seite Manage aus.
5. Klicken Sie in der linken Sidebar auf Credentials, dann oben auf Create Credentials und wählen Sie OAuth client ID. Als Typ wählen Sie Web application.
6. Auf der Detailseite der Credentials finden Sie die Client-ID und das Client-Secret. Tragen Sie hier außerdem unter Authorized redirect URIs die Redirect-URL ein, die Sie in SellSite auf der Detailseite der OAuth-Zugangsdaten finden.
7. Navigieren Sie auf der Manage-Seite der Gmail API zu OAuth consent screen. Das Projekt muss als External konfiguriert sein.
8. Unter Audience → Test users fügen Sie die Gmail-Adresse hinzu, die Sie für den Mailversand verwenden möchten. Diese Adresse muss mit der in SellSite konfigurierten sender-Adresse übereinstimmen.

Die folgende Anleitung beschreibt die Einrichtung einer App-Registrierung im Azure Portal für den Mailversand über die Microsoft Graph API.

1. Loggen Sie sich mit dem User, der die Mails verschicken soll im Azure Portal ein.
2. Navigieren Sie zu Microsoft Entra ID (über die Kachel "Microsoft Entra ID verwalten" oder die Suche). Klicken Sie auf Hinzufügen → App-Registrierung.
3. Vergeben Sie einen Namen und wählen Sie die passenden Unterstützten Kontotypen. Zu Testzwecken eignet sich die Option "Konten in einem beliebigen Organisationsverzeichnis (beliebiger Microsoft Entra ID-Mandant – mandantenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox)".
4. API-Berechtigungen konfigurieren: Wählen Sie auf der Detailseite der App-Registrierung unter Verwalten → API-Berechtigungen den Punkt Berechtigung hinzufügen. Wählen Sie Microsoft Graph → Delegierte Berechtigungen und aktivieren Sie:
   • Mail.Send – erlaubt den Mailversand
   • offline_access – erlaubt SellSite, das Access-Token über ein Refresh-Token regelmäßig zu erneuern
   Klicken Sie auf Berechtigungen hinzufügen und anschließend auf Administratorzustimmung für [Ihr Mandant] gewähren, damit die Berechtigungen wirksam werden.
5. Client-ID kopieren: Die Anwendungs-ID (Client) finden Sie auf der Übersichtsseite der App-Registrierung.
6. Client-Secret erstellen: Navigieren Sie unter Verwalten zu Zertifikate & Geheimnisse und generieren Sie ein neues Client-Secret. Nach dem Erstellen werden zwei Spalten angezeigt:
   • Geheime ID – eine interne ID des Secrets in Azure. Diese wird nicht in SellSite benötigt.
   • Wert – das eigentliche Client-Secret. Diesen Wert müssen Sie als Client-Secret in SellSite eintragen.
   Der Wert wird nur einmalig direkt nach dem Erstellen angezeigt und danach ausgeblendet. Kopieren Sie ihn sofort. Verwechseln Sie ihn nicht mit der Geheimen ID, die zwar dauerhaft sichtbar bleibt, aber nicht das Client-Secret ist.
7. Redirect-URL eintragen: Navigieren Sie unter Verwalten zu Authentifizierung. Klicken Sie auf Plattform hinzufügen bzw. Umleitungs-URI hinzufügen, wählen Sie Web und tragen Sie die Redirect-URL aus SellSite ein.

Sollte der Mailversand nach der Einrichtung nicht funktionieren, prüfen Sie folgende Punkte:

• Redirect-URL stimmt nicht überein: Die in SellSite angezeigte Redirect-URL muss exakt mit der im Mail-Anbieter hinterlegten URL übereinstimmen (inkl. Protokoll und Pfad).
• Zugangsdaten abgelaufen: Prüfen Sie auf der Detailseite der OAuth-Zugangsdaten in SellSite, ob das angezeigte Ablaufdatum in der Vergangenheit liegt. Falls ja, konnte SellSite das Token nicht mehr erneuern. Führen Sie die Authentifizierung erneut durch.
• Falscher Sender: Die im Feld mail.sender eingetragene E-Mail-Adresse muss mit der beim OAuth2-Anbieter autorisierten Adresse übereinstimmen.
• Microsoft Graph API nicht aktiviert: Bei Office 365 muss mail.microsoftGraphApi.enabled = true gesetzt sein.
• Microsoft Graph API autorisiert, aber Mailversand liefert Status 403: Prüfen Sie, ob die App vom Nutzer eingerichtet ist, der auch die E-Mails versenden soll. Bei der Microsoft Graph API muss die App mit dem gleichen User registriert sein, der auch als Absenderadresse konfiguriert ist.
• Fehlende Berechtigungen (Office 365): Stellen Sie sicher, dass sowohl Mail.Send als auch offline_access als delegierte Berechtigungen konfiguriert und die Administratorzustimmung erteilt wurde.
• Gmail Test-User fehlt: Solange die Google-App nicht verifiziert ist, muss die Absenderadresse als Test-User eingetragen sein.