Synchronizing User Accounts with Microsoft 365 - Modern Authentication

In addition to adding users manually as described in chapter User Management, MailStore Server can synchronize its internal user database with the Microsoft 365 tenant of your organization.

Tech Tip: Preparation of the Microsoft 365 Tenant and User Synchronization

During synchronization, user information, such as user names and email addresses, is copied from the Microsoft 365 tenant into MailStore Server's user database. That way, users can use their Microsoft 365 credentials to also log on to MailStore Server and emails can be assigned to their corresponding user archives automatically, for example. No changes are made to the Microsoft 365 tenant itself by MailStore Server. The scope of the synchronization can be limited through filters.
Our Tech Tip video shows the essential configuration steps in this article.

Prerequisites, Recommendations and Limitations

For best user experience, the certificate used by MailStore Server should be trusted by all clients and the used web browsers. Using a certificate that is signed by a trusted certificate authority or using Let's Encrypt certificates is highly recommended.
If you have archived emails from an Exchange server and synchronized users from an Active Directory until now, follow the article Changing Archiving from Microsoft Exchange Server to Microsoft 365
If users are supposed to log in to MailStore Server from outside the organization's network without a VPN using MailStore Client, MailStore Outlook Add-in or the Web Access, the URIs mentioned in this article must be resolvable via DNS on the Internet and port-forwardings to the MailStore Server computer must be set up on the firewall or router if necessary.
When using Microsoft 365 to authenticate users at login, accessing the archive via IMAP is not possible for technical reasons.
MailStore Server supports the synchronization of user accounts with the global Microsoft Cloud Microsoft 365 and Office 365, operated by 21Vianet. Other Environments like GCC, GCC High or DoD are not supported. In the following article, only the term Microsoft 365 is used for the sake of simplicity.

Connecting MailStore Server and Microsoft 365

In order to synchronize user information from Microsoft 365, MailStore Server has to be connected to your Microsoft 365 tenant and been granted the required permissions. Microsoft 365 relies on Microsoft Entra ID as directory service. Each Microsoft 365 tenant corresponds to an Microsoft Entra ID tenant that stores its user information.

Registering of MailStore Server as App in Microsoft Entra ID

Through registration, MailStore Server gets an identity in Microsoft Entra ID that makes it possible to authenticate to the tenant's services and use their resources.

Sign in to the Microsoft Entra ID Portal as a Global Administrator for your Microsoft 365 tenant.
The Microsoft Entra ID Portal of Office 365, operated by 21Vianet can be accessed here.
In the navigation menu (☰), select the option Microsoft Entra ID.
On the next page, select App registrations in the Manage section of the left navigation menu.
Select New Registration. The Register an application page appears.
In the Name field, enter a meaningful display name, e.g. MailStore Server. This name will be shown to users on logon later on, for example.
Leave all other settings on this page to their defaults.
Click on Register. If the registration has been successful, you are shown the overview page of the newly registered app.

The Application (client) ID shown on this page identifies MailStore Server in your Microsoft Entra ID tenant and has to be copied into MailStore Server next, together with the Directory (tenant) ID. Therefore, for the following steps, leave the overview page open in your web browser.

Creating Credentials in MailStore Server

Credentials for Microsoft 365 consist of the aforementioned IDs and a secret that MailStore Server uses to proof its identity to Microsoft Entra ID. Microsoft recommends using certificates as secrets to identify apps in Microsoft Entra ID. When creating credentials, such a certificate is generated automatically by MailStore Server but can also be recreated later on.

Log on to MailStore Client as a MailStore Server administrator.
Click on Administrative Tools > Users and Archives > Directory Services.
In the Integration section, change the directory service type to Microsoft 365 (Modern Authentication) or Microsoft 365 operated by 21 Vianet (Modern Authentication).

In the Connection section, click on the button (…) next to the Credentials drop-down list.
In the Credential Manager that appears, click on Create…
In the Microsoft Entra ID App Credentials dialog, enter the following information in the Settings section:
- Name
  A meaningful display name for the credentials, e.g. the name of your Microsoft 365 tenant.
- Application (client) ID
  The value of the corresponding field that you can copy from the Microsoft Entra ID app overview page in your web browser.
- Directory (tenant) ID
  The value of the corresponding field that you can copy from the Microsoft Entra ID app overview page in your web browser.

