×

Want to Search?

Go here

Switch Language

English

Contact Us

Get Help Give feedback

I am a Zivver admin

Configure and manage Zivver

Help Center >  Synchronising personal accounts from Active Directory in V1

Synchronising personal 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 you synchronise personal accounts from Microsoft Active Directory on-premise (AD) to Zivver using the Zivver Synctool. Personal accounts can be either user or administrator accounts.

It is not recommended to create personal accounts in Zivver for email addresses that are used as shared mailbox. For this scenario use a functional account in Zivver instead.

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

If SSO is not configured for you organisation the accounts created by the Synctool will be created with a temporary password. This means users have to know the temporary password created by the Synctool and enter their temporary password at first login. You do not want to create accounts with temporary passwords when using SSO, because password management should be handled by the Identity Provider.

Currently, there are two ways to synchronise personal accounts to Zivver with the Synctool:

  1. From AD
    Explained in this article.
  2. From an Excel file
    Explained in Synchronising personal accounts from an Excel file.

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.

Using AD to synchronise accounts to Zivver

In this manual AD is the source for the synchronisation. The synchronisation is executed in one way: from AD to Zivver, not the other way around. You can determine which accounts are synchronised from AD to Zivver with filters. Filters can for example be an Organizational Unit (OU), Security Group (SG), or Distribution Group (DG).

A single profile can be used to synchronise both personal accounts and functional accounts when functional accounts are SG’s or DG’s with an email address in AD. In this scenario the Synctool will automatically detect the SG’s or DG’s and create functional accounts in Zivver.

More on this topic in Synchronise users and groups.

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 all AD users that should receive a Zivver account. 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 personal account is created, suspended or deleted in Zivver is determined by the source (i.e. the OU used as Base DN) in combination with Filtering options and Synchronisation options.

Users that are not in the OU entered at Base DN will not be synchronised to Zivver. Contrarily, Zivver accounts will be suspended/deleted in Zivver if no matching accounts are found in the source (i.e. AD).

Not finding all users?

Consider choosing a Base DN high up in the AD domain hierarchy, such as DC=company,DC=org. If you worry that not all AD users need a Zivver account, you can exclude users who don’t need Zivver accounts later on with Filtering options.

If you are not sure about which OU to choose, please contact support.

LDAP query
Leave the LDAP query field blank for now. LDAP queries are discussed at Filtering options.

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

E-mail

  • Default AD attribute: proxyAddresses

Zivver accounts must have an email address as username. proxyAddresses is the default AD attribute that contains all email addresses of a user including 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 AD attribute. To do so, click the drop-down menu and select an alternate AD attribute.

Full name

  • Default AD attribute: name

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

ZivverAcountKey field

  • Default AD attribute: objectGUID

It is recommended to pick an AD attribute with a long, random, unique identifier as value for the ZivverAccountKey. If no long, random, unique identifier is available for every user in AD, then use objectGUID instead.

Mobile phone

  • Default AD attribute: mobile

Only synchronise mobile phone numbers to Zivver. Mobile phone numbers are used to automatically configure 2FA via SMS for users that have a mobile phone configured in AD. Nothing happens if the field is blank. Landline numbers should be avoided, because landline numbers often cannot receive SMS codes. This means the user cannot log in when Zivver asks for a second factor.

Is active

  • Default AD attribute: userAccountControl

The value in userAccountControl determines whether a Zivver account is created, suspended or deleted. If an AD user is active, has an email addres, name and ZivverAccountKey, a Zivver account will be created if there is no current account for that email address. Suspended AD users can get suspended or deleted it Zivver, depending on the synchronisation options. It is not recommend to change userAccountControl to a different AD attribute.

Delegates

  • Default AD attribute: MsExchDelegateListLink

Delegates get full access to the Zivver inbox of a personal account. Full access delegations configured in Exchange are mapped automatically to the MsExchDelegateListLink attribute in AD.

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. Your organization cannot use Delegates in Zivver, unless there is another AD attribute that contains the common names of users that should have delegated access to another users’ mailbox.

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.

