Microsoft 365 SMTP mit OAuth 2 in Shopware 6 einrichten

Die Einrichtung verwendet die Anwendungsberechtigung SMTP.SendAsApp. Dadurch kann Shopware E-Mails über ein festgelegtes Microsoft-365-Postfach versenden, ohne Benutzername und Kennwort direkt für die SMTP-Authentifizierung zu verwenden.

Inhaltsverzeichnis

1. Voraussetzungen
2. Microsoft Entra ID-App erstellen
3. SMTP-Berechtigung hinzufügen
4. Client Secret erstellen
5. Berechtigungen per PowerShell vergeben
6. Microsoft 365 OAuth 2 in Shopware konfigurieren
7. Hinweise und Fehlerbehebung

Voraussetzungen

Für die Einrichtung benötigen Sie:

• einen Microsoft-365-Mandanten mit Exchange Online,
• ein vorhandenes Exchange-Online-Postfach für den E-Mail-Versand,
• ausreichende Administratorrechte in Microsoft Entra ID und Exchange Online,
• PowerShell mit Zugriff auf die Microsoft-Module,
• eine Shopware-6-Installation mit Unterstützung für SMTP OAuth 2.

Schritt 1: Microsoft Entra ID-App erstellen

1. App-Registrierungen öffnen

1. Öffnen Sie entra.microsoft.com.
2. Wechseln Sie zu App-Registrierungen.
3. Klicken Sie auf Neue Registrierung.

2. Neue Anwendung registrieren

1. Vergeben Sie einen aussagekräftigen Namen, beispielsweise example.com SMTP OAuth 2.
2. Wählen Sie unter Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis.
3. Klicken Sie auf Registrieren.

Merken Sie sich die Anwendungs-ID:
Nach der Registrierung wird die Übersichtsseite der neuen Entra-ID-Anwendung angezeigt. Die dort angeführte Anwendungs-ID (Client) wird später für die Konfiguration in Shopware benötigt.

SMTP-Berechtigung für Exchange Online hinzufügen

Damit Shopware über die registrierte Anwendung E-Mails versenden darf, muss die Exchange-Online-Berechtigung SMTP.SendAsApp hinzugefügt werden.

1. Öffnen Sie in der Entra-ID-Anwendung den Bereich API-Berechtigungen.
2. Klicken Sie auf Berechtigung hinzufügen.
3. Wählen Sie Von meiner Organisation verwendete APIs.
4. Suchen Sie nach Office 365 Exchange Online.
5. Öffnen Sie den Eintrag für Office 365 Exchange Online.
6. Wählen Sie Anwendungsberechtigungen.
7. Suchen Sie nach SMTP.
8. Aktivieren Sie die Berechtigung SMTP.SendAsApp.
9. Klicken Sie auf Berechtigungen hinzufügen beziehungsweise Schließen.
10. Klicken Sie anschließend auf Administratorzustimmung für Ihre Organisation erteilen.

Hinweis:
Die Administratorzustimmung ist erforderlich, damit die Anwendung die SMTP-Berechtigung innerhalb des Microsoft-365-Mandanten verwenden darf.

Client Secret für Shopware erstellen

1. Öffnen Sie in der Entra-ID-Anwendung den Bereich Zertifikate und Geheimnisse.
2. Öffnen Sie den Bereich Geheime Clientschlüssel.
3. Klicken Sie auf Neuer geheimer Clientschlüssel.
4. Vergeben Sie eine Beschreibung für den Schlüssel.
5. Wählen Sie die gewünschte Gültigkeitsdauer.
6. Klicken Sie auf Hinzufügen.
7. Kopieren Sie unmittelbar danach den angezeigten Wert des Client Secrets.

Wichtig:
Der Wert des Client Secrets wird nur einmal vollständig angezeigt. Kopieren und speichern Sie den Wert daher direkt nach der Erstellung. Die Secret-ID ist nicht das Client Secret und kann nicht für die Shopware-Konfiguration verwendet werden.

Beachten Sie außerdem die gewählte Laufzeit. Nach Ablauf des Client Secrets muss ein neuer Schlüssel erstellt und in Shopware eingetragen werden. Andernfalls kann Shopware keine E-Mails mehr über Microsoft 365 versenden.

Schritt 2: Exchange-Online-Berechtigungen per PowerShell vergeben

Nach der Konfiguration in Entra ID muss die Anwendung in Exchange Online registriert und für das gewünschte Absenderpostfach berechtigt werden.

1. Erforderliche PowerShell-Module installieren

Install-Module -Name ExchangeOnlineManagement Install-Module Microsoft.Graph

Hinweis:
Führen Sie PowerShell bei Bedarf als Administrator aus. Bereits installierte Module müssen nicht erneut installiert werden.

2. Mit Exchange Online verbinden

Connect-ExchangeOnline -Organization [tenantId]

Ersetzen Sie [tenantId] durch die Mandanten-ID Ihres Microsoft-365-Mandanten.

3. Mit Microsoft Graph verbinden

Connect-MgGraph -Scopes "Application.Read.All"

