On Monday May 20th, Workspace 365 support is not available due to a national holiday.
Due to a SharePoint malfunction you may experience issues with the Documents app. Refer to the Microsoft 365 Service Health center for the latest status.
Hi , how can we help?

Step 3. Azure AD synctool configuration UI

Table of Contents


Introduction

In this step, we’ll configure the synctool so it can connect both to Microsoft Entra ID (previously called Azure AD) and the Workspace.

All the data you have collected in the first two steps can be filled in the configuration UI tool. You can find this tool in the downloaded Workspace 365 synctool folder. When you unzip the folder, the name of the file is: 
xe2.png

 

Configuration UI synctool

Let's get started

To disable the welcome page, uncheck checkbox at the bottom of the page. You can change the default language to Nederlands or English. Click Next to continue.

lets_get_started.PNG

Back to top

 

Connect to Azure AD

To connect the Azure AD synctool to Microsoft Entra ID, fill in the fields below. Click Next when all information is entered. Here, the connection to the entered information/Microsoft Entra ID will be validated.

  • Tenant ID
  • Tenant name
  • Application (client) ID
  • Client secret (value)

connect_to_AAD.PNG

Back to top

 

Environment settings

To add a new environment, fill in the following and click on 'Save' when you're done: 

Your Workspace site URL: this is the workspace base URL where all the environments are hosted on, mostly 'https://{companyname}.workspace365.net'.

Environment name: this must match exactly with the environment name in Workspace 365 and can be retrieved from the Workspace 365 URL, e.g. 'https://portal.workspace365.net/john -> john'.

The environment name must be lower case.

Sync API authentication token: this must match with the Workspace 365 environment 'Users & groups' > 'User provisioning' > API key  (step 2). 

environment_settings.PNG

Back to top

 

Filtering

Accidently included the wrong group and/or domain in filtering? No worries! You may follow these steps:

  1. Uncheck the checkbox for that specific group and/or domain.
  2. Click 'Save'. 
  3. Wait for the periodical sync to begin and has finished, or restart the synctool service yourself.

The corresponding users will then be automatically removed and won't be able to sign into Workspace. The removed users will be present under the "deleted users" list under 'User Management' and will be removed permanently after 30 days (of course these users will not be deleted from Microsoft 365!).

Changed your mind or want to add to a specific group and/or domain? Follow these steps:

  1. Check the checkbox for that specific group and/or domain.
  2. Click 'Save'. 
  3. Wait for the periodical sync to begin and has finished, or restart the synctool service yourself.

The corresponding users will be now be added to the Workspace environment.

 

Domain filtering

You can choose the desired filtering options. If you leave both unchecked, domain- and group filtering, it will sync all users and groups.

If you want to enable domain filtering, check the enable domain filtering checkbox. This will expand and show all domains and subdomains within the current domain.

domain_filtering_2.PNG

You can make a selection of the desired domains you want to sync. All users with the domain prefix selected will be synced in this case:

  • johndoe@ndawdev.onmicrosoft.com
  • carter@ndawdev.onmicrosoft.com

Will not be synced:

  • bay@subdomain.ndawdev.onmicrosoft.com

Back to top

 

Group filtering

If you want to enable group filtering, check the enable group filtering checkbox. This will expand and show all groups within this current domain.

We do not support nested groups.

group_filtering_2.PNG

Here you can make a selection of the desired groups you want to sync. All users within the selected group and the group itself will be synced in this case:

  • All members of ‘Anton League’
  • All members of ‘prefix1demo_1’
  • Group ‘Anton League’
  • Group ‘prefix1demo_1’

Will not be synced:

  • All other groups that are unchecked including the users

Back to top

 

Domain- and group filtering

It is possible to combine both, domain- and group filtering, as shown below:

domain_group_filtering.PNG


We have the following active directory structure:

  • 24631 development
    • johndoe@ndawdev.onmicrosoft.com
  • Anton League
    • rhodes@ndawdev.onmicrosoft.com
  • App search
  • prefix1demo_1
    • carter@ndawdev.onmicrosoft.com
    • bay@subdomain.ndawdev.onmicrosoft.com

 

