Mailversand im Shop via OAuth2

Im Folgenden werden die Schritte beschrieben, um den Mailversand über OAuth2 zu konfigurieren.

1. Einrichten eines OAuth2 Clients im Mailserver
2. Konfiguration des OAuth2 Clients in Sellsite
3. Authentifizierung
4. Testen der Verbindung

Sie müssen zunächst einen OAuth2 Client auf Ihrem Mailserver einrichten. Aktuell werden Gmail und Office 365 (auch bekannt als Microsoft 365) unterstützt. Die genauen Schritte hängen vom jeweiligen Mailserver ab. Falls Sie einen anderen Mailserver verwenden, dann melden Sie sich bitte beim SellSite-Support, damit wir die nötigen Endpunkte und Einstellungen konfigurieren können. Weiter unten sind Beispiele zum Testen und als Referenz aufgeführt.

Für SellSite wird später folgendes benötigt:

• Client-ID
• Client-Secret
• Möglichkeit im Mailserver, eine Redirect-URL zu autorisieren

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

1. Rufen Sie den Menüpunkt "Shops" und dann die Detailseite Ihres Shops auf.
2. Wählen Sie in der Sidebar den Punkt "OAuth-Zugangsdaten" aus.
3. Hier können Sie neue Zugangsdaten anlegen. Dabei kann der Name beliebig gewählt werden.
4. Abschließend müssen die Daten in der Shop-Konfiguration hinterlegt werden. Tragen Sie dazu im Block "mail" als Einstellung "oauthTokenName" den Namen der OAuth-Zugangsdaten ein, die Sie gerade erstellt haben. Als "protocol" muss "STARTTLS" und als Port üblicherweise "587" eingetragen werden, falls dies noch nicht der Fall ist. Der "sender" muss die E-Mail-Adresse sein, die berechtigt ist, E-Mails OAuth2-authentifiziert zu versenden. Diese ist in der Regel die, mit der Sie auch berechtigt sind, Client-ID und Client-Secret zu generieren.
5. Der Microsoft-Mailversand geschieht nicht per SMTP, sondern per Microsoft Graph API. Daher muss in diesem Fall zusätzlich in der Shop-Konfiguration mail.microsoftGraphApi.enabled = true eingetragen werden. Zudem muss der Kompatibilität halber mail.host weiterhin in der Shop-Konfiguration definiert sein, auch wenn es für den Mailversand nicht mehr benötigt wird.
6. In allen Fällen können Sie in der Shop-Konfiguration das Passwort im Feld "mail.password" entfernen, da der Mailversand nun per OAuth2 authentifiziert wird.

Nach der Konfiguration müssen Sie sich mit den OAuth-Zugangsdaten authentifizieren. Hierfür muss zunächst die Redirect-URL des Shops in den OAuth-Einstellungen des Mailservers eingetragen werden. Die Redirect-URL finden Sie auf der Detailseite der OAuth-Zugangsdaten in SellSite.

Auf der Detailseite der OAuth-Zugangsdaten in SellSite können Sie nun per Klick auf "Jetzt Autorisieren" die Authentifizierung starten. Sie werden dann zu Ihrem Mailserver weitergeleitet, wo Sie sich mit Ihren Mail-Zugangsdaten anmelden und der Anwendung die Berechtigung erteilen müssen, E-Mails in Ihrem Namen zu versenden.

Nach erfolgreicher Authentifizierung werden Sie zurück zu SellSite geleitet und die OAuth-Zugangsdaten sind nun aktiv. Dies Erkennen Sie an der nun grünen Hinweismeldung. Bitte beachten Sie, wann die Zugangsdaten ablaufen im Feld "Zugangsdaten gültig bis". Spätestens zu diesem Zeitpunkt müssen Sie die Authentifizierung erneut durchführen, um den Mailversand weiterhin nutzen zu können.

Mit dem Job Mail-Konfigurations-Test können Sie nun die Verbindung testen. Dieser Job sendet eine Test-E-Mail von der im Shop hinterlegten E-Mail-Adresse unter Nutzung der OAuth-Zugangsdaten eine E-Mail an die im Job angegebene E-Mail-Adresse.

Zu Entwicklungs- und Referenzzwecken können Sie wie folgt Mailversand per Gmail einrichten:

