OAuth2 Authentication for Sending E-Mails with Microsoft Office 365

Specific configurations are required for sending e-mails from enaio® server and enaio® webclient with Microsoft Office 365:

• Configuration of OAuth2 authentication in Microsoft Office 365.

• Configurations for administrative e-mails from enaio® server to enaio® enterprise-manager.

• Configurations for enaio® webclient via the enaio® service-manager osweb-prod.yml configuration file.

Microsoft Office 365 Configurations for User and App Registration

The user guidance described here may be subject to changes by Microsoft. Consult the Microsoft documentation if necessary.

1. Set up OAuth2 support for the desired user account.
   Enter the user account as 'SMTPUserName' in the enaio® client and enaio® server configuration and in the enaio® webclient configuration.

   • Call https://portal.microsoft.com/.

   • Open or create the desired administrator user account.

   • Activate SMTP authentication for this administrator user account by navigating to Mail > Manage email apps and checking Authenticated SMTP.

2. Follow these steps to create an app registration:

   • Call https://entra.microsoft.com/.

   • Create a new app registration by navigating to Identity > Applications > App registration and selecting + New registration.

   • Select a descriptive name, select Web under Redirect URI, and enter http://localhost.

3. All enterprise user accounts that are to be able to send e-mails via enaio® webclient must be specially configured:

   • Go to Active users in the Microsoft 365 admin center and make the following settings for each desired user account.

   • In the Mail tab, click Send as permissions/Send as permissions.

     You will find two designations here at Microsoft.

   • Check the SMTP administrator user account of enaio® webclient.

     It is not possible to send e-mails if the check mark is not set. A SendAsDenied error message will be displayed.

4. Set up a secret for the app registration:

   • Navigate to Certificates + secrets in the app registration area.

   • Select + New client secret.

   • Enter a description, select an expiration date, and select Add.
     Make a note of the value of the client key for additional configuration.

5. Grant API permissions:

   • Go to API permissions in the app registration area and select Add a permission.

   • Navigate to APIs my organization uses > Office 365 Exchange Online > Application permissions > SMTP and select SMTP.SendAsApp.

   • Grant administrator approval for the permission.

   • Go to Overview and make a note of the Application (client) ID and the Directory (tenant) ID for additional configuration.

6. Select the enterprise application:

   • Navigate to Identity > Applications > Enterprise applications and select the newly created application.

   • Make a note of the Object ID shown under Overview for additional configuration.

   • Add the desired user under Users and groups.

Configurations for Exchange (online) via Windows PowerShell

If not already installed, install Exchange Online Management in PowerShell.

1. Open Windows PowerShell.

   • Make sure that ExecutionPolicy is set to RemoteSigned:

     Get-ExecutionPolicy
     Set-ExecutionPolicy RemoteSigned

   • Install PowerShellGet:

     Install-Module -Name PowerShellGet -Force

   • Install the cmdlet Exchange Online Management:

     Install-Module -Name ExchangeOnlineManagement   #(for all users)

     OR

     Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser   #(for the currently logged in user)

   • Create a ServicePrincipal and set up permissions in Exchange Online:

     • Open Windows PowerShell.

     • Establish a connection to Exchange Online:

       Connect-ExchangeOnline -UserPrincipalName <USER@example.com>

     • Create the ServicePrincipal. Use the Object ID from the enterprise application:

       New-ServicePrincipal -AppId <ApplicationID> -ObjectId <ObjectID Enterprise Application> -DisplayName <Name>

     • Define mailbox permissions:

       Add-MailboxPermission -Identity <Email@example.com> -User <ObjectID Enterprise Application> -AccessRights FullAccess

Configurations for enaio® server in enaio® enterprise-manager

The following settings are required in enaio® enterprise-manager for using Microsoft Office 365 to send administrator e-mails from enaio® server:

Parameter	Value (registry entry)	Description
E-mail sender	- (MailSender)	The sender’s address to be given to the server when sending e-mails to an administrator account. The address must correspond to the SMTP user name and the configured user.
Administrative e-mails	Allow e-mails (NoMails=0)	Disables or enables the sending of administrative e-mails for the transfer of system events. The log files 'startup.txt' and 'shutdown.txt' are also sent during startup and shutdown.
E-mail server	smtp.office365.com (MailServer)	The IP address or host name of the e-mail server for administrative e-mails.
SMTP encryption	2 (SMTPSecurity=2)	None (0), SSL (1), TLS (2). The corresponding port must also be set during encryption.
SMTP server port	587 (SMTPPort)	Port for SMTP
SMTP authentication	OAuth2 Microsoft Office (SMTPAuthenticating=3)	Authentication method for SMTP.
SMTP user name	- (SMTPUserName)	User name for SMTP login. The address must correspond to the e-mail sender and the configured user.
Microsoft Office client ID	- (OfficeClientID)	Office 365 application ID (client) for e-mail authentication 'OAuth2 Microsoft Office' from the Microsoft Office 365 configuration.
Microsoft Office client secret	- (OfficeClientSecret)	Secret Office 365 client key for e-mail authentication 'OAuth2 Microsoft Office' from the Microsoft Office 365 configuration. The client secret will be encrypted prior to storage and then masked when shown.
Microsoft Office tenant ID	- (OfficeTenantID)	Office 365 directory ID (tenant) for the e-mail authentication 'OAuth2 Microsoft Office' from the Microsoft Office 365 configuration.
-	https://login.microsoftonline.com/#TenantID#/oauth2/v2.0/token (OfficeTokenEndpoint)	Address for the login to Microsoft Office 365. The placeholder #TenantID# is replaced by the value from OfficeTenantID.
-	https://outlook.office365.com/.default (OfficeAccessScopes)	Standard query parameters for SMTP.
-	30 (OfficeTokenGraceTimeInSeconds)	Buffer time (in seconds) that is subtracted from the token expiration to ensure that the token remains valid until the e-mail is actually sent.
The registry entries OfficeTokenEndpoint, OfficeAccessScopes, and OfficeTokenGraceTimeInSeconds are default settings that enaio® enterprise-manager does not display in the server settings. These registry entries should generally only be changed after consultation.

Configurations for enaio® webclient via osweb-prod.yml

The following settings are required in the enaio® service-manager osweb-prod.yml configuration file for using Microsoft Office 365 to send e-mails from enaio® webclient. The configuration can be carried out via enaio® services-admin.

Parameter	Value	Description
featureSwitches.sendEmail.smtpServer	-	SMTP server for sending e-mails, host or IP.
featureSwitches.sendEmail.smtpPort	-	The SMTP server port
featureSwitches.sendEmail.smtpEncryption	TLS	Encryption method: TLS
featureSwitches.sendEmail.smtpAuthentication	MS_OAUTH	Authentication for the SMTP server: MS_OAUTH
featureSwitches.sendEmail.smtpUsername	-	User name for global authentication on the SMTP server. Schema: MS_OAUTH: name@domain.com
featureSwitches.sendEmail.oAuthClientId	-	The application ID (client) for OAuth authentication for sending e-mails from the Microsoft Office 365 configuration.
featureSwitches.sendEmail.oAuthClientSecret	-	The secret client key for OAuth authentication for sending e-mails from the Microsoft Office 365 configuration.
featureSwitches.sendEmail.oAuthTenantId	-	The directory ID (tenant) for OAuth authentication for sending e-mails from the Microsoft Office 365 configuration.