Introduction

To comply with Microsoft's deprecation of plain password authentication when using their SMTP servers, WebADM is able to use XOAUTH2 as the authentication method when it sends email through Exchange Online/Office 365's SMTP service. You will need to register an app and associated secret in Entra ID for WebADM to use, then a mailbox in Exchange Online to send emails as, and finally tell WebADM about both in servers.xml.

This method also involves disabling security measures, i.e. the "Security Defaults" of Entra ID, and allowing SMTP authentication for one mailbox.

Start a PowerShell session and set up some variables that will be used throughout. $TenantID, $AdminUpn should match your infrastructure, and $Mailbox is the Exchange mailbox you have already created for WebADM (it must be licensed). The other variables need only be different from existing app names, scope groups and scopes, respectively.

$TenantId   = '<tenant-guid>'
$AdminUpn   = 'admin@contoso.onmicrosoft.com'
$AppName    = 'webadm-smtp'
$Mailbox    = 'webadm@contoso.com'
$ScopeGroup = 'webadm-scope-group'
$ScopeName  = 'webadm-scope'

Install the modules you will need if they are not installed for your user yet:

Install-Module -Name Microsoft.Entra -Repository PSGallery -Scope CurrentUser -Force -AllowClobber
Install-Module -Name Microsoft.Graph -Scope CurrentUser -Force -AllowClobber
Install-Module -Name ExchangeOnlineManagement -Scope CurrentUser -Force

Create the Entra ID app

Register a new app, and create a secret for WebADM to identify itself with, when fetching an OAuth2 token.

Connect-Entra -TenantId $TenantId           
$app = New-EntraApplication -DisplayName $AppName
$sp  = New-EntraServicePrincipal -AppId $app.AppId -DisplayName $AppName
$pwd = New-Object Microsoft.Open.MSGraph.Model.PasswordCredential
$pwd.DisplayName   = 'webadm secret'
$pwd.StartDateTime = Get-Date
$pwd.EndDateTime   = (Get-Date).AddYears(1)
$secret = New-EntraApplicationPassword -ApplicationId $app.Id -PasswordCredential $pwd
Disconnect-Entra

Disable Security Defaults

Security Defaults disables SMTP authentication altogether, and we cannot leave it enabled. Understand what this entails: https://learn.microsoft.com/en-us/entra/fundamentals/security-defaults

Connect-MgGraph -TenantId $TenantId
Update-MgPolicyIdentitySecurityDefaultEnforcementPolicy -BodyParameter @{ isEnabled = $false }
Disconnect-MgGraph

Allow the app to use its mailbox

Exchange Online has its own layer of security, and it needs to be configured to let the Entra app use a particular mailbox.

Connect-ExchangeOnline -UserPrincipalName $AdminUpn
Set-CASMailbox -Identity $Mailbox -SmtpClientAuthenticationDisabled $false
New-ServicePrincipal -AppId $app.AppId -ObjectId $sp.Id -DisplayName $AppName
New-DistributionGroup -Name $ScopeGroup -Alias $ScopeGroup
Add-DistributionGroupMember -Identity $ScopeGroup -Member $Mailbox
$dg = Get-DistributionGroup -Identity $ScopeGroup
New-ManagementScope -Name $ScopeName -RecipientRestrictionFilter "MemberOfGroup -eq '$($dg.DistinguishedName)'"
New-ManagementRoleAssignment -App $sp.Id -Role "ApplicationImpersonation" -CustomRecipientWriteScope $ScopeName
Disconnect-ExchangeOnline

Set up WebADM

You should now have a client ID: $app.AppId, and a client secret: $secret.SecretText. Use them in a new MailServer section in /opt/webadm/conf/servers.xml, like so:

<MailServer name="SMTP Server"
        host="smtp.office365.com"
        port="587"
        oauth="<tenant id>:<client id>"
        password="<client secret>"
        user="<mail box>"
        encryption="TLS"
        ca_file="" />

Restart the WebADM service (systemctl restart webadm, or /opt/webadm/bin/webadm restart if you've opted for directly using the init script), and test that mails get sent properly by logging into the web admin interface, and under the Admin tab, clicking "Send Test Alert Email" (bottom right).

Troubleshooting

  • Connect-ExchangeOnline and Connect-Entra may need -Device if the usual shortcuts for authentication are not available (such as when using pwsh on Linux).

  • New-ManagementRoleAssignment may complain that you do not "have access to create, change, or remove" the management role assignment. Add yourself to the group "Organization Management": Add-RoleGroupMember "Organization Management" -Member $AdminUpn -BypassSecurityGroupManagerCheck, then Disconnect-ExchangeOnline and connect again, and finally retry New-ManagementRoleAssignment.

  • New-ManagementScope may complain that "the command you tried to run isn't currently allowed in your organization". Invoke Enable-OrganizationCustomization, like the error message suggests.