1. Loggen Sie sich in der Google Cloud Console ein.
2. Erstellen Sie ein neues Projekt oder wählen Sie ein bestehendes aus. Das Projekt muss bei der Erstellung als "external" deklariert werden.
3. Suchen Sie im Suchfeld nach "Gmail API" und aktivieren Sie diese API.
4. Anschließend wählen Sie "Manage" auf der "Gmail API" Seite.
5. Klicken Sie auf "Credentials" in der linken Sidebar, dann "Create Credentials" oben und legen Sie eine "OAuth client ID" an. Diese sollte vom Typ "Web application" sein und einen beliebigen Namen haben.
6. Auf der Detailseite der neu angelegten Credentials finden Sie die Client-ID und das Client-Secret. Hier muss später dann auch die Redirect-URL eingetragen werden, die Sie in SellSite auf der Detailseite der OAuth-Zugangsdaten finden.
7. Solange die App nicht von Google verifiziert wurde, müssen Sie einen Testbenutzer für den Mailversand anlegen. Klicken Sie dazu auf der Manage-Seite der "Gmail API" auf "OAuth consent screen" → "Audience" → "Test users" und fügen Sie dort die Google-Mail-Adresse hinzu, die Sie für den Mailversand verwenden möchten. Diese E-Mail-Adresse muss später auch in SellSite als "sender" eingetragen werden.

Bitte beachten Sie bei Office 365, dass der Mailversand über die neuere Microsoft Graph API statt wie bisher über SMTP erfolgt.

Zu Entwicklungs- und Referenzzwecken können Sie wie folgt Mailversand per Office 365 einrichten:

1. Loggen Sie sich in das Azure Portal ein.
2. Erstellen Sie eine neue App-Registrierung oder wählen Sie eine bestehende aus. Um eine neue App-Registrierung zu erstellen, klicken Sie auf "Sicht" in der Kachel "Microsoft Entra ID verwalten", dann "Hinzufügen" und wählen Sie dort "App-Registrierung". Zu Testzwecken können Sie bei den "Unterstützte Kontotypen" die Option "Konten in einem beliebigen Organisationsverzeichnis (beliebiger Microsoft Entra ID-Mandant – mandantenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox)" wählen.
3. Um den Mailversand per Microsoft Graph API zu erlauben, müssen Sie auf der Detailseite der App-Registrierung unter "Verwalten" den Punkt "API-Berechtigungen" auswählen. Klicken Sie auf "Berechtigung hinzufügen", wählen Sie "Microsoft Graph" und dann "Delegierte Berechtigungen". Suchen Sie anschließend nach "Mail.Send" und aktivieren diese. Zudem muss die Berechtigung "offline_access" aktiviert werden, damit SellSite nicht nur das kurzlebige Access-Token (meist nur eine Stunde gültig), sondern auch ein Refresh-Token erhält, um das Access-Token regelmäßig zu erneuern. Nach der Auswahl der zwei Berechtigungen klicken Sie auf "Berechtigungen hinzufügen". Ein abschließender Klick auf "Administratorzustimmung für [Ihr Mandant] gewähren" auf der Berechtigungen-Übersichtsseite sorgt dafür, dass die Berechtigungen auch tatsächlich wirksam werden.
4. Auf der Detailseite der App-Registrierung finden Sie zudem die "Anwendungs-ID (Client)", die Sie später als Client-ID in SellSite eintragen müssen. Links finden Sie untern dem Punkt "Verwalten" zudem den Unterpunkt "Zertifikate & Geheimnisse". Hier können Sie ein neues Client-Secret generieren. Wenn Sie ein neues Client-Secret generieren, ist der angezeigte "Wert" das Client-Secret, welches Sie später in SellSite eintragen müssen. Hinweis: Dieses Secret wird an dieser Stelle nur einmalig angezeigt und später ausgeblendet.
5. Im Menüpunkt "Verwalten" gibt es zudem den Unterpunkt "Authentication". Hier kann die in SellSite angegebene Redirect-URL angegeben werden. Dazu klicken Sie auf "Umleitungs-URI hinzufügen" und wählen "Web" aus. Tragen Sie dann die Redirect-URL aus SellSite ein und speichern Sie die Einstellungen per Klick auf "Konfigurieren".