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 and via Windows PowerShell.
-
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.
-
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.-
Activate SMTP authentication for this administrator user account by navigating to Mail > Manage email apps and checking Authenticated SMTP.
-
Follow these steps to create an app registration:
-
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.
-
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.
-
-
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.
-
-
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.
-
-
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.
-
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. |
- (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:
|
featureSwitches.sendEmail.smtpAuthentication | MS_OAUTH |
Authentication for the SMTP server: |
featureSwitches.sendEmail.smtpUsername | - |
User name for global authentication on the SMTP server. Schema:
|
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. |