SMTP OAuth authentication

Azure-side configuration

In the Entra ID environment, it is necessary to register an application with Office 365 Exchange Online / SMTP.SendAsApp permission in Admin Consent mode for the needs of the Team assistant. A Service Account must then be created for this application, which will have the assigned permission to fully manage the email box, whose identity the Team assistant is to use to send email messages.

1. Application registration

1. Permission settings

1. Creating a secret

1. Obtaining Object ID and Client ID

For the next steps, you need to use the Client (Application) ID and Object ID. These values ​​must be obtained from the Managed/Enterprise Application, not from the application registration.

For further configuration, it is also necessary to note the Tenant ID.

1. Creating a service account in Exchange and granting permissions to send with the identity of a specific mailbox

Pairing a newly created application with a specific mailbox can be done using a PowerShell script. To execute it, you need the identifiers obtained from the application in the previous steps.

Import-Module ExchangeOnlineManagement
 Connect-ExchangeOnline -UserPrincipalName "<EXCHANGE_ADMIN_ACCOUNT>"

 New-ServicePrincipal -AppId "<ENTRA_APPLICATION_ID>" -ServiceId "<ENTRA_OBJECT_ID>" -DisplayName "TAS SMTP OAuth"

 Add-MailboxPermission -Identity "<SENDING_USER_EMAIL>" -User "<ENTRA_OBJECT_ID>" -AccessRights FullAccess

Changing the Team assistant backend configuration

In the configuration of all backends (standard deployment, cron deployment), in the local.js file, it is necessary to extend the configuration for sending emails with attributes related to OAuth authentication. In addition to the basic configuration, these are mail.smtp.type amail.smtp.oauth2 attributes (which contains other nested attributes).

A configuration using Exchange Office365 might look like this:

mail: {
 smtp: {
 type: 'oauth2',
 host: 'smtp.office365.com',
 port: 587,
 auth: {
 user: process.env.TAS_SMTP_AUTH_USER,
 },
 oauth2: {
 host:`https://login.microsoftonline.com/${process.env.TAS_SMTP_OAUTH_TENANT_ID}/oauth2/v2.0/token`,
 grantType: 'client_credentials',
 clientSecret: process.env.TAS_SMTP_OAUTH_CLIENT_SECRET,
 clientId: process.env.TAS_SMTP_OAUTH_CLIENT_ID,scope: 'https://outlook.office365.com/.default',
 },
 },
 },

The following environment variables are used in the example:

• TAS_SMTP_AUTH_USER - username for authentication. In most cases, this will match the email address that TAS should use to send emails
• TAS_SMTP_OAUTH_TENANT_ID - Azure Tenant in which the application is created with permission to send using SMTP
• TAS_SMTP_OAUTH_CLIENT_SECRET – secret for an application with permission to send via SMTP
• TAS_SMTP_OAUTH_CLIENT_ID – Client ID of the application with permission to send via SMTP

In addition to this configuration, it is also necessary to consider the sender address that TAS should use when sending email messages. This address is configured using the mail.from attribute, which can be set both in local.js and in the Team assistant GUI administration interface.