View source for Synchronizing User Accounts with Microsoft 365 (Basic Authentication)

{{DISPLAYTITLE:Synchronizing User Accounts with Microsoft 365 (Basic Authentication)}}
<p class=msnote><span style="color:red">'''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.'''</span><br/><br/>
On September 20th, 2019 [https://developer.microsoft.com/en-us/office/blogs/end-of-support-for-basic-authentication-access-to-exchange-online-apis-for-office-365-customers/ 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.
<br/>
<br/>
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)]].</p>
{{Directory Services Preamble|Office 365 tenant|Office 365}}

<p class=msnote>'''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 [https://technet.microsoft.com/en-us/library/exchange-online-service-description.aspx TechNet article].</p>

== 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''.

[https://docs.microsoft.com/en-us/powershell/scripting/wmf/setup/install-configure?view=powershell-5.1 Windows Management Framework]<br/>
[https://docs.microsoft.com/en-us/office365/enterprise/powershell/connect-to-office-365-powershell 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.
#; <br/>
# The command to connect to the Office 365 Azure AD tenant depends on its Azure Cloud:
#; <br/>
#; ''Global Azure Cloud''
#; In case your Office 365 Azure AD tenant resides in the global Azure Cloud enter the following command:
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">Connect-MsolService -AzureEnvironment AzureCloud</source>
#; <br/>
#; ''Azure Germany Cloud''
#; In case your Office 365 Azure AD tenant resides in the Azure Germany Cloud enter the following command:
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">Connect-MsolService -AzureEnvironment AzureGermanyCloud</source>
#; <br/>
#; ''Azure China Cloud''
#; In case your Office 365 Azure AD tenant resides in the Azure China Cloud enter the following command:
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">Connect-MsolService -AzureEnvironment AzureChinaCloud</source>
#; <br/>
# A login dialog opens. Enter admin credentials of your Office 365 plan.
#;<br/>
# Create a new service principal and store its value in the ''$principal'' variable by entering
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">$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)</source>
#;<br/>
#;<p class="msnote">'''Please note:''' The service principal's password is valid for one year from its creation date by default. Additional information can be found [https://docs.microsoft.com/en-us/powershell/module/msonline/new-msolserviceprincipal on MSDN].</p>
# For the service principal to be able to read information from the Azure AD tenant, assign the ''Directory Readers'' role by entering
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">Add-MsolRoleMember -RoleName "Directory Readers" -RoleMemberType ServicePrincipal -RoleMemberObjectId $principal.ObjectId</source>
#;<br/>
# ''Optional:'' To get a list of all ServicePrincipalCredential objects (e.g. passwords) that are bound to ServicePrincipals that contain ''MailStore'', enter:
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">Get-MsolServicePrincipal -SearchString "MailStore" | % { Write-Host "DisplayName:" $_.DisplayName;Write-Host "ServicePrincipalNames:" $_.ServicePrincipalNames;Write-Host "ObjectId:" $_.ObjectId;Get-MsolServicePrincipalCredential -ObjectId $_.ObjectId -ReturnKeyValues $true }</source>

== Accessing Directory Service Integration ==
{{Directory Services Accessing Configuration|Office 365|office365_sync_01.png}}

== Connecting to Office 365 ==
For synchronization MailStore Server requires information on how to connect to Office 365.
*'''Service Principal'''<br/>The ''service principal name'' of the service principal (e.g. ''MailStoreSP'').
*'''Password'''<br/>The ''password'' of the service principal.
*'''Domain Name'''<br/>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'''<br/>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'''<br/>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'''<br/>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'''<br/>Choose which naming scheme MailStore user names should follow:
** ''User Principal Name (UPN)''<br/>The full Office 365 login name e.g. ''jane.doe@office365.example.com''
** ''User Principal Name (UPN) Local Part''<br/>The Office 365 login name without domain, e.g. ''jane.doe''
{{Directory Services Options|Office 365 tenant}}
{{Directory Services Assign Default Privileges|Office 365}}
{{Directory Services Run Synchronization|Office 365 tenant}}
[[File:Office365_sync_02.png|450px|center]]


{{Directory Services Test Authentication}}
{{Directory Services Login with Directory Services Credentials|Office 365}}
[[de:Office_365-Integration]]
[[en:Office_365_Integration]]