Email notifications

DISCLAIMER

This page contains third-party references. We strive for our content to always be up-to-date, however, the content referring to external vendors may change independently of Omada. If you spot any inconsistency, please report it to our Helpdesk.

Omada Identity offers a comprehensive email notification feature designed to streamline communication processes within your organization. By utilizing customizable email templates, you can effortlessly generate and dispatch notifications for various events triggered within the system.

Whether it's notifying stakeholders about access requests, sharing survey results, or updating personnel on organizational changes, Omada Identity's email templates provide the flexibility to tailor messages to specific scenarios. Events such as access request approvals, rejections, or assignment removals due to access reviews can automatically trigger email notifications, ensuring timely and efficient communication.

Setting up sending mails for Cloud customers

For information on how to set up sending mails in the Omada Identity Cloud portal, refer to the Email delivery section in the Creating environment documentation.

Setting up sending mails on-prem

You can configure sending emails by defining the host name, port, TLS configuration, and authentication method.

The notificationSettings XML schema is available under the following path: <website root>/Schema/NotificationSettingsML.xsd.

Follow these steps to set up port and host name:

1. Go to Setup > System settings > Configuration objects.

2. Open the configuration object notificationSettings.

3. Set up the port and host name in the XML schema:

   <?xml version="1.0" encoding="utf-8">
   <notificationSettings xmlns="http://schemas.omada.net/ois/2022/NotificationSettingsML">
             <smtp>  
               <network
                 host="mail.name-domain.com"
                 port="25"
                 secureSocketOptions="StartTlsWhenAvailable" >

4. Optionally, you can change the SecureSocketOptions default security configuration StartTlsWhenAvailable to one of the following values:

   • StartTlsWhenAvailable - this is the default configuration. It supports the SMTP Service Extension for Secure SMTP over Transport Layer Security as defined in RFC 3207. In this mode, the SMTP session begins on an unencrypted channel, then a STARTTLS command is issued by the client to the server to switch to secure communication using SSL.
   • None - no SSL or TLS encryption should be used.
   • Auto - allows the IMailService to decide which SSL or TLS options to use (default). If the server does not support SSL or TLS, then the connection will continue without any encryption.
   • SslOnConnect - an alternate connection method is where an SSL session is established up front before any protocol commands are sent. This connection method is sometimes called SMTP/SSL, SMTP over SSL, or SMTPS and by default uses port 465.
   • StartTls - elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server.

Next, depending on the authentication type, the parameters needed will vary.

warning

Vault Service
Instead of storing sensitive information locally in Omada Identity, we recommend using the Vault Service, which is able to fetch secrets from external vault services.

For more information, see Vault Service (Cloud) or Vault Service (On-prem).

StringEncrypter
We recommend using the StringEncrypter utility to encrypt strings (for example, passwords) before storing them in the configuration files.

For more information, see the StringEncrypter section of Additional security aspects.

Anonymous authentication

This setup is for testing purposes only. When connecting to the SMTP service, Omada Identity gets the capabilities of the SMTP service:

• If the SMTP service supports anonymous authentication, then, Omada Identity authenticates using SASL anonymous authentication protocol.

note

If you are using Exchange, follow Microsoft guidelines to configure Exchange for anonymous authentication.

<?xml version="1.0" encoding="utf-8">
<notificationSettings xmlns="http://schemas.omada.net/ois/2022/NotificationSettingsML">
    <smtp>  
       <network
          host="mail.name-domain.com"
          port="25"
       <anonymous 
          userName = ""/>
       </network>
    </smtp>    
</notificationSettings>

NTLM authentication

No parameter value is needed.

<?xml version="1.0" encoding="utf-8">
<notificationSettings xmlns="http://schemas.omada.net/ois/2022/NotificationSettingsML">
          <smtp>  
            <network
              host="mail.name-domain.com"
              port="25">
              <defaultCredentials />
            </network>
          </smtp>
</notificationSettings>

Basic authentication

The following parameters are needed:

• userName - the user name associated with the credentials.
• password - the password for the user name associated with the credentials.

<?xml version="1.0" encoding="utf-8">
<notificationSettings xmlns="http://schemas.omada.net/ois/2022/NotificationSettingsML">
  <smtp>
    <network
        host="mail.name-domain.com"
        port="25">
    <basic 
        userName="" 
        password="" />
    </network>
  </smtp>
</notificationSettings>

Microsoft Entra ID authentication

This setup is only for Microsoft Entra ID Password Grant. The following parameters are needed:

• instance - specify an instance. If not, your app will target the Azure public cloud instance (the instance of URL https://login.onmicrosoftonline.com).
• clientId - the Application (client) ID that the Azure portal - App registrations page assigned to your app.
• tenantId - the directory tenant that you want to log the user into.
• userName - the user name associated with the credentials.
• password - the password for the user name associated with the credentials.
• scopes - space-separated list of permissions, that the app requires.

For more detailed information, refer to the Microsoft documentation.

<?xml version="1.0" encoding="utf-8">
<notificationSettings xmlns="http://schemas.omada.net/ois/2022/NotificationSettingsML">
          <smtp>
            <network
              host="smtp.office365.com"
              port="587">
              <azureAdPasswordGrant
                instance="https://login.microsoftonline.com"
                clientId="7A83471E-A8C7-4C06-8120-77B9AA56FA04"
                tenantId="2487ABFA-47FC-4F60-8AF4-2B857B17432C"
                userName="example@megamart.onmicrosoft.com"
                password="xxx"
                scopes="https://outlook.office365.com/.default"
              />
            </network>
          </smtp>
</notificationSettings>

No authentication

• If the SMTP server does not require authentication but still supports it, you shouldn't provide any authentication in the settings. SMTP authentication will then be skipped automatically.

• If the SMTP service does not support authentication, then, Omada Identity doesn't attempt to authenticate with the SMTP service.

Email sending process

Once everything is configured, a process within the Time Service will be responsible for executing the task. This process will continuously run, checking for pending emails as long as the Timer Service is operational. Every 6 seconds, it will retrieve a batch of pending emails and send them using the configurations specified in the notificationSettings object.

The size of the batch of pending emails sent every 6 seconds can be defined in the customer setting MailQueueBatchSize. If not explicitly defined, its default value will be set to 10.

Error handling and retry policy

In the event of an error during the sending process, the failed email will be scheduled for delivery after a specified interval for a certain number of attempts. This policy is designed to manage transient failures associated with temporary unavailability of the service.

To prevent unnecessary retries when encountering connection errors to the email server, emails will remain in the mail queue until a successful connection is established.

The interval between retries and the maximum number of retries can also be defined in the customer settings MailQueueRetryInterval and MailQueueMaxRetries. Their default values are 60 minutes and 1 retry, respectively.

For more information on the Mail queue delivery retries setting, refer to the Mail section in the Customer settings documentation.