Azure SMTP mail server with Oauth2

1. Setting up an Azure SMTP mail server with Oauth2

1.1 Azure configuration

Press "Microsoft Entra ID"

Select "App Registrations" from the menu on the left.

If your app isn't registered, follow the Microsoft app registration steps before proceeding. (https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)

If the app is already registered, choose the "All Apps" tab

Select your app.

Note the information at the top of the page. You'll need the directory and application credentials.

Application ID (Client)
Directory ID (tenant)

Tap "Allowed APIs" in the menu on the left.

Choose "Add Permission"

In the new window, choose "APIs used by my organization"

Type "Office 365" in the search bar.

Choose "Office 365 Exchange Online" from the results.

Choose "App Permissions"

Open the "Mail" section and check the "Mail.Send" permission

Open the "SMTP" section and check the "SMTP. SendAsApp »

Tap "Add Permissions" at the bottom of the window.

Tap "Grant admin consent to..." to the right of the "Add Permission" option

Choose "Yes" in the new window and log in with an admin account if requested.

Tap "Certificates & Secrets" in the menu on the left.

Choose "New Client Secret"

Provide a description and expiration date for the secret.

Tap "Add" at the bottom of the window.

Note the "Value" of the generated secret. This information is only available for a limited time after creation. If this information is lost, a new secret will have to be regenerated.

1.2 Exchange Configuration

Tap "Microsoft Entra ID"

Choose "Enterprise Apps" from the menu on the left.

Select your app.

Note the value of "Object ID"

Open a "Powershell" window as an administrator on your Windows computer.

Run "Install-Module -Name ExchangeOnlineManagement -RequiredVersion 3.4.0"

Run "Set-ExecutionPolicy -ExecutionPolicy RemoteSigned"

Run "ExchangeOnlineManagement Import-module"

Run "Connect-ExchangeOnline -Organization [tenantId]" where [tenantId] is the value of "Directory ID" in Azure above.

Run "New-ServicePrincipal -AppId [appId] -ObjectId [objId]" where [appId] is the value of "Application ID" in Azure above and [objId] is the value noted in step 5.

Run "Get-ServicePrincipal | fl" to see the info of the service created.

Note the value of "ExchangeObjectId"

Run "Add-MailboxPermission -Identity "[username]" -User [exchangeId] -AccessRights FullAccess" where [username] is the value of the mailbox from which you want to send emails and [exchangeId] is the value noted in step 14.

Validate that the permission has been added with "Get-MailboxPermission -Identity "[username]"" and validate that there is an entry for your [objId] from step 5

Run "Set-TransportConfig -SmtpClientAuthenticationDisabled -$false"

Run "Disconnect-ExchangeOnline"

Turnaround time

Note that there is a delay between when commands are executed and when changes are actually affected in Azure services.

Note that if the license of the user to whom the "Add-MailboxPermission" permission was created is withdrawn, the permission also seems to disappear. It will therefore be necessary to repeat steps 15 and 16 to give it a licence after giving it a licence. If a user does not have a license, it will be impossible to create permission for them, the system will return an error that this user cannot be found.

1.3 Constellio configuration in "Application" mode

Select "Control" from the menu on the left.

Choose "Configure Mail Server" to change your existing configuration to Oauth2.

Check the " Enabled " box;

Choose "Application" as your authentication mode.

Fill in the "Username" and "Default Sending Email" fields with the value of the box configured in the Exchange section above.

Fill in the "Tenant Identification" fields with the value of "Directory ID" from the "Azure" section above.

Fill in the "Application Identification" fields with the value of "Application ID" from the "Azure" part above.

Fill in the "Client Secret" field with the value of the secret generated in the "Azure" section above.

In the "Server Property" section, add the line "mail.smtp.auth.mechanisms=XOAUTH2"

Tap "Save" at the bottom of the page.

1.4 Server proprieties

Here's a functional example :

mail.smtp.port=587
mail.smtp.starttls.required=true
mail.smtp.auth=true
mail.smtp.starttls.enable=true
mail.smtp.socketFactory.port=587
mail.smtp.host=smtp.office365.com
mail.smtp.auth.mechanisms=XOAUTH2