From 24.1.0.0 MIS (Mosaic Interface Server) sends emails by calling a send Email API on the Mosaic WebAPI.
Minimum Mosaic version (after 24.1.0.0)
Mosaic 24.1.0.2 is first version to support msgraph. Mosaic version 24.1.0.2 or later is required when sending attachments using the msgraph protocol. Mosaic version 24.1.0.2 is alsorequired when using SMTP and disabling STARTTLS by setting the enableEmailTLSConnection system property to false.
Deprecation of Basic Authentication
Microsoft will at some point start disabling Basic Authentication for Exchange Online therefore the legacy authentication mechanism in Mosaic and MIS will stop working.
Modern Authentication (OAuth2)
Modern Authentication (OAuth2) can now be implemented with Mosaic to be compliant with future versions of Microsoft Exchange. Basic Authentication model will still work from 24.1, but customers should look to transition across to Modern Authentication at an appropriate date after upgrade.
System properties
2 new system properties have been added:
emailProtocol (values can be set to smtp or msgraph): smtp is used for the standard SMTP email protocol, whereas msgraph is used for MS exchange with new modern authentication mechanism (OAuth2).
emailAuthentication (values can be set to basic or msoauth2): this is used only when SMTP email protocol is set. MS Graph protocol uses OAuth2 by default. N.B. SMTP with OAuth2 is not supported by MS exchange. This has been implemented for potential use with other email service providers (e.g. GMail).
Default values
By default the system properties emailProtocol and emailAuthentication are set to smtp and basic - this is how the Mosaic system uses emails prior to this version update in 24.1.0.0 If you have email setup using smtp and basic authentication prior to the upgrade to 24.1.0.0, this will not be altered when upgrading to 24.1 and no additional steps are required to continue using this functionality.
Email settings screen
The email settings configuration screen changes have been made to accommodate the system property values mentioned above and alter depending on the configuration values used.
When the system property emailProtocol is set to smtp and emailAuthentication is set to basic the configuration screen will be shown as it is now.
When the system property emailProtocol is set to smtp and emailAuthentication is set to msoauth2 the authentication configuration settings screen will include Username, Tenant Id, Client Id, Client Secret and List of Scopes.
When the system property emailProtocol is set to msgraph the emailAuthentication is set to msoauth2 the authentication configuration settings screen will include Username, Tenant Id, Client Id, Client Secret, List of Scopes and the connection settings will include Endpoint.
List of Scopes default value (when left empty) is https://graph.microsoft.com/.default .
Restart required for system property changes
Please note that system properties only take effect when the Mosaic system has been restarted.
Encryption of stored secrets
ClientId for OAuth2 and Password for basic authentication are encrypted into the db. This is documented as a standard Mosaic set up in the Platform Build Guide.
Certificate setup for email sending from Mosaic with SMTP with TLS
For SMTP we need add any required certificates for trust to the cacerts used by the JDK.
Microsoft Exchange Online setup
This is high level guidance for Exchange Online configuration to allow Mosaic to send emails when using the msgraph protocol.
Go to https://portal.azure.com/ and log in with an admin account. You should see the Microsoft Azure Dashboard. Type app registrations in the search box at the top of the screen and click App registrations under Services.
Click New registration
Type GraphAPI Test App in the Name field and select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) as Supported account type. Click Register.
You should be redirected to the Overview screen of the newly created app registration.
Copy the values of the Application (client) ID and Directory (tenant) ID
Click Manage > Certificates & secrets from the left menu and then New client secret.
Type TestAppClient in the Description field, and select 365 days as Expires. Click Add.
Copy the Value of the newly added secret by clicking on the copy icon next to the value.
Note that you must copy the value now, as it will not be possible when accessing this screen later.
Click Manage > API permissions from the left menu and then Add a permission.
Click Microsoft APIs and Microsoft Graph.
Delegated permissions
No delegated permissions are required.
Application permissions
Mosaic requires an application permission to send emails.
Select Mail.Send
Once all the permissions have been added, click Grant admin consent for MSFT and then Yes.
This is the minimum permission needed for Mosaic to send emails using the Graph API.