Synchronising functional accounts from Active Directory in V1

From 1 July 2023, the Zivver Synctool V1 is out of support. Consider to upgrade.

Introduction

This document explains how to synchronise functional accounts from Microsoft Active Directory (AD) to Zivver using the Zivver Synctool. You can use this manual to synchronise functional accounts to Zivver if your organisations’ functional accounts are (suspended) users in AD.

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.

Three kinds of data sources can be used to synchronise functional accounts to Zivver with the Synctool:

  1. From Exchange on-premise or Office 365.
    Explained in Synchronising functional accounts from Exchange (via PowerShell).
  2. From Active Directory.
    Explained in this article.

    A single profile can be used to synchronise both personal accounts and functional accounts when functional accounts are Security Groups (SG) or Distribution Groups (DG) in AD with an email address. In this scenario the Synctool will automatically detect the SG’s or DG’s and create functional accounts in Zivver.
    Read more
  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.
  • The Domain Controller (DC) must allow incoming traffic (via port 636) from the machine on which the Synctool is installed.
  • A service account (SA) is available which that meets the following requirements:
    • View-Only rights in AD.
    • Can make a LDAP connection to pull data from AD.
    • Can be used to run a basic task in the Windows Task Scheduler.
  • The shared mailboxes to be synchronised has an email address and has delegates with email addresses or groups with FullAccess permission.

Using AD to synchronise accounts to Zivver

This section explains how to synchronise functional accounts to Zivver from AD on-premise.

In this manual AD is the source for the synchronisation. The synchronisation is executed in one way: from the source to Zivver, not the other way around. You can determine which accounts are synchronised from the source to Zivver with filters.

Set up a connection to AD via LDAP

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

In Source to use to sync users with Zivver select LDAP (incl active directory) from the dropdown menu.

Host Name
This is the Host Name of the Domain Controller, for example ad.example.org. This is a mandatory field.

Port
This port will be used for a LDAP connection. Fill in 636 and check Use implicit TLS. This is a mandatory field.

Authorized user
Use the SA specified in the technical requirements. Usually this must be provided along with the domain name - for example company\name_service_account. This is a mandatory field.

Password
Enter the password for the SA. This is a mandatory field.

Base DN
Choose an OU that contains both the AD users used as functional accounts and AD users that are personal accounts. The Synctool will detect AD users in child OU’s. Fill in the distinguished name of the OU at Base DN in the Synctool. This is a mandatory field.

Whether a functional account is created in Zivver is determined by the source (i.e. the OU used as Base DN) in combination with Filtering options and Synchronisation options.

Not finding all functional accounts or delegates?

Consider choosing a Base DN high up in the AD domain such as DC=company,DC=org. If you are not sure about which OU to choose, please contact support.

LDAP query
Leave the LDAP query field blank. LDAP queries can not be used in this scenario.

Paging
Raise paging to a value more than 1.000 if there is a possibility that the result set will contain more than a 1.000 AD users.

Queries of AD without paging are limited to return a maximum of the first found 1.000 users. If you use paging in the Synctool, it can retrieve multiple sets of the amount configured and display it as one large set. Change the paging number if not all accounts are shown after the following steps. Gradually increase paging with steps of 1.000 if you are not getting all the users you would expect. You can increase the number up to 100.000.
Read more on paging in AD.

Test Connection.
Test the connection from the Synctool to AD with the Test Connection button next to Paging. This returns either a successful or refused connection.

A successful connection means the Synctool can connect to AD and is ready to fetch AD users.

A refused connection means the Synctool can’t connect to AD and can’t fetch AD users. The reasons for a refused connection could be:

  • The host name is incorrect.
  • The port entered is blocked by a firewall.
  • The authorised user does not have sufficient permissions.
  • The authorised user does or does not need the domain prior to the account name.
    Try company\name_service_account as well as name_service_account.
  • The password is entered incorrectly.
    Try entering the password again.

Map AD attributes to account properties

The connection has been established with the steps from the previous chapter. The Synctool can now fetch all AD attributes that have values, so that these AD attributes can be mapped to Zivver functional account properties such as email address and names.

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

In the central column at Server type click Microsoft AD from the dropdown menu and select Microsoft AD. This action will trigger the Synctool to fetch the AD attributes, it can take a few seconds to complete. The Synctool will automatically display a pop-up showing how many variables were found, and fill in the default variables in the central column after you close the pop-up.

Just below Server type check Select groups with their members. Any (suspended) AD users found by the Synctool will be created as functional account. Optionally select Groups in Groups if the members of a functional account are related to an AD user via a security group.

E-mail address of group

  • Default AD attribute: proxyAddresses

Functional accounts must have an email address. proxyAddresses is the default AD attribute that contains the email address of a user and its aliases. Only SMTP and smtp adresses will be synchronised to Zivver.

If one of the smtp-addresses under proxyAddresses has received a Zivver message before creating the alias via the Zivver Synctool, then the alias property will be ignored. In such cases, you should merge accounts before the next synchronisation. SMTP addresses that are not claimed in Zivver should be excluded from synchronisation to Zivver in the Zivver synctool. If you want to synchronise email aliases to Zivver for unclaimed domains, you should first claim the domain in Zivver.

If you do not want to synchronise aliases to Zivver, or your organization does not use aliases, then you can also use mail as an AD attribute. To do so, click the drop-down menu and select an alternate AD attribute.

