Synchronising functional accounts from Exchange (via PowerShell)

Introduction

This document explains how to synchronise functional accounts from Microsoft Exchange on-premise or Exchange Online to Zivver using the Zivver SyncTool.

It is not recommended to create personal accounts in Zivver for email addresses that are used as shared mailbox. If an email address is shared, make it a functional account in Zivver.

If you want to use Single Sign On (SSO) for your organisation, make sure you’ve configured SSO before synchronising accounts with the SyncTool.

Currently, there are three ways to synchronise functional accounts to Zivver with the SyncTool:

  1. From Exchange on-premise or Exchange Online.
    Explained in this article.
  2. From Active Directory.
    Explained in Synchronising functional accounts from Active Directory.
  3. From an Excel file.
    Explained in Synchronising functional accounts from an Excel file.

This manual assumes installation of the SyncTool and configuration of the first two tabs is completed.

Technical requirements

The machine on which the SyncTool will be installed must meet the following technical requirements:

  • The machine has Microsoft .NET 4.7.2 or higher installed.
  • The SyncTool can make a HTTPS connection (TLS v1.2) on the machine via port 443.

See the sections below for additional requirements based on your organization’s Exchange server type.

Exchange Online additional requirements

Exchange on-premise additional requirements

  • The machine is allowed to make a remote PowerShell connection to the Exchange on-premise server.

  • An Exchange account is available which has at least the following rights:

    • Distribution Groups.
    • View Only Configuration.
    • View Only Recipients.
  • For shared mailboxes to be synchronised each shared mailbox need to have an email address and delegates with FullAccess permission.

  • If FullAccess rights to shared mailboxes are assigned to Active Directory Security Groups, then

    • The Exchange server needs to have Microsoft’s Remote Server Administration Tools installed. Specifically, you’ll need the Active Directory Domain Services (AD DS) and AD Lightweight Directory Services (LDS) tools installed.
    • The Exchange server needs to have the Active Directory PowerShell module installed.

Using Exchange to synchronise functional accounts to Zivver

This section explains how to synchronise functional accounts to Zivver from Exchange on-premise or Exchange Online.

In this manual Exchange on-premise or Exchange Online is the source for the synchronisation. The synchronisation is executed in one direction: from the source to Zivver, not the other way around. You can determine which accounts are synchronised from the source to Zivver with filters.

SyncTool tab | Step 3: Set up local users/group settings

In Source to use to sync users with Zivver select Exchange (via Powershell) from the dropdown menu.

Exchange type
Choose the Exchange type you want to use as a source to synchronise functional accounts to Zivver.

Set up a connection to Exchange Online manually

SyncTool tab | Step 3: Set up local users/group settings

Exchange type
Select Office 365 - MFA.

Admin user name
Fill in the username for the account that can be used to log into Exchange Online. The account must meet the criteria in the technical requirements. The username for Exchange Online is always an email address.

Set up a connection to Exchange Online automictically with certificate

Version 2.0.3 of the PowerShell module ExchangeOnlineManagement is required. Additionally, make sure app-only authentication for unattended scripts is already configured before attempting to connect.

SyncTool tab | Step 3: Set up local users/group settings

Exchange type
Select Office 365 - Certificate.

Certificate location
Fill in the location of the .pfx file created at step 3: Generate a self-signed certificate including the name. For example C:\mycert.pfx.

The path from which you run the second PowerShell cmdlet from the Microsoft documentation is where the .pfx file is stored. For example if you run the PowerShell cmdlet from C:\Windows\System32, then the file location will be C:\Windows\System32\mycert.pfx

Certificate password
Fill in the password that you used to secure the .pfx file at step 3: Generate a self-signed certificate. Make sure the password is at least 12 characters long and store the password somewhere safe.

Application ID
Fill in the application ID of the App registration created at step 1: Application registration in Azure AD.

  1. Go to portal.azure.com.
  2. Select Azure Active Directory.
  3. Select the tab App registrations.
  4. Select the App registration created for the SyncTool from the list.
  5. Copy the Application (client) ID.

