How to set up SMTP with Microsoft OAuth2.0?

Zyxel_Emily · May 28

his guide explains how to configure your gateway to send emails using SMTP with Microsoft OAuth 2.0 authentication through a Microsoft 365 account. OAuth 2.0 provides secure, token-based authentication, replacing less secure basic authentication methods. Follow these steps to register an application in Microsoft Azure and configure your gateway for SMTP. This feature is supported in uOS version 1.35 and later. Note: SMTP with Microsoft OAuth 2.0 is supported on USG Flex H series. This example was tested using USG FLEX 200HP (Firmware Version: uOS 1.35).

Prerequisites

A Microsoft 365 account with a licensed Exchange Online mailbox.
Administrative access to the Microsoft Azure Portal (https://portal.azure.com).
SMTP AUTH is enabled for the mailbox (see Step 3 below).
Your gateway device with SMTP configuration access (firmware version uOS1.35 or above).

Step-by-Step Instructions

Step1: Register an Application in Azure Portal

1.Sign in to Azure Portal:

Go to https://portal.azure.com and sign in with an account that has administrative privileges for Microsoft Entra ID.

2.Navigate to App Registrations:

In the left-hand menu, select Microsoft Entra ID > App registrations > New registration.

3.Configure the Application:

Name: Enter a descriptive name (e.g., "Gateway SMTP App").
Supported account types: Select Accounts in this organizational directory only (Single tenant)for most cases.
Redirect URI: The redirect URI specifies where the authorization server should send the user back after successfully authenticating to return an access token to their email account.
Type: Select "Web."
URI: Enter https://[devicefqdn or ip]/cgi-bin/msoauth2.cgi. Replace [Device FQDN or IP] with the actual fully qualified domain name or IP address of an internal interface that the administrator computer can connect to. (Note: Redirect URI must begin with the scheme https.)
Click Register.

4.Copy Application IDs:

Onthe app’s Overview page, copy the Application(client) ID and Directory (tenant) ID. These are required for your gateway configuration.

5.Create a Client Secret:

Go to Certificates & secrets > Client Secrets > New client secret.
Add a description (e.g., "SMTP Secret") and select an expiration period(e.g., 24 months).
Click Add, then immediately copy the value of the client secret. Note: This value is only shown once, and you will not be able to retrieve it after leaving this page. If you lose it, you'll need to generate a new one. This is your “ClientSecret”.
Store it securely, as it grants access to your application.

Step 2:Grant API Permissions

1.Add Permissions:

From the left-hand navigation of your application's overview page, click on API permissions > +Add a permission.
Select Microsoft Graph
Choose Delegated permissions > Search for offline access
Click Add permissions.
Add 2nd permissions. Click +Add a permission
Select Microsoft Graph
Choose Delegated permissions > select SMTP.Send
Click Add permissions.

Step 3: Enable SMTP AUTH for the mailbox

1.Sign in to Microsoft 365 admin center- Navigate to Users > Active users > click the user’s mailbox > Select Mail tab.

2.Ensure that the checkbox option “Authenticated SMTP” is selected..

Step 4:Configure SMTP in Your Gateway

1.Access the Gateway GUI:

Log in to your device’s configuration interface from internal interface (LAN side).
Navigate to System > Notification > Mail Server

2.Enter SMTP Settings:

Mail Server: smtp.office365.com
Port: 587 (recommended, supports STARTTLS).
Encryption: Enable STARTTLS
Authentication Method: Select Microsoft OAuth2.0.
Sender Email Address: Enter the Microsoft 365 email address (e.g., sender@yourdomain.com).
Client ID: Paste the Application (client) ID from Step 1-4.
Client Secret: Paste the client secret value from Step 1-5.
Tenant ID: Paste the Directory (tenant) ID from Step 1-4.

3.Apply Configuration:

! You must click Apply before requesting a token.
Click Apply to save the configuration on your gateway.

4.Obtain OAuth 2.0 Token

After applying the configuration, click "Get New Token" button.
This will open a new browser tab to the Microsoft Azure sign-in page.
Sign in with the Microsoft 365 account associated with the sender email address (e.g., sender@yourdomain .com).
Grant permissions when prompted
The browser will close automatically upon successful authentication, and your gateway will have securely obtained an authentication token from Microsoft.
The Token Status field will update. (e.g., “Valid”).
If the browser does not open: Click the “Refresh Token Status” button to check if the token was successfully obtained or to retry the token retrieval process.

Verify the SMTP with Microsoft OAuth2.0 function

Ensure the token is successfully acquired.

Fill in the recipient email address and send a test email.

Navigate to Log & Report>Log/Events>System and check for the successful token‑retrieval log message.

2. Navigate to Log & Report > Email Daily Report > Send Report Now to send an email through your firewall.

Ensure that the email is successfully received in the mailbox.

Troubleshooting

Authentication Failed:

Double-check credentials: Ensure that the Client ID, Tenant ID, and Client Secret are copied precisely without any extra spaces.
Ensure admin consent was granted for API permissions
Check that the sender email address exists in your Microsoft 365 tenant

Permission Denied:

Confirm API permission is granted (Step2-1).
Verify the application has admin consent
Check that the sender email account is active

Client Secret Expired:

Generate a new client secret in Azure Portal and update it in the gateway settings.

Connection Issues

Verify SMTP server settings (smtp.office365. com:587). Ensure port 587 is unblocked.
Ensure STARTTLS encryption is enabled
Check the firewall/network connectivity

Browser Issues

Browser doesn't open: Check if pop-up blockers are enabled and allow pop-ups for the gateway
Browser opens but shows error: Verify the Azure application redirect URI configuration. And make sure the administrator’s PC located in the network that can access the URI(Located in LAN side of gateway is recommend).
Token not acquired after sign-in: Click the "Refresh Token Status" button to check token status
Multiple browser tabs open: Close extra tabs and try again
Browser doesn't close automatically: Manually close the tab after successful sign-in

Token Issues:

Token acquisition failed:Verify internet connectivity and try clicking "Get New Token "again
Token expires quickly: This is normal - the gateway will automatically refresh tokens
"Refresh Token Status" button shows no token: Repeat the "Get New Token" process
Token status not updating: Wait 10-15 seconds then click "Refresh Token Status" again

Security Best Practices

Secret Management

Store client secrets securely
Rotate secrets before expiration
Use different applications for different purposes

Access Control

Grant the minimum required permissions only
Regularly review application permissions
Monitor application usage through Azure logs

Monitoring

Enable audit logging in Microsoft Entra ID
Monitor for unusual authentication patterns
Set up alerts for failed authentication attempts

Additional Information

Token Lifecycle

Access tokens expire after 1 hour
Your gateway automatically handles token refresh
Initial token must be acquired through browser sign-in
Subsequent token renewals happen automatically in the background
No user interaction required for token renewal after initial setup

Supported Email Types

Plaintext emails
HTML-formatted emails
Emails with attachments
Bulk email sending (within Microsoft limits)

Rate Limits

Microsoft imposes sending limits:
30 messages per minute
10,000 messages per day (default)
Higher limits are available through Microsoft support

Support

If you encounter issues:

Verify all steps were completed correctly
Check Microsoft Entra ID audit logs for authentication errors
Contact your system administrator for Azure access issues
Refer to Microsoft's official OAuth 2.0 documentation

For technical support with your gateway device, contact our support team with your configuration details (never share client secrets).