Configure an SMTP server

Go to Administration > SMTP.

Basic elements

Address: SMTP server’s address
Port: Port used by the SMTP server
Encryption: Encryption of the connection to the SMTP server (STARTTLS, TLS or Clear)
Domain: Domain used by the SMTP server
Authentication: Authentication method with the SMTP server (PLAIN, LOGIN, CRAM-MD5 or OAuth 2.0 (Microsoft 365))
Username: Username used to establish a connection to the SMTP server
Password: Password of the username previously informed
Azure credential: Stored credential that provides the access token, instead of the password, with OAuth 2.0 (Microsoft 365) authentication
Sender: Email address that will be used by Cyberwatch

Configure a non-authentication server

To configure an SMTP server without authentication, simply leave the Username and Password fields empty.

If an error occurs, it’s possible to delete the current configuration with the Delete button, and then, put the desired configuration.

OAuth 2.0 authentication with Microsoft 365

Microsoft is retiring SMTP password authentication on Exchange Online (timeline). With OAuth 2.0 (Microsoft 365) authentication, Cyberwatch obtains an access token from Microsoft Entra ID for an application registered in your tenant, then authenticates with this token to the SMTP server.

The configuration takes three steps: the application in Microsoft Entra ID, its access to the mailbox in Exchange Online, then the Cyberwatch SMTP form.

Create the application in Microsoft Entra ID

From the Microsoft Entra admin center, in the App registrations menu, create a new app registration, with the account type Accounts in this organizational directory only
Note the Application (client) ID and the Directory (tenant) ID, displayed on the Overview page of the application
From Certificates & secrets, create a client secret. It is also possible to authenticate with a certificate generated by Cyberwatch, as described in Configure API accesses
From API permissions, click on Add a permission, then in the APIs my organization uses tab, search for Office 365 Exchange Online
Click on Application permissions, check SMTP.SendAsApp, then click on Add permissions
Grant admin consent for this permission, from the same page

Allow access to the mailbox in Exchange Online

The service principal of the application must then be registered in Exchange Online, and be given access to the sending mailbox. These operations are done with the ExchangeOnlineManagement PowerShell module:

Install-Module -Name ExchangeOnlineManagement
Connect-ExchangeOnline -Organization <TENANT_ID>
New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID> -DisplayName "Cyberwatch SMTP"
Get-ServicePrincipal -Identity "Cyberwatch SMTP" | Format-List
Add-MailboxPermission -Identity "cyberwatch@contoso.com" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

With:

<TENANT_ID>: the Directory (tenant) ID
<APPLICATION_ID>: the Application (client) ID
<OBJECT_ID>: the Object ID displayed in the Enterprise applications menu, on the Overview page of the application
<SERVICE_PRINCIPAL_ID>: the value of the Identity field returned by Get-ServicePrincipal
cyberwatch@contoso.com: the address of the sending mailbox

The Object ID to use is that of the enterprise application, not that of the app registration. With the wrong Object ID, authentication fails.

If the address entered in the Cyberwatch Sender field differs from the sending mailbox, also allow the application to send as this sender:

Add-RecipientPermission -Identity <SENDER> -Trustee <SERVICE_PRINCIPAL_ID> -AccessRights SendAs

If SMTP authentication (SMTP AUTH) is disabled at the tenant level, enable it for the sending mailbox:

Set-CASMailbox -Identity "cyberwatch@contoso.com" -SmtpClientAuthenticationDisabled $false

Configure Cyberwatch

From Settings > Stored credentials, create a credential of type Microsoft Entra ID (Azure or Microsoft 365), with the tenant ID, the Application (client) ID and the client secret, as described in Configure API accesses. On an instance deployed on AKS, the credential can also authenticate with Azure Workload Identity
Go to Administration > SMTP and fill in the following fields:
Field Value
Address smtp.office365.com
Port 587
Encryption STARTTLS
Authentication OAuth 2.0 (Microsoft 365)
Username The address of the sending mailbox
Azure credential The credential created in the previous step
Click on Save
Send a test email from the Send a test email section

Field	Value
Address	`smtp.office365.com`
Port	`587`
Encryption	STARTTLS
Authentication	OAuth 2.0 (Microsoft 365)
Username	The address of the sending mailbox
Azure credential	The credential created in the previous step

The access token request goes through the proxy configured in Administration > Proxy, unless the credential has the proxy bypass option. The connection to the SMTP server, however, does not go through the proxy.

A credential used by the SMTP configuration cannot be deleted.

Common errors

In case of failure, the test email displays the message returned by Microsoft:

HTTP 401: AADSTS7000215: Invalid client secret…: the client secret of the credential is invalid or has expired
535 5.7.3 Authentication unsuccessful: the service principal is not registered in Exchange Online, was registered with the wrong Object ID, or does not have access to the sending mailbox