O365 Organization
Fill in the primary domain of you Azure AD tenant. It usually looks like yourcompany.onmicrosoft.com.

  1. Go to portal.azure.com.
  2. Select Azure Active Directory.
  3. Select the tab Overview.
  4. Look for the Primary domain on the tenant information tile.

OU to filter on
Optional: You can fill in the Exchange Online OU (not AD OU) to filter on specific units. In most use cases an OU to filter on is not necessary. You can also filter on mailbox types in the next section.

Set up a connection to Exchange on-premise

SyncTool tab | Step 3: Set up local users/group settings

Exchange type
Select Exchange on premise.

Exchange address
Fill in the Exchange address. The SyncTool will use this address to set up a remote connection.

The address should look like http://"ServerFQDN"/PowerShell/. Replace “ServerFQDN”” with the fully qualified domain name of your Exchange server (for example, exchange01.example.com).

Use Kerberos
Select Yes. Using Kerberos is the default way to authenticate for Exchange on-premise.

Admin user Name
Fill in the username for the account that can be used to log into Exchange. The username often is preceded by the domain - for example company\name_exchange_account.

The account must meet the criteria in the technical requirements.

Password
Enter the password for the Exchange on-premise account.

OU to filter on
Optional: You can fill in the Exchange on-premise (not AD OU) to filter on specific units. In most use cases an OU to filter on is not necessary. You can also filter on mailbox types in the next section.

Select shared mailbox types to include

SyncTool tab | Step 3: Set up local users/group settings

At the central column under Shared mailbox types to include you can select the shared mailbox types you want to include in your synchronisation. All shared mailbox types are selected by default.

  1. Review which shared mailbox types in your Exchange you want to include in the synchronisation.
    After this step you should know which shared mailbox types in Exchange you want a create functional account in Zivver for.
  2. Check the matching boxes for each shared mailbox type in the SyncTool.
    This will create a functional account for each shared mailbox type included.
  3. Uncheck the shared mailbox types you do not want to include in the synchronisation.
    This will prevent functional accounts from being created for unchecked shared mailbox types.
At least one shared mailbox type should be checked.

Assign Zivver OU

  1. If your organization uses OU’s in Zivver, then check the box at Assign Zivver OU. If your organization does not use OU’s in Zivver, you can ignore this section.

    If your organization uses Organizational Units in Zivver, you have access to the Organization Units tab in Zivver. If you don’t have access, your organization doesn’t use Organizational Units in Zivver, or you don’t have administrator rights.
  2. Select the Organization Unit Setup:

    1. If your organization populates Organizational Units in Zivver based on their email domain, then choose Domain name.
    2. If your organization populates Organization Units in Zivver based on a custom OU Identifier, then Choose Custom OU.

    You can check the Organizational Unit Identifier by browsing to the Organization Units tab in Zivver, clicking on one of the OU’s present and edit edit the Organizational Unit. You will see the identifier in a popup under Organization Unit Identifier.

Filtering options

SyncTool tab | Step 3: Set up local users/group settings

These filtering options are optional. Currently you can only filter on the email address of shared mailboxes.

  1. Check Apply filter on users/groups.
  2. Enter the filter value(s) at Filter values.

    Use space, enter, semicolon or OR as OR-operator (i.e. match any of the list). Use AND with or without () to match all in the list.
  3. Choose between including or excluding results from your filter in the results.
    You can’t include and exclude in the same filter.

Read the next section Preview resources how to get the results based on your filtering options.

Preview resources

SyncTool tab | Step 3: Set up local users/group settings

If you click the button Preview resources, then the SyncTool will create a preview of what can be synchronised by connecting to your exchange and applying the previously configured filters on shared mailbox types and/or email addresses.

Previewing resources may take a couple of minutes or more since the SyncTool will run a PowerShell script in the background. If there are no error messages shown within one minute after clicking Preview resources, then let the SyncTool run untill it shows the results. To verify that the SyncTool process is still running, check that Windows Task Manager shows it is using CPU and memory.

