During synchronization user information such as user names and email addresses are read from the Office 365 tenant and recorded in Visible-Archive's user database. No changes are made to the Office 365 tenant itself by Visible-Archive. 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, Visible-Archvie requires a service principal which has been granted permission to access the Office 365 tenant. The service principal represents Visible-Archive 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.
Creating a service principal
1. Open a PowerShell Session.
2. The command to connect to the Office 365 Azure AD tenant depends on its Azure Cloud:
Install-Module MSOnline Connect-MsolService -AzureEnvironment AzureCloud
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
5. Create a new service principal by entering
$principal = New-MsolServicePrincipal -DisplayName 'Visible-ArchiveSP' -ServicePrincipalNames @("Visible-ArchiveSP") -Type Password -Value 'use_a_difficult_of_your_choice_here' -StartDate 'use_todays_date' -EndDate 12/31/2099
The service principal object was created and is stored in the $principal variable. Its ObjectId is needed for role assignment in the next step. The service principal's password is valid for one year from its creation date by default. Additional information can be found on MSDN.
6. 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 E-Mail Archive Client as an Archive 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:
Connecting to Office 365
For synchronization Visible-Archive requires information on how to connect to Office 365.
- Service Principal: The service principal name of the service principal (e.g. Visible-ArchiveSP).
- 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 Visible-Archive users. That way it's possible to exclude certain users from being synchronized to Visible-Archive.
User Name Format: Choose which naming scheme Visible-Archive user names should follow:
- User Principal Name (UPN)The full Office 365 login name e.g. firstname.lastname@example.org
- User Principal Name (UPN) Local PartThe Office 365 login name without domain, e.g. jane.doe
- Automatically delete users in Visible-Archive
Here you can choose whether users that have been deleted in the Office 365 tenant will also be deleted in the Visible-Archive 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 Visible-Archive. Additionally, only Visible-Archive users that have their authentication method set to Directory Services will be deleted.
Assigning Default Privileges
By default, users that have been synchronized to Visible-Archive from Office 365 have the privilege to log on to Visible-Archive 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...
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 Visible-Archive user database being actually committed.
To finally run the synchronization, click on Synchronize now. The results are shown with any changes committed to the Visible-Archive user database.