If domain filtering is enabled and the following checked:

  • onmicrosoft.com

If group filtering is enabled and the following is checked:

  • Anton League
  • prefix1demo_1


The following users and groups will be synced:

  • All members of ‘Anton League’ with the ndawdev.onmicrosoft.com domain
    • rhodes@ndawdev.onmicrosoft.com
  • All members of ‘prefix1demo_1’ with the ndawdev.onmicrosoft.com domain
    • carter@ndawdev.onmicrosoft.com
  • Group ‘Anton League’
  • Group ‘prefix1demo_1’

Will not be synced:

  • All other groups and domains that are unchecked including the users

Back to top

 

Synchronization settings

Click on preferences to open the synchronization settings menu. 

You can set the synchronization type to Periodical or Once a day.  If you choose to set the synchronization type to 'Periodical' you need to define the interval in hours and/or minutes. If you choose to set the synchronization type to 'Once a day', you need to define at which time you want to run the sync.

If you set the synchronization type to Once a day, you cannot perform a manual sync. When set to Periodical, you can perform a manual sync.

synchronization_settings.PNG

Back to top

 

Clear cache

What is caching? And how does it work?

Why do we have caching? Well, caching makes things much faster. Instead of syncing every user object from scratch, the Azure AD synctool will only check for changes, and only these changes will be handled by the synctool and written to the cache. The cache can be seen as the synctool's "memory". When you clear the synctool's cache, you basically clear the synctool's memory and thus the entire user history. Unfortunately you cannot look into the cache history.

When you make user changes like adding or removing users in Microsoft Entra ID, these changes are written to the synctool's cache. That is, when the sync from the User provisioning settings in Workspace is enabled.

AD sync in Workspace disabled

But what happens when you disable the sync and make manual user changes in Workspace 365? For example, you removed a user in Workspace from a group that is being synchronized while the sync was disabled in Workspace. As a consequence, this user change will not be written to the cache. In other words, the cache still thinks the user exists in Workspace. So, what happens when you made a mistake and want to re-add that same user? It doesn't matter if you also deleted the user from the deleted user list, the cache still thinks the user exists in Workspace and, as a consequence, the synctool will not sync the user.

Why do we want to avoid clearing the cache?

If users are not being updated or added to specific groups, clearing the cache may fix this issue. However, we have seen that clearing the cache may cause user discrepancies later on and it can take a long time to sync all user objects, especially in large environments, and is generally too resource-intensive.

So how can I fix user synchronization issues, without clearing the cache?

  1. You need to make sure that Microsoft Entra ID is in correspondence with Workspace. If you deleted or added a user from a group in Workspace, you need to do the same in your Microsoft Entra ID.
  2. Make sure you enable the sync in Workspace under the User provisioning settings.
  3. Restart the synctool's Windows service.
  4. Wait for the sync to complete. When complete, the cache is up to date.
  5. Now you can make user changes in Microsoft Entra ID. If you had filtering disabled, you can create a new group of users in Microsoft Entra ID and sync it to Workspace.

What do I need to take into account when I still want to clear the cache? 

Do not clear the cache as first solution! If you clear the cache, please make sure you run the latest version of the Azure AD synctool. Please contact support when you're in doubt.
If groups are not being synced accordingly, try disabling filtering first and run a full sync before you clear the cache. When the sync is complete, you can enable filtering again and sync the selected groups.

How to clear the cache

  1. Make sure the checkbox of the synctool is enabled in Workspace.

    enablesync.png

  2. Stop the synctool service.
    (This way, you make sure the synctool button won't trigger while executing the clear cache).
  3. In the synctool configuration UI, click "Preferences" at the bottom left. 
  4. Then, click the “Clear cache” button at the bottom right. 
  5. Click “Ok” to confirm. 
  6. Run the synctool manual in the synctool directory as an administrator.

    service.png

  7. Wait until the user is added to the Workspace.
  8. Start the synctool service.

Proceed to step 4

Back to top