Member of group

  • Default AD attribute: memberOf

The Synctool will display which SG and DG a user is member of. If the SG or DG has an email address configured, the Synctool can create a functional account and automatically delegate access to users that are member of that SG or DG. Nothing happens if the field is blank.

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.

Assign OU for users

Zivver supports mapping AD Organizational Units to Zivver Organizational Units

Filtering options

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

You can include or exclude users with either the built-in filtering options or an LDAP query.

Built-in filtering options

The built-in filtering options let 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.
  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.

LDAP query

LDAP stands for Lightweight Directory Access Protocol. The Synctool can handle certain LDAP queries to filter users from AD. In this part of the manual only basic LDAP queries are discussed. For more information visit Microsoft’s Wiki page for LDAP filters.

You can’t query OU’s with LDAP in the Synctool. Use the Filtering options described above instead.

Most commonly used LDAP query

(&(objectClass=user)(memberOf:1.2.840.113556.1.4.1941:=))

This LDAP query gives you all users (objectClass=user) for a SG (memberOf:1.2.840.113556.1.4.1941:=).

In the above query, use the distinguishedName of a SG and enter it directly after memberOf:1.2.840.113556.1.4.1941:=.

Filled in example

(&(objectClass=user)(memberof:1.2.840.113556.1.4.1941:=CN=ZivverUsers,CN=Users,DC=company,DC=org))

If you’re LDAP query does not give you the results you want, there are two common mistakes made:

  1. The parentheses are not entered correctly. Make sure you close all the parentheses you open and that they are in the right place.
  2. You are trying to query on an OU instead of SG.

Synchronise users and groups

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 it to the current Zivver accounts.
  3. Check both boxes under Personal accounts sync options.
    This will create new personal accounts and update information of existing personal accounts when available.
  4. Check the box [X] users that are in Zivver but not in local data to be modified.

  5. Select Suspend the accounts of missing users (Recommended).
    This will suspend Zivver accounts when they are suspended or deleted in Active Directory.

    It is recommended to suspend Zivver accounts instead of deleting Zivver accounts. Deleting an account results in losing access to all Zivver messages sent and received by that account. Also, disabling an account can be reverted, while deleting a Zivver account can not be reverted.

  6. Leave the other boxes unchecked.

    A single profile can be used to synchronise both personal accounts and functional accounts when functional accounts are SG’s or DG’s with an email address in AD. In this scenario the Synctool will automatically detect the SG’s or DG’s and display how many groups are found in the source. In all other scenarios you use two distinct profiles to synchronise personal accounts and functional accounts.
    You can use this functionality when [X] groups that are new or changed in local data to sync with Zivver where [X] => 1. If you want to use this functionality, check the box at [X] groups that are new or changed in local data to sync with Zivver under Functional/group account sync options.

    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.

    You are now ready to synchronise Zivver accounts.

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

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

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

  10. Click OK.
    The user synchronisation is complete. The Synctool will prompt you to save the results.

How to automate the Synctool synchronisation using the Windows Task Scheduler

Configure functional accounts

If you have not yet synchronised functional accounts, go to Step 1: Select sync profile in the Synctool and select the profile for functional accounts. Create functional accounts from Exchange, Active Directory or an Excel file.

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?

If you get the above error for one or more accounts there are two possible causes:

  1. The account has an email address that does not belong to a claimed domain in Zivver. Go to domains in Zivver and claim the domain, if you want to create a Zivver account for that domain.
    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. Go to domains in Zivver. There should be an Adopt button, if there are free accounts outside of your Zivver organisation. This button will adopt all accounts using the claimed domain and currently exist outside of your Zivver organisation.

    Adopted accounts are not transferred to your organisation immediately, because adoption of accounts into your organisation cannot be forced. It requires the user to log into Zivver before their account is adopted. If the Adopt button has already been used, you will see an hourglass hourglass_empty indicating the adoption is in process and waiting for the user to log in.

Updated on 2024-01-15