Office 365 Mail Server Configuration with OAuth2

The Mail Connector also supports an authentication via OAuth2 (XOAUTH2), specifically for Microsoft Office 365.
This enables secure email sending via Azure App Registrations without the need for traditional user passwords.

Technical Instructions & Docker Configuration

To use OAuth2 for Office 365, the following environment variables must be configured (e.g., in your docker-compose.yml):

Variable	Description	Enable Office 365 mail
MAIL_OAUTH_ENABLED	Enables the OAuth2 flow.	true
MAIL_OAUTH_TENANT_ID	The Azure Directory (Tenant) ID.	[Your Azure Tenant ID]
MAIL_OAUTH_CLIENT_ID	The Azure Application (Client) ID.	[Your Azure Client ID]
MAIL_OAUTH_CLIENT_SECRET	The Secret Key from your Azure App Registration.	[Your Azure Secret]
MAIL_OAUTH_AUTHORITY	The base URL for Microsoft authentication.	https://login.microsoftonline.com/
MAIL_OAUTH_SCOPE	The permission scope for SMTP access.	https://outlook.office365.com/.default
MAIL_USER	The email address of the sending account.	[Your Azure User which is configured to send emails]
MAIL_HOST	The Microsoft SMTP host.	smtp.office365.com
MAIL_PORT	The SMTP port (requires STARTTLS).	587
MAIL_SECURITY	The encryption protocol.	STARTTLS
MAIL_SYSTEM_REPLY_TO_EMAIL	Office 365 email address from which to send system emails.	[Your Azure User which is configured to send emails]
MAIL_SYSTEM_FROM_NAME	The name for the "From" field shown in email clients (expect exchange clients).	["From" name which is shown in emails]
MAIL_SYSTEM_FROM_EMAIL	The email address from which to send system emails not created by a 4ALLPORTAL user.	[Email address for system emails, e.g, no-reply@company.de ]

Please note

• The MAIL_USER must match the account that has been granted the SMTP.SendAsApp permission in your Azure App Registration.
• Exchange mail clients will show a field from exchange instead of MAIL_SYSTEM_FROM_NAME.

Step by Step: Configure SMTP OAuth2 for Java Applications in Azure AD & Exchange Online

This guide describes in eight steps how an Azure Administrator can configure SMTP mail sending using OAuth2 (Client Credentials flow) for a Java application.

1. Register an Application in Azure Active Directory

1. Open the Azure Portal
2. Navigate to Azure Active Directory > App registrations > New registration and make the following settings:
   • Name: smtp-oauth-app (example)
   • Supported account types: accounts in this organizational directory only (single tenant)
   • Redirect URI: leave empty (not required for Client Credentials flow)
3. Click "Register"
4. Note/copy the following values:
   • Application (Client) ID
   • Directory (Tenant) ID
   • Object ID

2. Create a Client Secret

1. Go to the newly registered app
2. Navigate to Certificates & secrets > Client secrets
3. Click "New client secret"
4. Choose an expiration (e.g. 12 months)
5. Click "Add"

Important:

• Copy and securely store the secret value immediately — it is shown only once.
• The client secret has an expiration date. Before it expires, you must:
  1. Create a new client secret in Azure Active Directory (Certificates & secrets > Client secrets)
  2. Update the MAIL_OAUTH_CLIENT_SECRET environment variable in 4ALLPORTAL with the new secret value
  3. Restart the 4ALLPORTAL to apply the changes

3. Add API Permissions for Exchange Online

1. Go to API permissions > Add a permission
2. Select "APIs my organization uses"
3. Choose "Office 365 Exchange Online"
4. Select:
   • Application permissions
   • SMTP.SendAsApp
5. Click "Add permissions"

4. Grant Admin Consent

After adding the permission, click "Grant admin consent" for your tenant. Then, confirm the action.
This step is mandatory. Without admin consent, SMTP OAuth will not work.

5. Connect to Exchange Online PowerShell

Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com

6. Register the Service Principal in Exchange Online

New-ServicePrincipal -AppId <CLIENT_ID> -ServiceId <OBJECT_ID>

Replace the following values:

• <CLIENT_ID> with the Application (client) ID from Step 1
• <OBJECT_ID> with the Object ID found under "Enterprise Applications" (not the one from App Registrations)

7. Configure the Mailbox Permissions

7.1 Mailbox Check

Ensure that the mailbox is properly configured and verify the following:

• Is the mailbox licensed?
• Is SMTP AUTH enabled?

If required, enable SMTP AUTH as follows:

Set-CASMailbox -Identity "<MAIL_ADDRESS>" -SmtpClientAuthenticationDisabled $false

Replace the following value:

• <MAIL_ADDRESS> with the mailbox email address

7.2 Grant "Send As" Permission

Grant "Send As" permission to the service principal with the following powershell:

Add-RecipientPermission `
  -Identity "<MAIL_ADDRESS>" `
  -Trustee "<SERVICE_PRINCIPAL_ID>" `
  -AccessRights SendAs

Replace the following values:

• <SERVICE_PRINCIPAL_ID> is the Object ID of the Service Principal (found under Enterprise Applications).
• <MAIL_ADDRESS> is the mailbox email address

7.3 Grant "Full Access" Permission

Grant "Full Access" permission to the service principal with the following powershell:

Add-MailboxPermission `
  -Identity "<MAIL_ADDRESS>" `
  -User "<SERVICE_PRINCIPAL_ID>" `
  -AccessRights FullAccess

Replace the following values:

• <SERVICE_PRINCIPAL_ID> is the Object ID of the Service Principal (found under Enterprise Applications).
• <MAIL_ADDRESS> is the mailbox email address

8. SMTP AUTH at Tenant Level

Enable SMTP AUTH at tenant level (if disabled):

Set-TransportConfig -SmtpClientAuthenticationDisabled $false

Result

The following should be configured now:

• The Azure AD app is registered.
• The OAuth2 Client Credentials flow is enabled.
• Exchange Online allows SMTP.SendAsApp.
• The service principal can send emails.
• SMTP AUTH is enabled at mailbox and tenant level.

The Java application or SMTP client can now authenticate using OAuth2 and send emails via smtp.office365.com.