Synchronizing User Accounts with Microsoft 365 (Basic Authentication)

A checked version of this page, approved on 15 July 2020, was based on this revision.

Information in this document is no longer maintained and may no longer be up-to-date. Furthermore, we reserve the right remove this feature in a future MailStore Server version.

On September 20th, 2019 Microsoft announced the end of support for Basic Authentication for Exchange Online APIs in the future. This affects any MailStore Server version prior to 13, which will therefore no longer be able to authenticate users against Microsoft 365 when trying to log into MailStore Server.

In MailStore Server 13, support for modern authentication methods via OAuth 2.0 & OpenID Connect as per Microsoft's recommendation was introduced. Therefore, please refer to the chapter 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 Office 365 tenant of your organization.

During synchronization, user information, such as user names and email addresses, is copied from the Office 365 tenant into MailStore Server's user database. That way, users can use their Office 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 Office 365 tenant itself by MailStore Server. The scope of the synchronization can be limited through filters.

Important notice: User authentication against Office 365 requires the Exchange Online feature EWS Application support for the plan of the user that wants to authenticate. Please make sure that your Office 365 plan supports this feature. More information is available in this TechNet article.

Preparing the Office 365 tenant

In order to synchronize user account information from Office 365, MailStore Server requires a service principal which has been granted permission to access the Office 365 tenant. The service principal represents MailStore Server in the Office 365 tenant and makes it possible to authenticate to the tenant's services and use their resources.

Installing the Azure Active Directory Module

Office 365 relies on Azure Active Directory as directory service. Each Office 365 tenant corresponds to an Azure AD tenant where its user information is being stored. In order to create a service principal, the necessary PowerShell module Microsoft Azure Active Directory Module for Windows PowerShell has to be installed first.

This module requires PowerShell 5.1 or higher on a 64-bit operating system to work correctly. PowerShell 5.1 is part of current builds of Windows 10 and Windows Server 2016. For other Windows versions, you have to install it as part of the Windows Management Framework.

These prerequisites as well as instructions on how to install them are available directly from Microsoft.

Follow the instructions with the cmdlets that include Msol and NOT those that include AzureAD.

Windows Management Framework
Connect to Office 365 PowerShell

Creating a service principal

Once the PowerShell module has been installed, a service principal can be created in the Azure AD by following these steps:

Open a PowerShell Session.
The command to connect to the Office 365 Azure AD tenant depends on its Azure Cloud:
Global Azure Cloud

In case your Office 365 Azure AD tenant resides in the global Azure Cloud enter the following command
```
Connect-MsolService -AzureEnvironment AzureCloud
```
Azure Germany Cloud

In case your Office 365 Azure AD tenant resides in the Azure Germany Cloud enter the following command
```
Connect-MsolService -AzureEnvironment AzureGermanyCloud
```
Azure China Cloud

In case your Office 365 Azure AD tenant resides in the Azure China Cloud enter the following command
```
Connect-MsolService -AzureEnvironment AzureChinaCloud
```
A login dialog opens. Enter admin credentials of your Office 365 plan.

Create a new service principal and store its value in the $principal variable by entering

$principal = New-MsolServicePrincipal -DisplayName 'MailStoreSP' -ServicePrincipalNames @("MailStoreSP") -Type Password -Value 'use_a_password_of_your_choice_here' -StartDate (Get-Date) -EndDate (Get-Date).AddYears(1)

Please note: The service principal's password is valid for one year from its creation date by default. Additional information can be found on MSDN.

For the service principal to be able to read information from the Azure AD tenant, assign the Directory Readers role by entering

Add-MsolRoleMember -RoleName "Directory Readers" -RoleMemberType ServicePrincipal -RoleMemberObjectId $principal.ObjectId

Optional: To get a list of all ServicePrincipalCredential objects (e.g. passwords) that are bound to ServicePrincipals that contain MailStore, enter:

Get-MsolServicePrincipal -SearchString "MailStore" | % { Write-Host "DisplayName:" $_.DisplayName;Write-Host "ServicePrincipalNames:" $_.ServicePrincipalNames;Write-Host "ObjectId:" $_.ObjectId;Get-MsolServicePrincipalCredential -ObjectId $_.ObjectId -ReturnKeyValues $true }

Accessing Directory Service Integration

Log on to MailStore Client as a MailStore Server administrator.
Click on Administrative Tools > Users and Archives > Directory Services.
The directory service type depends on the Azure Cloud of your Office 365 Azure AD tenant:

Globale Azure Cloud

If your Office 365 Azure AD tenant resides in the global Azure Cloud, chose the directory service type Office 365.

Azure Germany Cloud

If your Office 365 Azure AD tenant resides in the Azure Germany Cloud, chose the directory service type Office 365 Germany.

Azure China Cloud

If your Office 365 Azure AD tenant resides in the Azure China Cloud, chose the directory service type Office 365 operated by 21 Vianet.

Connecting to Office 365

For synchronization MailStore Server requires information on how to connect to Office 365.

Service Principal
The service principal name of the service principal (e.g. MailStoreSP).
Password
The password of the service principal.
Domain Name
An email domain in the Office 365 tenant.

User Database Synchronization

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

Synchronize licensed Microsoft Exchange Online users only
Only Office 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 Office 365 user accounts that do not have their login to Office 365 blocked will be taken into account by the synchronization.
Sync only these groups
Choose one or several Office 365 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.
User Name Format
Choose which naming scheme MailStore user names should follow:
- User Principal Name (UPN)
  The full Office 365 login name e.g. [email protected]
- User Principal Name (UPN) Local Part
  The Office 365 login name without domain, e.g. jane.doe

Options

Automatically delete users in MailStore Server
Here you can choose whether users that have been deleted in the Office 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 Office 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 Office 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.

Login with Office 365 Credentials

After synchronization MailStore users can log on to MailStore Server with their Office 365 username and Office 365 password.