Difference between revisions of "Office 365 Integration"

Jump to: navigation, search
[unchecked revision][checked revision]
m
(Creating a service principal)
(26 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{DISPLAYTITLE:Synchronizing User Accounts with Office 365}}
 
{{DISPLAYTITLE:Synchronizing User Accounts with Office 365}}
{{Draft}}
 
 
{{Directory Services Preamble|Office 365 tenant}}
 
{{Directory Services Preamble|Office 365 tenant}}
 
== Preparing the Office 365 tenant ==
 
== Preparing the Office 365 tenant ==
Line 6: Line 5:
  
 
=== Installing the Azure Active Directory Module ===
 
=== 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 of is being stored. In order to create a service principal, the necessary PowerShell cmdlets have to be installed first as described in this article:
+
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.
  
[https://support.office.com/en-us/article/Windows-PowerShell-cmdlets-for-Office-365-06a743bb-ceb6-49a9-a61d-db4ffdf54fa6 Windows PowerShell cmdlets for Office 365 management and deployment on Office.com]
+
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/wmf/5.1/install-configure Windows Management Framework 5.1]<br/>
 +
[https://docs.microsoft.com/en-us/office365/enterprise/powershell/connect-to-office-365-powershell Connect to Office 365 PowerShell]
  
 
=== Creating a service principal  ===
 
=== 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:
 
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 and enter the following command to connect to the Office 365 Azure AD tenant:
+
# Open a PowerShell Session.
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">Connect-MsolService</source>
+
# 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.
 
# A login dialog opens. Enter admin credentials of your Office 365 plan.
 
#;<br/>
 
#;<br/>
 
# ''Optional:'' To get a list of all service principals that currently exist in the AD tenant, enter
 
# ''Optional:'' To get a list of all service principals that currently exist in the AD tenant, enter
 
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">Get-MsolServicePrincipal</source>
 
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">Get-MsolServicePrincipal</source>
 +
#;<br/>
 
# Create a new service principal by entering
 
# Create a new service principal by entering
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">New-MsolServicePrincipal -DisplayName "MailStoreSP" -ServicePrincipalNames "MailStoreSP/<tenant domain>" -Type Password -Value "<Password>"</source>
+
#; <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'</source>
# A <code>service principal object</code> is returned. Its ''ObjectId'' is needed for role assignment in the next step. The service principal is valid for one year from its creation date by default. Additional information can be found [http://msdn.microsoft.com/en-us/library/azure/dn194119.aspx on MSDN].
 
 
#;<br/>
 
#;<br/>
 +
# The <code>service principal object</code> was created and is stored in the ''$principal'' variable. Its ''ObjectId'' is needed for role assignment in the next step.
 +
#;<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
 
# 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 "<Service Principal's ObjectId>"</source>
+
#; <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false">Add-MsolRoleMember -RoleName "Directory Readers" -RoleMemberType ServicePrincipal -RoleMemberObjectId $principal.ObjectId</source>
  
== Accessing Directoy Service Integration ==
+
== Accessing Directory Service Integration ==
 
{{Directory Services Accessing Configuration|Office 365|office365_sync_01.png}}
 
{{Directory Services Accessing Configuration|Office 365|office365_sync_01.png}}
  
 
== Connecting to Office 365 ==
 
== Connecting to Office 365 ==
 
For synchronization MailStore Server requires information on how to connect 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/<tenant domain>'').
+
*'''Service Principal'''<br/>The ''service principal name'' of the service principal (e.g. ''MailStoreSP'').
 
*'''Password'''<br/>The ''password'' of the service principal.
 
*'''Password'''<br/>The ''password'' of the service principal.
 
*'''Domain Name'''<br/>An email domain in the Office 365 tenant.
 
*'''Domain Name'''<br/>An email domain in the Office 365 tenant.
Line 37: Line 56:
 
=== User Database Synchronization ===
 
=== User Database Synchronization ===
 
After configuring the connection settings as described above, you can specify filter criteria for the Office 365 synchronization in this section.
 
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.
 
*'''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 Options|Office 365 tenant}}
 
{{Directory Services Assign Default Privileges|Office 365}}
 
{{Directory Services Assign Default Privileges|Office 365}}
 
{{Directory Services Run Synchronization|Office 365 tenant}}
 
{{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]]
 
[[de:Office_365-Integration]]
 
[[en:Office_365_Integration]]
 
[[en:Office_365_Integration]]

Revision as of 10:44, 29 April 2019

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

During synchronization user information such as user names and email addresses are read from the Office 365 tenant and recorded in MailStore Server's user database. No changes are made to the Office 365 tenant itself by MailStore Server. The scope of the synchronization can be limited through filters.

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 5.1
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:

  1. Open a PowerShell Session.
  2. 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
    

  3. A login dialog opens. Enter admin credentials of your Office 365 plan.

  4. Optional: To get a list of all service principals that currently exist in the AD tenant, enter
    Get-MsolServicePrincipal
    

  5. Create a new service principal by entering
    $principal = New-MsolServicePrincipal -DisplayName 'MailStoreSP' -ServicePrincipalNames @("MailStoreSP") -Type Password -Value 'use_a_password_of_your_choice_here'
    

  6. The service principal object was created and is stored in the $principal variable. Its ObjectId is needed for role assignment in the next step.

    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.

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

Accessing Directory Service Integration

  • Log on to MailStore Client as a MailStore Server administrator.
  • Click on Administrative Tools > Users and Privileges and then on 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.
Office365 sync 01.png


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. jane.doe@office365.example.com
    • 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 user database by the synchronization. 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. Additionally, only MailStore users that have their authentication method set to Directory Services will be deleted.

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.

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.

Login with Office 365 Credentials

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

Navigation
Tools
Print/export
About MailStore

  • MailStore Server is one of the leading email archiving solutions for SMB.
  • For private use there is a free tool for email archiving furthermore: MailStore Home.