Synctool V1 installation instructions

From 1 July 2023, the Zivver Synctool V1 is out of support. Visit this page to read how you can upgrade to Synctool V2.

Introduction

This manual guides you through the technical requirements, installation and setup of the Zivver Synctool. The Synctool is used for account management in Zivver. The Synctool can create, update, suspend or delete personal accounts and functional accounts in Zivver for a large number of accounts. The synchronisation is one way, from the source (e.g. Active Directory, Exchange) to Zivver.

Technical requirements

The server on which the Synctool will be installed must meet the following technical requirements:

  • The server has Microsoft .NET 4.7.2 or higher installed.
  • The Synctool can make a HTTPS connection (TLS v1.2) on the server via port 443.
  • The Domain Controller (DC) must allow incoming traffic (via port 636) from the server on which the Synctool is installed.
  • Only for Active Directory (AD) on-premise synchronisation: A service account (SA) is available which meets the following requirements:
    • View-Only rights in AD.
    • Can make an LDAP connection to pull data from AD.
    • Can be used to run a basic task in the Windows Task Scheduler.

Optional technical requirements

If you want to synchronise accounts from Exchange, then you need a SA with the following permissions in Exchange or Office 365:

  • Distribution groups
  • View-Only Configuration
  • View-Only Recipients.

Installation

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. You do not want to create accounts with temporary passwords, because password management should be handled by the Identity Provider when using SSO.

Follow the steps below to install the Synctool on a server. Often a domain controller or application server is used, but if you meet the technical requirements, other servers on Windows 10 will work as well.

  1. Download Synctool V2.0.2.
  2. Save the zip file.
  3. Extract the zip file.
  4. Copy or move all extracted files to the desired location on the chosen server.

Creating profiles

Synctool tab | Step 1: Select sync profiles

Log in on the Synctool server with the designated SA. The Synctool configuration is saved in the %appdata% folder of the currently logged in user. With this method you prevent only one admin being able to access the Synctool configuration.

If you configure the Synctool with an administrator account instead of the SA, you can move the configuration afterwards from your %appdata% folder to the %appdata% of the SA.

Basic configuration consists of two Synctool profiles. One profile to synchronise personal accounts and one profile to synchronise functional accounts. A single profile can be used to synchronise both personal accounts and functional accounts when functional accounts are also security groups with an email address. In this scenario the Synctool will automatically detect functional accounts.

When you open the Synctool for the first time there will be a Default profile.

  1. In the Synctool select the tab Step 1: Select sync profile.
  2. Click Edit edit for the Default profile.
  3. Give the profile a name.
    For example: Personal accounts
  4. Optional: Give a profile description.
  5. Click OK.
  6. Click Add new sync profile.
  7. Give the profile name.
    For example: Functional accounts
  8. Optional: Enter a profile description.
  9. Click OK.

Exclude domains for aliases

Smtp-addresses that are not claimed in Zivver should be excluded from synchronisation to Zivver in the Zivver synctool. If you want to synchronise aliases to Zivver for unclaimed domains, you should first claim the domain in Zivver. Additionally, some domains can’t be claimed. For example email aliases under a legacy domain or aliases created when migrating to Exchange Online (e.g. @yourdomain.mail.onmicrosoft.com). For these domains you should configure the Synctool to ignore these domains when synchronising, so the remaining aliases are synchronised.

  1. In the Synctool select the tab Step 1: Select sync profile.
  2. Click Edit edit .
  3. Select Enable Email/Domain Filtering.
  4. Enter one or more domains separated by a semicolon ; or comma ,.
    For example example.com; exampledomain.org; example.onmicrosoft.com
  5. Click OK.
    The entered domains will be excluded from synchronising aliases for Zivver accounts.

Set up a connection to Zivver

Synctool tab | Step 2: Set up Zivver settings

Test the connection by clicking the Test connection button. The Connection test prompt should say Connection successful!. If it doesn’t, make sure the Synctool can make a HTTPS connection (TLS v1.2) on the server via port 443 to https://app.zivver.com/api/.

API key

An API key is used to connect the Synctool to your Zivver organisation. You will create an API key in the administrator portal. Ask a Zivver administrator for admin rights if you are not an administrator for Zivver yet.

Synctool tab | Step 2: Set up Zivver settings

  1. Go to the API Keys page.
  2. Click GENERATE.
    The Add a new API key pop-up appears.
  3. Fill in a name.
    For example: Synctool {admin email address}. This way you know the API key is used for the Synctool and who created the API key.
  4. Click ADD.
    The API key is shown. Make sure to save it somewhere, because the API key will only be shown once.
  5. Copy the API key file_copy .
  6. In the Synctool, paste the API key in the API-key field.
  7. Check the API key for leading or trailing spaces.
The API key is connected to the admin who created the API key. Therefore personal accounts created with this API key will have the same language settings as the admin who created the API key. For an admin with English language settings, this means the accounts created will have English language settings and the notification message default will also be English.
Check or change your language settings here
API keys of deleted administrator accounts are no longer valid. If admin accounts are suspended, then the API key is still valid. However you might still want to change the API key, so that accounts are not created by suspended administrator accounts.
Create a new API key

User login method

Synctool tab | Step 2: Set up Zivver settings

Under the API-key field, you will find the User login method into Zivver, with two options:

  1. Users log in via SSO.
  2. Users need to log into Zivver with a password.

The user login method determines whether an account is created with a temporary password or not.

Users log in via SSO

If accounts are created with Users log in via SSO they are created with a ZivverAccountKey which should be known by the Identity Provider. Because the Identity Provider will handle the username and password, it is not necessary to have a temporary password in Zivver.

A peronal account always needs a ZivverAccountKey for the encryption process. When using SSO, the input for the ZivverAccountKey comes from the Synctool, which receives input from the source (e.g. AD or CSV-import).

If you choose Users log in via SSO, you have to configure SSO before you run the Synctool.

Users need to log into Zivver with a password

If accounts are created with Users need to log into Zivver with a password the accounts are created with a temporary password. The first time a users log in, they need to enter the temporary password and create a Zivver password for their account. After setting a Zivver password, users can log in with their email address and Zivver password. Accounts are created with a temporary password so that the administrator does not know the user’s password.

Preview users

Synctool tab | Step 2: Set up Zivver settings

The Preview users in Zivver button shows you a table with the current Zivver accounts in your organisation. You can download this overview via the Download current users in Zivver as xslx link.

Use the Preview users in Zivver button to test if the API key is valid.

Filtering options

Synctool tab | Step 2: Set up Zivver settings

Filtering at this stage is optional. Apply a filter to include or exclude certain accounts from the synchronisation process.

Use the filter to prevent administrator accounts from being suspended, or to exclude accounts in other managed domains.
  1. Select Apply filter on users/groups.
  2. At Filter field, select the attribute you want to filter on.
    For example: User email address.
  3. At Filter values, enter the values that match the attribute chosen at the previous step.
    For example: john.doe@example.com.
  4. Apply either as a positive or negative filter.
    If you want to exclude an email address from the synchronisation process, choose Apply as negative filter.
  5. Click Preview users in Zivver to see the filtered results.

Go to Step 3: Set up local user/group settings

You are done with step 1 and 2 of the Synctool. Continue to Step 3: Set up local user/group settings. You will first create personal accounts before creating functional accounts.

After that create functional accounts according to either …

If you want to use an Excel file to synchronise both personal and functional accounts start with Synchronising personal and functional accounts from an Excel file.

Was this article helpful?

thumb_up thumb_down