In the Authentication section, click on the drop-down button next to the Certificate text box und select Download Certificate. Save the certificate on your hard drive.
Confirm your entries by clicking OK.
The newly created credentials are listed in the Credential Manager under the name you have entered with the type Microsoft 365. Here you can also edit or delete existing credentials if necessary.
Leave the Credential Manager by clicking Close.
The newly created credentials are selected in the corresponding drop-down list by default.

Publishing Credentials in Microsoft Entra ID

For Microsoft Entra ID to validate the identity of MailStore Server, the created certificate needs to be published in Microsoft Entra ID.

Switch to the Microsoft Entra ID app overview page in your web browser.
Select Certificates & secrets in the Manage section of the left navigation menu.
Click on Upload certificate in the Certificates section. Select the certificate file that you have saved previously and upload it to Microsoft Entra ID by clicking Add.
If uploading has been successful, the certificate's thumbprint as well as its start and expiry dates appear in the certificates list. You can compare the thumbprint and expiry date with those listed in the MailStore Credential Manager to check that you've uploaded the correct certificate.

Configuring App Authentication in Microsoft Entra ID

For Microsoft Entra ID to return the result of a user's authentication request to MailStore Server, the endpoint where MailStore Server expects authentication responses, the so-called Redirect URI, has to be conveyed to Microsoft Entra ID.

In the Microsoft Entra ID Portal in the web browser, select Authentication in the Manage section of the left navigation menu.
Click on the Add a platform button in the Platform configurations section of the Authentication page.
Select Web in the Web applications section of the Configure platforms menu page.
Enable the ID tokens option in the Implicit grant section.
In the field Redirect URI, enter a URI in the format (without brackets)
https://<fqdn>[:<port>]/oidc/signin

with the following components:

https://
Specifying the https:// protocol is obligatory. To avoid certificate warnings during user logon, the web browsers on the client machines must trust the certificate used by MailStore Server.

FQDN
The Fully Qualified Domain Name (FQDN) of your MailStore Server that consists of the machine name and the DNS domain, e.g. mailstore.example.com. This name must be resolvable by all clients from which users shall be able to log on to MailStore Server.

Port
The TCP port of the MailStore Web Access (8462 by default). This value must be equal to the port configured in the section Base Configuration > Network Settings > MailStore Web Access / Outlook Add-in (HTTPS) of the MailStore Server Service Configuration. The TCP port has to be specified only if it is different from the default port of the HTTPS protocol (443).

/oidc/signin
The endpoint where MailStore Server expects the authentication responses of Microsoft Entra ID. This path has to be specified exactly as stated here at the end of the redirect URI.
Leave the field Logout URL blank.
Click on Configure to finish the configuration of the app authentication in Microsoft Entra ID.

Examples for valid redirect URIs
Product	FQDN	Port	Resulting Redirect URI
MailStore Server	mailstore.example.com	8462	`https://mailstore.example.com:8462/oidc/signin` Redirect URI with Fully Qualified Domain Name and MailStore Web Access default port
MailStore Server	mailstore.example.com	443	`https://mailstore.example.com/oidc/signin` The port can be ommited if the HTTPS default port 443 has been configured for MailStore Web Access or as source port of a port-forwarding on the firewall or router.
MailStore SPE	archive.example.com	443	`https://archive.example.com/<instanceid>/oidc/signin` The instanceid of the instance is part of the Redirect URI.

Important Notice: Please note that the redirect URI is case-sensitive. Also review the requirements on resolving URIs in the Prerequisites, Recommendations and Limitations section.

Configuring the Redirect URI in MailStore Server

For MailStore Server to convey the redirect URI to requesting clients, it must be configured there, too.

Switch to the Directory Services page in the MailStore Client.
Enter the redirect URI in the corresponding field in the Authentication section. Just copy the value previously configured in Microsoft Entra ID from the web browser.

Configuring API Permissions in Microsoft Entra ID

Switch again to Microsoft Entra ID in your web browser.
Select API permissions in the Manage section of the left navigation menu.
Click on the Add a permission button in the Configured permissions section.
On the Request API permissions menu page, select the API Microsoft Graph in the Commonly used Microsoft APIs section.
Select the option Application permissions.
Enable the Directory > Directory.Read.All permission in the Select permissions section.
Click on Add permissions.
The permissions are updated and the Directory.Read.All permission appears in the API permissions list under Microsoft Graph.
Click on the Add a permission button in the Configured permissions section again.
On the Request API permissions menu page, select APIs my organization uses.
Search for Office 365 Exchange Online and click on the corresponding entry.
Select the option Application permissions.
Enable the full_access_as_app permission in the Select permissions section.
Click on Add permissions.
The permissions are updated and the full_access_as_app permission appears in the API permissions list under Exchange.
Now click on the Grant admin consent for <your tenant name> button in the Configured permissions section.
Acknowledge the following notice with Yes.
The status of all granted permissions is updated to Granted for <your tenant name>.

