Email from STEP

Multiple functional areas of STEP support using email to deliver data, error reports, workflow notifications, and other messages.

Further information about how email can be used in functional areas is available in the following topics:

Asset Push - as defined in the Monitoring Asset Push topic and the Creating and Maintaining Asset Push Configurations topic
Bulk Updates using a business action - as defined in the Scheduling a Task Notification Email topic
Event Processors - as defined in the EP - Error Handling and Reporting topic
Export Manager - as defined in the Email Delivery Method topic
IIEPs - as defined in the IIEP - Error Handling & Reporting topic
OIEPs - as defined in the OIEP - Configuration Section topic
Workflows - as defined in the Send Email from a Workflow topic

Instead of using the default mail relay server, you can configure a custom mail relay server. The required configuration for each authentication method is detailed below.

Mail Server with Basic Authentication Configuration

When using basic authentication, every time a user or functional area within STEP sends an email, a username and password are exchanged with the configured mail relay service. Basic authentication is increasingly considered outdated and vulnerable, and many widely used email services, such as Office 365, plan to discontinue support.

Note: Microsoft has announced that Basic authentication will be deprecated for client submissions within their Exchange Online / Office 365 mail service in September 2025. Search the web for details.

To use a mail server with basic authentication, submit a Stibo Systems Service Portal ticket and include the relevant values for your environment on these configurations:

Provide the mail server URL, such as smtp.office365.com, for the Mail.MailServerURL configuration.
Provide the mail server port, such as 587, for Mail.MailServerPort configuration.
If TLS should be used in connection to the mail server, request to set the Mail.UseTLS configuration to 'true'.
Provide the default mail address displayed in the 'From' field, such as noreply@mailserver.com, for the Mail.DefaultFromMailAddress configuration.

If no default mail address is provided, STEP sets the default 'From' email address as noreply@step-system.invalid.
Provide the authorized user name, such as AuthUser, for the Mail.MailAuthenticationUser.Name configuration.
Provide the authorized user password, such as AuthPassword, for the Mail.MailAuthenticationUser.Password configuration.

Note: This configuration holds the password of the authorized user. When that password changes, the value on this configuration must also be updated.

Mail Server OAuth 2.0 Authentication Configuration

When using OAuth 2.0 to send an email from STEP, first an access token is requested from an authorization service using a client ID and a password or a client ID and a certificate. Once the authorization service accepts the request, it provides an access token with a limited lifetime to STEP, and during that lifetime, STEP uses that token to authenticate when sending email.

To use a mail server with OAuth 2.0 instead of Basic authentication, submit a Stibo Systems Service Portal ticket and include the relevant values for your environment on these configurations:

Provide the mail server URL, such as smtp.office365.com, for the Mail.MailServerURL configuration.
Provide the mail server port, such as 587, for the Mail.MailServerPort configuration.
If TLS should be used in the connection to the mail server, request to set the Mail.UseTLS configuration to 'true'.
Provide the authorized user name, such as AuthUser, for the Mail.MailAuthenticationUser.Name configuration.
Provide the OAuth scope, such as https://outlook.office365.com/.default, for the Mail.OAuth.Scope configuration.
Provide the appropriate URL, such as https://login.microsoftonline.com/[Tenant-ID]/oauth2/v2.0/token, for the Mail.OAuth.TokenService.URL configuration. Replace the text in the brackets with your own tenant ID.
Identify the required authentication option:
- To use a Client ID / Client Secret, use the following configurations:
  - Provide the Client ID for the Mail.OAuth.ClientID configuration.
  - Provide the secret for the Mail.OAuth.ClientSecret configuration.
- To use a Client ID / Certificate, use the following configurations:
  - Provide the Client ID for the Mail.OAuth.ClientID configuration.
  - Provide the keystore file or location for the Mail.OAuth.ClientKeyStore configuration.
  - Provide the keystore password for the Mail.OAuth.ClientKeyStore.Password configuration.

Mail Server OAuth Authentication - Office 365 / Exchange Online Configuration

When Office 365 / Exchange Online is used as mail server, specific configuration steps are required to enable OAuth authentication. The following section outlines the necessary instructions that can be shared with email administrators to complete the configuration within Azure.

Create a user in your Azure tenant with an active mailbox that can send mails on behalf of the STEP application.
Create a Service Principal (Enterprise Application) with a corresponding App registration with the following API Permissions:
- Application -> Office 365 Exchange Online -> IMAP.AccessAsApp
- Application -> Office 365 Exchange Online -> SMTP.SendAsApp
  
  Admin consent is granted for both API Permissions as shown in the following image.
Create a Client Secret or Client Certificate that is active and not expired.
Register the Service Principal (Enterprise Application) within Exchange Online using PowerShell:
- Connect-ExchangeOnline
- New-ServicePrincipal - AppId <Application-ID> - ObjectId <Object-ID> (information from the Service Principal mentioned in step 2)
Assign mailbox permissions to the mailbox created in step 1 using PowerShell:
- Add-MailboxPermission - Identity "mailbox@customer.tld" - User "<Object-ID from step 4>" - AccessRights FullAccess
Enable SMTP AUTH for the mailbox:
- admin.microsoft.com > Users -> Active Users -> Select mailbox > Mail -> Manage email apps -> Authenticated SMTP, as shown in the following image.