SMTP email service

IAM sends emails to end-users in several scenarios, including:

  • During authentication, when email OTP is used as a second authentication factor (via the Email OTP Authentication Step).
  • During self-registration, to verify the end-user's email address (via the Email Verification Step).
  • During public self-service flows, such as password reset or self-unlock, to verify the end-user's identity (via the Email Identity Verification Step).
  • During protected self-service flows, when an end-user changes their email address (via the Email Verification Step).

IAM delivers these emails using SMTP (Simple Mail Transfer Protocol). SMTP transfers messages from the IAM system to the recipient’s mail server. As a send-only protocol, it is responsible only for message submission and relay.

 
Notice

IAM also supports a dummy email service. This service does not transmit the email but instead prints the message details into the log file (INFO log level). Use this for testing purposes.

IAM SMTP plugins

IAM provides the following plugins to configure email-sending with SMTP: the SMTP Email Service plugin and the SMTP Email Server plugin. They must be set when using the steps mentioned above.

The SMTP Email Service defines general email-sending properties, such as

  • the SMTP email server to use,
  • the sender address used by IAM (e.g., airlock@yourcompany.com),
  • the character set used in the message body (default: UTF-8), and
  • the encryption algorithm.

The SMTP Email Server plugin defines how IAM connects to the SMTP mail server. This includes:

  • the SMTP server host name (e.g., outlook.office365.com),
  • the port number (typically 25, 465 or 587),
  • the connection and read timeouts, and
  • the authentication mechanism used to authenticate to the SMTP server.

Supported authentication methods

IAM supports two authentication methods for SMTP:

  • Username/password authentication, via the SMTP Authentication With Username/Password plugin. This method is also known as the SMTP AUTH LOGIN mechanism, and referred to by Microsoft as “Basic Authentication” or Basic Auth.
  • OAuth 2.0 Client Credentials (also called XOAUTH2), via the SMTP Authentication With OAuth 2.0 Client Credentials Grant plugin.
 
Notice

Currently, basic authentication with username and password is still the primary authentication method used for SMTP in IAM.

However, Microsoft considers Basic Authentication a legacy and less secure method (because it uses static credentials rather than token-based modern authentication). Therefore, Microsoft plans to permanently disable Basic Authentication for the SMTP AUTH endpoint in Exchange Online by April 30th, 2026 (with partial enforcement starting around 1 March 2026).

After April 30th, 2026, applications or devices will no longer be able to authenticate to Microsoft’s SMTP submission service with username and password. They must use OAuth 2.0 based credentials to send emails via Microsoft services.

This change affects at least the following Microsoft SMTP submission endpoints (typically using port 587):

  • smtp.office365.com
  • outlook.office365.com
  • smtp-legacy.office365.com

For details on configuring SMTP authentication with OAuth 2.0, see below.

SMTP authentication with OAuth Client Credentials Grant

This section describes how to configure authentication to the SMTP server with OAuth 2.0, by using the OAuth 2.0 Client Credentials Grant.

  1. In the Config Editor, search for and open the SMTP Email Server plugin dialog.
  2. In the plugin's Authentication section, Authentication field, select the SMTP Authentication With OAuth 2.0 Client Credentials Grant plugin. Configure the plugin's attributes as follows:
  3. Username: Defines the username used to authenticate to the SMTP mail server. For example: smtp-user@yourcompany.ch.
  4. Access Token Provider: Configures the OAuth 2.0 Client Credential Grant used to obtain the access token. Create an OAuth2 Access Token String Value Provider plugin, which can be used to retrieve, cache and provide the access token. After obtaining the token, IAM caches it until expiration, and automatically fetches a new token when required. Specify the plugin's attributes as follows:

  5. OAuth2 Access Token String Value Provider plugin configuration

    • Client ID: The client ID is used to identify IAM at the OAuth 2.0 provider's endpoints (authorization, token and resource).
      • For Microsoft services, contact Microsoft to obtain the client ID.
    • Client Secret: The client secret is used to verify the client.
      • For Microsoft services, contact Microsoft to obtain the client secret.
    • Access Token Request Method: Specifies the required HTTP method used for the access token exchange. Select OAuth 2.0 POST Request (this is the default).
    • HTTP Client: Specifies the HTTP client that handles all requests to the token and resource endpoints. Create an HTTP Client Config plugin. Keep the default settings.
    • Token Endpoint Authentication: Specifies how to include the client secret for authentication in requests to the token endpoint.
      • Select OAuth 2.0 Basic Auth Client Secret - this is the default, based on the HTTP basic authentication scheme.
      • However, you can also choose other ways to pass the client secret, for example, in the request header (OAuth 2.0 Header Client Secret) or as a request parameter (OAuth 2.0 Parameter Client Secret). It is also possible to authenticate with a JWT token (OIDC Private Key JWT Client Authentication).
    • Token Endpoint URL: Defines the URL of the token endpoint from which IAM obtains the access tokens.

    • For the Microsoft services, use the following URL:

    • https://login.microsoftonline.com/<MS tenant ID>/oauth2/v2.0/token
    • Scopes to Request: Defines the scopes to request from the token endpoint.
      • For Microsoft services, the correct scope is https://outlook.office365.com/.default
  6. Activate your settings.
  7. You have now configured an SMTP email server that uses the OAuth 2.0 Client Credentials Grant to send emails via Microsoft services.