If any error messages appear please read the message carefully to troubleshoot the message and close the SyncTool before retrying. Most common error messages are explained in Common error messages after previewing resources.

Synchronise users and groups

This section explains how to run the synchronisation after the SyncTool is configured.

SyncTool tab | Step 4: Synchronise users/groups

  1. Select the tab Step 4: Synchronise users/groups.
    A Get changes? pop-up will appear.
  2. Click YES.
    A Progress… pop-up will appear while the SyncTool loads the results from the source and compares the results to the current Zivver accounts.

    This process may take a couple of minutes or more since the SyncTool will run a PowerShell script in the background. If there are no error messages shown within one minute after clicking YES, then let the SyncTool run untill it shows the results. To verify that the SyncTool process is still running, check that Windows Task Manager shows it is using CPU and memory.
  3. Check the box [X] groups that are new or changed in local data to sync with Zivver under Functional/group account sync options.
    This will create new functional accounts and update information of functional accounts in future synchronisations.

    Do not check the box Groups that are missing in local data and should be removed from Zivver under Delete options for users and groups.

This could result in deletion of a functional account if a change is made to the source. All Zivver messages will be lost with the deletion of a functional account.

  1. Leave the other boxes unchecked.
    You are now ready to synchronise Zivver accounts.
  2. Click Run synchronisations.
    A Confirm actions pop-up appears with a summary of what is about to be synchronised.
  3. Click Yes.
    A Get changes pop-up will appear.
  4. Click Yes.
    A summary of the mutations will appear.
  5. Click OK.
    A Save As pop-up will appear. After saving the file the SyncTool will notify you if the export was successful.
  6. Click OK. The synchronisation is complete.

How to automate the SyncTool synchronisation using the Windows Task Scheduler

Common error messages after previewing resources

System.Exception: [outlook.office365.com] Connecting to remote server outlook.office365.com failed with the following error message: The WinRM-client received HTTP-statuscode403 from the external service WS-management.

Cause: The admin account entered at Step 3: Set up local users/group settings does not have permission to connect to Exchange Online using remote PowerShell.

Solution: Give the administrator the permissions to do so, or enter different administrator credentials that have permission to connect to Exchange using remote PowerShell.

System.Management.Automation.Runspaces.PSSnapInException: Cannot load Windows PowerShell snap-in Microsoft.PowerShell.Diagnostics because of the following error: Could not load file or assembly ‘Microsoft.PowerShell.Commands’ or one of its dependencies. The system cannot find the file specified.

Cause: The machine running the SyncTool has a PowerShell version installed lower than version 3.

Solution: Update PowerShell to version 3 or higher. You can check which version is currently installed by opening PowerShell and running the $PSVersionTable.PSVersion. The column Major displays your current PowerShell version. If this command does not work, you are using PowerShell version 1.

Error UpdateAll 1: System.Net.Http.HttpRequestException: An error occurred while sending the request. —> System.Net.WebException: Unable to connect to the remote server.

Cause: The SyncTool is probably blocked by your Firewall.

Solution: Make sure the SyncTool can make a HTTPS connection (TLS v1.2) on the server via port 443 to https://*.zivver.com.

The WINRM client received an HTTP bad request status (400)

Cause: You are using https:// instead of http:// in the Exchange address.

Solution: Use the default connection URI for remote access to your Exchange on-premise server: http://"ServerFQDN/PowerShell/ in combination with Kerberos authentication. Or try https://"ServerFQDN"/PowerShell/ without Kerberos authentication.

Still having trouble?

For the synchronisation to work, the SyncTool needs to set up a remote PowerShell session with your Exchange. If you are having trouble with connecting the SyncTool to your Exchange, please verify you can set up a connection using PowerShell instead of the SyncTool from the machine running the SyncTool. This might help you troubleshoot the problem. The Microsoft articles listed below show you the steps to set up a remote PowerShell session to your Exchange or Exchange online.

Was this article helpful?

thumb_up thumb_down