Name of Group

  • Default AD attribute: name

The name of a functional account. This name will be displayed in a Zivver notification message, therefore it is suggested to select an attribute that contains a name that can be displayed to external recipients. Other commonly used attributes are displayName, userPrincipalName, givenName. Use these alternatives if name does not give you the name of a functional account.

Members

  • Default AD attribute: memberOf

It is recommended to change the memberOf to MsExchDelegateListlink by unchecking memberOf and checking MsExchDelegateListlink in the central column at Members. The property Members provide full access to Zivver inbox of a functional account. Full access delegations configured in Exchange are mapped automatically to the (suspended) user in AD to the AD attribute MsExchDelegateListLink.

Auto-mapping does not work as expected in Office 365 hybrid environments. This Microsoft article explains that auto-mapping to MsExchDelegateListLink does not work when your organization uses Active Directory on-premise together with Exchange Online (Office 365 Hybrid). The reason for this is personal Zivver accounts are created from AD on-premise and mailbox delegations are not synchronised from Exchange Online to AD on-premise. This means that MsExchDelegateListLink only contains the mailbox delegations from before the Office 365 Hybrid scenario, when you organization had an on-premise Exchange. Added or removed mailbox delegations in Exchange Online are not automatically mapped to AD on-premise and therefore cannot be used to map mailbox delegations to Zivver because they are not updated from Exchange Online to your on-premise AD. In such a situation, your organization cannot use Delegates in Zivver, unless there is another AD attribute that contains the common names of users that you wish to grant delegated access to.

You can select any other AD attribute to map delegations to, as long as it contains the AD common names of users you want to provide access to the delegated account. The delegates must have an active Zivver account in your Zivver organization, and the domain of the email addresses must be claimed by your organization in Zivver. If the delegate does not have an active Zivver account, is not a member of your Zivver organization or has an email address under a domain that your Zivver organization has not claimed in Zivver, then the Delegates property will be ignored.

If you are having trouble getting the correct results please visit the Zivver troubleshooting guide for functional accounts.

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.

How to check if your organization uses OU’s in Zivver

If your organization uses OU’s in Zivver, then you will see a tab called Organizational Units in your Organization settings. You can also try to visit the Organizational Units tab directly. If your organization does not use OU’s in Zivver, then you will see the following notification when clicking the link:

Sorry, the page you requested does not exist.

Filtering options

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

These filtering options are optional. You can include or exclude (suspended) AD users with the built-in filtering options. The built-in filtering options lets you filter on a value given in an AD attribute.

  1. Check Apply filter on users/groups.
  2. Choose an AD attribute from the dropdown table at Filter field.
  3. Enter the filter value(s) at Filter values.
    If you want to enter more than one filter value, add a line break between 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.
  4. Choose between including or excluding the results from your filter in the results.
    You can’t include and exclude in the same filter.

  5. Click Preview selected resources from Ldap to see the results.

Example: filter on OU

  1. Check Apply filter on users/groups.
  2. Choose distinguishedName from the dropdown table at Filter field.
  3. Enter the distinguishedName of the OU's separated by a line break at Filter values.
    For example if you have two OU’s to filter on:
    OU=Example,OU=Users,DC=company,DC=org
    OU=AnotherExample,Users,DC=company,DC=org
  4. Choose between including or excluding the results from your filter in the results.
    You can’t include and exclude in the same filter.
  5. Click Preview selected resources from Ldap to see the results.

Example: filter on SG

  1. Check Apply filter on users/groups.
  2. Choose MemberOf from the dropdown table at Filter field.
  3. Enter the commonName of the SG separated by a line break at Filter values.
    For example if you have two SG’s to filter on:
    Zivver-security-group1
    Zivver-security-group2
  4. Choose between including or excluding the results from your filter in the results.
    You can’t include and exclude in the same filter.
  5. Click Preview selected resources from Ldap to see the results.

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 AD on-premise and applying the previously configured filters to (suspended) users.

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.
  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.
  4. Leave the other boxes unchecked.
    You are now ready to synchronise Zivver accounts.

  5. Click Run synchronisations.
    A Confirm actions pop-up appears with a summary of what is about to be synchronised.

  6. Click Yes.
    A Get changes pop-up will appear.

  7. Click Yes.
    A summary of the mutations will appear.

  8. Click OK.
    A Save As pop-up will appear. After saving the file the Synctool will notify you if the export was successful.

  9. Click OK.
    The synchronisation is complete.

How to automate the Synctool synchronisation using the Windows Task Scheduler

Common error messages after synchronising

Error processing {Name} ({Email address}) with status code ‘Forbidden’. You are not allowed to add this address to your organization. Does the account belong to a registered domain name?

Cause: There are two possible causes.

  1. The account has an email address that does not belong to a claimed domain in Zivver.
    Claim a domain manual
  2. A Zivver account for this email address already exists, but it was created as a free account before your domain was claimed in Zivver.

Solution: The solution depends on whether or not you have claimed the domain in Zivver.

If have not claimed the domain in Zivver, go to domains and claim the domain. This allows the Synctool to create a Zivver account for that domain.

If you have claimed the domain, visit the troubleshooting guide for functional accounts.

Was this article helpful?

thumb_up thumb_down