Configure Microsoft 365 SMTP with OAuth 2 in Shopware

The setup uses the application permission SMTP.SendAsApp. This allows Shopware to send emails through a defined Microsoft 365 mailbox without using a username and password directly for SMTP authentication.

Table of contents

1. Requirements
2. Create a Microsoft Entra ID app
3. Add the SMTP permission
4. Create a client secret
5. Assign permissions via PowerShell
6. Configure Microsoft 365 OAuth 2 in Shopware
7. Notes and troubleshooting

Requirements

You need the following:

• a Microsoft 365 tenant with Exchange Online,
• an existing Exchange Online mailbox for email delivery,
• sufficient administrator permissions in Microsoft Entra ID and Exchange Online,
• PowerShell with access to the required Microsoft modules,
• a Shopware 6 installation with support for SMTP OAuth 2.

Step 1: Create a Microsoft Entra ID app

1. Open App registrations

1. Open entra.microsoft.com.
2. Go to App registrations.
3. Click New registration.

2. Register a new application

1. Enter a clear name, for example example.com SMTP OAuth 2.
2. Under Supported account types, select Accounts in this organizational directory only.
3. Click Register.

Keep the Application ID:
After registration, Microsoft Entra ID displays the overview page of the new application. You will need the Application (client) ID shown there later for the Shopware configuration.

Add the SMTP permission for Exchange Online

To allow Shopware to send emails through the registered application, add the Exchange Online permission SMTP.SendAsApp.

1. Open API permissions in the Entra ID application.
2. Click Add a permission.
3. Select APIs my organization uses.
4. Search for Office 365 Exchange Online.
5. Open the Office 365 Exchange Online entry.
6. Select Application permissions.
7. Search for SMTP.
8. Enable the permission SMTP.SendAsApp.
9. Click Add permissions or Close.
10. Then click Grant admin consent for your organization.

Note:
Admin consent is required so that the application can use the SMTP permission within the Microsoft 365 tenant.

Create a client secret for Shopware

1. Open Certificates & secrets in the Entra ID application.
2. Open the Client secrets section.
3. Click New client secret.
4. Enter a description for the secret.
5. Select the desired expiration period.
6. Click Add.
7. Copy the displayed client secret Value immediately.

Important:
Microsoft displays the client secret value only once in full. Copy and store it immediately after creation. The secret ID is not the client secret and cannot be used for the Shopware configuration.

Also note the selected expiration period. After the client secret expires, you must create a new secret and enter it in Shopware. Otherwise, Shopware will no longer be able to send emails through Microsoft 365.

Step 2: Assign Exchange Online permissions via PowerShell

After configuring the application in Entra ID, you must register it in Exchange Online and grant access to the required sender mailbox.

1. Install the required PowerShell modules

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

Note:
Run PowerShell as an administrator if required. You do not need to reinstall modules that are already installed.

2. Connect to Exchange Online

Connect-ExchangeOnline -Organization [tenantId]

Replace [tenantId] with the tenant ID of your Microsoft 365 tenant.

3. Connect to Microsoft Graph

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

The first time you run this command, Microsoft may display a sign-in window. Sign in with an account that has the required administrator permissions and approve the requested access.

4. Retrieve the service principal of the Entra ID application

$entraServicePrincipalDetails = Get-MgServicePrincipal -Filter "DisplayName eq '[Name of the Entra ID app]'"

Replace [Name of the Entra ID app] with the name you entered during app registration.

5. Register the service principal in Exchange Online

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

6. Retrieve the Exchange service principal

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

7. Grant access to the sender mailbox

Add-MailboxPermission -Identity "[Email address for sending]" -User $EXOServicePrincipal.Identity -AccessRights FullAccess

Replace [Email address for sending] with the full email address of the mailbox that Shopware should use to send messages.

8. Grant the SendAs permission

Add-RecipientPermission -Identity "[Email address for sending]" -Trustee $EXOServicePrincipal.Identity -AccessRights SendAs

Confirm any security prompt displayed in PowerShell.

Note:
After assigning the permissions, it may take up to 15 minutes before they are fully active in Exchange Online.

Step 3: Configure Microsoft 365 OAuth 2 in Shopware

After setting up the Entra ID application and Exchange Online permissions, enter the credentials in the Shopware mailer configuration.

1. Open the Shopware Administration.
2. Go to Settings → System → Mailer.
3. Select SMTP server with OAuth 2 as the preferred email agent.
4. Enter smtp.office365.com as the host.
5. Use port 587.
6. Enter https://login.microsoftonline.com/[tenantId]/oauth2/v2.0/token as the OAuth URL.
7. Enter https://outlook.office365.com/.default as the OAuth scope.
8. Enter the Application (client) ID of the registered Entra ID application as the client ID.
9. Enter the previously copied client secret value.
10. Select TLS as the encryption method.
11. Enter the mailbox that received the Exchange Online permissions as the sender address.
12. Save the mailer configuration.

Overview of the Shopware mailer settings

Notes and troubleshooting

The OAuth URL must end with /token

Shopware requires the token endpoint. Use the URL ending in /oauth2/v2.0/token and not the authorization endpoint ending in /authorize.

Do not confuse the client secret with the secret ID

Shopware requires the client secret Value that Microsoft displays once immediately after creation. The secret ID that remains visible in Entra ID cannot be used for authentication.

The sender address must match the authorized mailbox

The sender address configured in Shopware must match the mailbox for which the FullAccess and SendAs permissions were assigned in PowerShell.

Permission changes may not be active immediately

New permissions in Microsoft 365 can take several minutes to propagate. Wait up to 15 minutes after completing the PowerShell configuration and then perform another test email.

Renew the client secret before it expires

Check the expiration date of the client secret and renew it in time. After the secret expires, OAuth authentication will fail until you create a new secret in Entra ID and save it in Shopware.

Conclusion

With a registered Microsoft Entra ID application, the SMTP.SendAsApp permission and the appropriate Exchange Online permissions, Shopware 6 can securely send emails through Microsoft 365 using OAuth 2.

After the initial setup, make sure to regularly check the client secret expiration date and the permissions assigned to the sender mailbox.