Difference between revisions of "Synchronizing User Accounts with Microsoft 365 - Modern Authentication"

[checked revision][checked revision]
Line 64: Line 64:
! style="width:80px;" | Product
! style="width:80px;" | Product
! style="width:80px;" | FQDN
! style="width:80px;" | FQDN
! style="width:40px;" | TCP Port
! style="width:40px;" | Port
! Resulting Redirect URI
! Resulting Redirect URI

Revision as of 07:14, 3 September 2021

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 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 synchronizing user accounts with Microsoft 365 (Modern Authentication) only with the global Microsoft Cloud. National clouds such as Microsoft Cloud for US Government, Microsoft Cloud Germany (operated by T-Systems) and Azure and Microsoft 365 operated by 21Vianet in China are not supported. For synchronizing users with Office 365 Germany and Office 365 operated by 21Vianet, please refer to the corresponding manual chapter.

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 Azure Active Directory as directory service. Each Microsoft 365 tenant corresponds to an Azure AD tenant that stores its user information.

Registering of MailStore Server as App in Azure AD

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

  • Sign in to the Azure Portal as a Global Administrator for your Microsoft 365 tenant.
  • In the navigation menu (☰), select the option Azure Active Directory.
  • 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 Azure AD 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 Azure AD. Microsoft recommends using certificates as secrets to identify apps in Azure AD. 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).
Microsoft 365 sync 01.png
  • 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 Azure AD 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 Azure AD app overview page in your web browser.
    • Directory (tenant) ID
      The value of the corresponding field that you can copy from the Azure AD app overview page in your web browser.
Microsoft 365 cred 01.png
  • 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 Azure AD

For Azure AD to validate the identity of MailStore Server, the created certificate needs to be published in Azure AD.

  • Switch to the Azure AD 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 Azure AD 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 Azure AD

For Azure AD 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 Azure AD.

  • In the Azure 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.
  • In the field Redirect URI, enter a URI in the format (without brackets)
    with the following components:
    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.
    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.
    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).
    The endpoint where MailStore Server expects the authentication responses of Azure AD. This path has to be specified exactly as stated here at the end of the redirect URI.
  • Leave the field Logout URL blank.
  • Enable the ID tokens option in the Implicit grant section.
  • Click on Configure to finish the configuration of the app authentication in Azure AD.
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 Azure AD from the web browser.
Microsoft 365 sync 02.png

Configuring API Permissions in Azure AD

  • Switch again to Azure AD 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 Azure AD is now complete. You can sign out of your Azure AD 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.


  • 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.

Office365 sync 02.png

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.