Beim ersten Aufruf kann ein Microsoft-Anmeldefenster erscheinen. Melden Sie sich mit einem Konto an, das über die erforderlichen Administratorrechte verfügt, und bestätigen Sie die angeforderten Berechtigungen.

4. Service Principal der Entra-ID-Anwendung ermitteln

$entraServicePrincipalDetails = Get-MgServicePrincipal -Filter "DisplayName eq '[Name der Entra-ID-App]'"

Ersetzen Sie [Name der Entra-ID-App] durch den Namen, den Sie bei der App-Registrierung vergeben haben.

5. Service Principal in Exchange Online registrieren

New-ServicePrincipal -AppId $entraServicePrincipalDetails.AppId -ObjectId $entraServicePrincipalDetails.Id -DisplayName "EXO ServicePrincipal for EntraID App $($entraServicePrincipalDetails.DisplayName)"

6. Exchange-Service-Principal abrufen

$EXOServicePrincipal = Get-ServicePrincipal -Identity "EXO ServicePrincipal for EntraID App $($entraServicePrincipalDetails.DisplayName)"

7. Zugriff auf das Absenderpostfach vergeben

Add-MailboxPermission -Identity "[E-Mail-Adresse für Versand]" -User $EXOServicePrincipal.Identity -AccessRights FullAccess

Ersetzen Sie [E-Mail-Adresse für Versand] durch die vollständige E-Mail-Adresse des Postfachs, über das Shopware Nachrichten versenden soll.

8. SendAs-Berechtigung vergeben

Add-RecipientPermission -Identity "[E-Mail-Adresse für Versand]" -Trustee $EXOServicePrincipal.Identity -AccessRights SendAs

Bestätigen Sie eine eventuell angezeigte Sicherheitsabfrage in PowerShell.

Hinweis:
Nach dem Setzen der Berechtigungen kann es bis zu 15 Minuten dauern, bis diese in Exchange Online vollständig aktiv sind.

Schritt 3: Microsoft 365 OAuth 2 in Shopware konfigurieren

Nachdem die Entra-ID-Anwendung und die Exchange-Online-Berechtigungen eingerichtet wurden, können die Zugangsdaten im Shopware-Mailer hinterlegt werden.

1. Öffnen Sie die Shopware-Administration.
2. Wechseln Sie zu Einstellungen → System → Mailer.
3. Wählen Sie als bevorzugten E-Mail-Agenten SMTP-Server mit OAuth 2.
4. Tragen Sie als Host smtp.office365.com ein.
5. Verwenden Sie den Port 587.
6. Tragen Sie als OAuth-URL https://login.microsoftonline.com/[tenantId]/oauth2/v2.0/token ein.
7. Tragen Sie als OAuth-Scope https://outlook.office365.com/.default ein.
8. Tragen Sie als Client-ID die Anwendungs-ID (Client) der registrierten Entra-ID-App ein.
9. Tragen Sie als Client Secret den zuvor kopierten Wert des geheimen Clientschlüssels ein.
10. Wählen Sie als Verschlüsselungsmethode TLS.
11. Tragen Sie als Absender-Adresse das Postfach ein, für das zuvor die Exchange-Online-Berechtigungen vergeben wurden.
12. Speichern Sie die Mailer-Konfiguration.

Übersicht der Shopware-Mailer-Einstellungen

Hinweise und Fehlerbehebung

OAuth-URL endet auf /token

In Shopware muss die Token-URL hinterlegt werden. Verwenden Sie daher die URL mit /oauth2/v2.0/token und nicht die Autorisierungs-URL mit /authorize.

Client Secret und Secret-ID nicht verwechseln

Shopware benötigt den bei der Erstellung einmalig angezeigten Wert des geheimen Clientschlüssels. Die in Entra ID dauerhaft sichtbare Secret-ID ist dafür nicht geeignet.

Absender-Adresse muss mit dem berechtigten Postfach übereinstimmen

Die in Shopware eingetragene Absender-Adresse muss dem Postfach entsprechen, für das in PowerShell die Berechtigungen FullAccess und SendAs gesetzt wurden.

Änderungen sind nicht sofort aktiv

Neue Berechtigungen können in Microsoft 365 einige Minuten benötigen. Warten Sie nach der PowerShell-Konfiguration bis zu 15 Minuten und führen Sie anschließend erneut einen Testversand durch.

Client Secret regelmäßig erneuern

Prüfen Sie die Gültigkeitsdauer des Client Secrets und erneuern Sie es rechtzeitig. Nach Ablauf des Schlüssels schlägt die OAuth-Authentifizierung fehl, bis ein neues Secret in Entra ID erstellt und in Shopware gespeichert wurde.

Fazit

Mit einer registrierten Microsoft-Entra-ID-Anwendung, der Berechtigung SMTP.SendAsApp und den passenden Exchange-Online-Berechtigungen kann Shopware 6 E-Mails sicher über Microsoft 365 und OAuth 2 versenden.

Nach der einmaligen Einrichtung sollten insbesondere die Laufzeit des Client Secrets sowie die korrekte Berechtigung des verwendeten Absenderpostfachs regelmäßig geprüft werden.