The configuration of MailStore Server's connection to Microsoft 365 within Microsoft Entra ID is now complete. You can sign out of your Microsoft Entra ID tenant and close the browser window. Switch to the Directory Services page in the MailStore Client again, all remaining configuration steps must be done there.

User Database Synchronization

After configuring the connection settings as described above, you can specify filter criteria for the Microsoft 365 synchronization in this section.

Synchronize licensed Microsoft Exchange Online users only
Only Microsoft 365 user accounts with a Microsoft Exchange Online license assigned to them will be taken into account by the synchronization.
Synchronize enabled users only
Only Microsoft 365 user accounts that do not have their login to Microsoft 365 blocked will be taken into account by the synchronization.
Sync only these groups
Choose one or several Microsoft 365 security groups if you only want their members to be created as MailStore Server users. That way it's possible to exclude certain users from being synchronized to MailStore Server.

Options

Automatically delete users in MailStore Server
Here you can choose whether users that have been deleted in the Microsoft 365 tenant will also be deleted in the MailStore Server user database by the synchronization. Users will also be deleted if they fall out of scope of the configured settings.
Only MailStore Server users that have their authentication method set to Directory Services will be deleted.
If the archive folder of such a user already contains archived emails, only the user entry but not its archive folder will be deleted in MailStore Server.

Assigning Default Privileges

By default, users that have been synchronized to MailStore Server from Microsoft 365 have the privilege to log on to MailStore Server as well as read access to their own user archive.
You can configure those default privileges before synchronization, for example, to assign the privilege Archive E-mail to all new users. To do this, click on Default Privileges...
More information on managing user privileges and their effects is available in the chapter Users, Folders and Settings which also has details on editing existing privileges.

Running Directory Services Synchronization

Click on Test Settings to check synchronization configuration and the results returned by the Microsoft 365 tenant without any changes to the MailStore Server user database being actually committed.

To finally run the synchronization, click on Synchronize now. The results are shown with any changes committed to the MailStore Server user database.

You can test the authentication for a user by first selecting him from the list and then clicking on the button on the lower left. You will now be asked for that user's password. Upon clicking OK you'll receive a message whether the authentication has been successful.

Updating credentials

The certificate generated by MailStore for logging into Microsoft Entra ID is valid for 825 days. In order for user synchronization and archiving to work afterwards, the certificate must be updated before its validity expires.

MailStore Server will show a notification on the dashboard in MailStore Client and in the status report 28 days before credentials expire. You can also use the GetCredentials API command to retrieve the expiration date.

To update the credentials, proceed as follows:

Updating credentials in MailStore Server

Log on to MailStore Client as a MailStore Server administrator.
Click on Administrative Tools > Users and Archives > Directory Services.
In the Integration section, make sure that the directory service type is set to Microsoft 365 (Modern Authentication) or Microsoft 365 operated by 21 Vianet (Modern Authentication).

In the Connection section, click on the button (…) next to the Credentials drop-down list.
In the Credential Manager that appears, click on the currently used credential object and click Edit…

In the Authentication section, click on the drop-down button next to the Certificate text box und select Create Certificate....
Confirm the process.
In the Authentication section, click on the drop-down button next to the Certificate text box und select Download Certificate. Save the certificate on your hard drive.
Confirm your changes by clicking OK.
Leave the Credential Manager by clicking Apply.
The newly created credentials are selected in the corresponding drop-down list by default.

Updating credentials in Microsoft Entra ID

Sign in to the Microsoft Entra ID Portal as a Global Administrator for your Microsoft 365 tenant.
The Microsoft Entra ID Portal of Office 365, operated by 21Vianet can be accessed here.
In the navigation menu (☰), select the option Microsoft Entra ID.
On the next page, select App registrations in the Manage section of the left navigation menu.
Select the application that is currently used by MailStore.
Select Certificates & secrets in the Manage section of the left navigation menu.
Click on Upload certificate in the Certificates section. Select the certificate file that you have saved previously and upload it to Microsoft Entra ID by clicking Add.
If uploading has been successful, the certificate's thumbprint as well as its start and expiry dates appear in the certificates list. You can compare the thumbprint and expiry date with those listed in the MailStore Credential Manager to check that you've uploaded the correct certificate.
The previously used certificate can be removed from the list.