Introduction
Do you experience problems with user management, but don't have the Azure AD synctool running? Please refer to our troubleshooting section on user provisioning & management.
We recommend to always run the latest version of the AAD synctool. Update the synctool first before continuing troubleshooting. You can download the newest version here.
Keep in mind:
Workspace check's for the user's UPN. Changing the UPN during synchronization may cause problems.
Users in your AAD must be assigned a first- and last name.
Users from distribution lists and/or mail-enabled security groups cannot be imported.
Users from Nested Groups cannot be imported.
The App registration for the Azure AD synctool, is separate from the SSO App registration. Meaning, if you ever need to change something to the App registration created for the Azure AD synctool, it will not affect users being able to sign into the Workspace environment.
As an alternative for the Azure AD synctool, you can use Automated user provisioning via SCIM API.
Check if the synctool is up to date
You should always ensure that you are running the latest version of the synctool. To check which version you are running:
Open the file location.
Right click the configuration tool:
Go to Properties.
Select the Details tab.
Check the File Version.
Version not up to date? Update to the latest version, you can download this here.
Synctool logs
When troubleshooting the Azure AD synctool, you should always check the logs for any error messages. Many of these are described in the Errors & Solutions section of this article.
The Logs folder can be found in the same folder where the synctool runner and configuration tool executables are found. From the Logs folder, select the date and then the time of which you want to view the logs. If you have multiple synctools running, make sure that you have the correct synctool directory opened when checking logs.
Force a manual sync
In some situations, you may want to force a manual sync instead of waiting for the periodic synchronization to complete. For example, you're troubleshooting the synctool and, after restarting the sync, want to see if a user was added to the correct group while checking the logs for possible error messages. There are two ways to run a manual sync.
Note: A manual sync cannot be performed if the 'Synchronization settings' of the synctool is set to 'Once a day'. This is by design. And if you run multiple synctools, make sure you restart the correct synctool service.
Option 1 (recommended):
Stop the synctool’s Windows service from Task Manager or services.msc.
Navigate to the synctool’s directory and run 'NDAW.AzureActiveDirectorySync.Runner.exe'.
The sync will run in a CMD window and you can see exactly what the synctool does (this will also be written to the logs). When finished, you'll see the following message:
You can review the log for error messages and subsequently close the CMD window.Start the Windows service again.
Option 2:
Restart the synctool’s Windows service from Task Manager or services.msc.
Manual sync doesn't seem to do anything
When you are running a manual sync, it seems like nothing is happening:
Generally speaking, this happens when the synctool has to process a lot of changes. During any manual sync, the synctool will first inventorize the changes it has to make. While it's doing that, it may seem like nothing is happening. This is especially likely during the first sync, which will always take longer as the synctool has to build its cache at the same time. Depending on the size of your Azure AD and how many users/groups you are syncing, this may take some time. This is a matter of waiting; once the synctool has finished inventorizing you will see it process all the changes.
The exception to this is when the Synchronization type in the synctool's settings is set to Once a day. With this setting, you cannot perform a manual sync. Change the type to Periodical and try again.
Client secret expiration
Explanation: in the first step in setting up the AAD synctool, you have created an Azure AD app registration in Azure. The corresponding client secret has an expiration date. If it is about to expire, or already expired, you will be notified in Azure:
Solution: you will then have to replace the client secret, or delete it and create a new one. To do this:
Click the hyperlink as shown in the example above to create a new client secret.
Fill in the Description and set a new Expiration date.
Click Add.
Note down the Value (not to confuse with 'secret ID'!).
Open the file location where the synctool is running. Open the configuration tool:
In the Connect to Azure AD window, replace the Client secret (value).
Then, click Next.
You have now replaced the client secret.
Tip: after renewing the client secret, schedule a reminder in your calendar to renew the client secret again shortly before its expiration date.
Profile picture not updating
Explanation: when a user has changed their profile picture in Microsoft 365, the current Azure AD synctool will not automatically update the profile picture in Workspace. This is because the profile picture is not an Azure AD attribute. The synctool will only check for changes to Azure AD attributes. This is a limitation of the Azure AD synctool.
Solution: change one of the user's Azure AD attributes (a space behind the name should be sufficient). The synctool will now detect a change to an Azure AD attribute. Subsequently, the user's profile will be synchronised to Workspace, including the new profile picture. Another solution to this problem is to switch over to automated user provisioning via SCIM.
User and/or group synchronization issues
Groups are not syncing as expected
Having both group- and domainfiltering enabled may cause discrepancies in users between your Azure AD and Workspace.
Example: user A is included in domain X and group Y. Domain X is being synced, but group Y is not. As a consequence, user A does not sync accordingly.
If so, try to:
Disable filtering entirely from the synctool's configuration UI.
Restart the Window service of the synctool. This will sync all users to Workspace.
Wait for the sync to complete.
Enable filtering again from the synctool's configuration UI. This way, you can select which users should be added to Workspace and all other users will be removed accordingly.
Restart the synctool service and wait for the sync to complete.
Groups should be be synced accordingly.
Users are not added to specific groups
If users are not added to groups, try to:
Disable filtering entirely from the synctool's configuration UI.
Restart the Window service of the synctool. This will sync all users to Workspace.
Wait for the sync to complete.
Enable filtering again from the synctool's configuration UI. This way, you can select which users should be added to Workspace and all other users will be removed accordingly.
Restart the synctool service.
Wait for the sync to complete.
When the issue is persists, you can think of a clear cache. However, this is not recommend as first solution. Please contact support if you have any questions.
Accidentally deleted a user from a group that is being synced to Workspace
If so, try to:
Stop the Window service of the synctool.
Re-add or recreate the user to the group (or create a new group) in Azure AD.
Make sure to include this group in the group filtering from the synctool's configuration UI.
Restart the synctool service.
Wait for the sync to complete.
The deleted user should now be synced accordingly. If not, check the synctool logs.
User with a reused UPN is not being added to the workspace
It could be the case you deleted a user from your Azure AD that was being synced to Workspace. When you delete this user, he/she will be end up in the Workspace's deleted user list. But perhaps you need to re-add that same user in your Azure AD and sync it to Workspace? It is most likely, if you do this within 30 days, the Azure AD synctool cannot sync that same user to Workspace. Why? Learn more about caching.
You now have two options.
Option 1: wait 30 days until re-adding that same user to your Azure AD to sync it to Workspace.
Option 2: manually delete the user from the Workspace's deleted user list and clear the synctool's cache.
Go to the Workspace setting page.
Go to 'Users & groups'.
Select 'User provisioning'.
Disable the sync from Azure AD.
Click 'Done'.
Go to 'User management'.
Select the tab 'Deleted users'.
From here, delete the user you're trying to re-sync to Workspace.
Go back to 'User provisioning'.
Enable the sync from Azure AD.
Click 'Done'.
Clear the synctool's cache.
Restart the synctool's Windows service.
Permanent deleted Azure AD user is not deleted in Workspace
When a user is permanently deleted in Azure AD, the synctool's cache may not see this change and thus the user will not be deleted and remains active in Workspace. Even a clear cache will not delete the user in Workspace.
Note: we recommend to either soft delete the user in Azure AD, or use automated user provisioning via SCIM.
To delete the user, you must manually delete the user in Workspace:
Go to the Workspace admin setting page.
Go to 'Users & groups'.
Select 'User provisioning'.
Uncheck the checkbox 'Enable sync from Azure AD'.
Click 'Done'.
Go to 'User management'.
Select and delete the user who was deleted in Azure AD. It is optional to permanently delete the user in Workspace from the 'Deleted users' list, but this is not required. Deleted users in Workspace will be permanently deleted after 30 days.
Go back to the 'User provisioning' page.
Enable the sync from AD and click 'Done'.
Errors & Solutions
API Endpoint or resource ID was not found
018-08-16 16:42:00.689 ActiveDirectoryToWorkspaceSyncTool.ActiveDirectory.NotificationService - Error during W365 notification
ActiveDirectoryToWorkspaceSyncTool.ActiveDirectory.NotificationService.A(:0) (null)
NDAW.AdSyncApi.Client.Exceptions.NotFoundException: API Endpoint or resource id was not found
Explanation: some information that was put in, is invalid.
Solution: please check the following:
The Workspace site URL
API Token
Environment name
Server refused to authenticate client, check if API is enabled and authentication token is correct
NotificationService - Error during W365 notification
NDAW.AzureActiveDirectorySync.ActiveDirectory.NotificationService.CreateOrUpdateUserNotification(:0) (null)
NDAW.AdSyncApi.Client.Exceptions.AuthenticationException: Server refused to authenticate client, check if API is enabled and authentication token is correct
Explanation: there is no connection between the Azure AD synctool and Workspace.
Solution:
In the AAD synctool configuration UI, verify the Workspace site URL:
This should be the instance URL without the environment name.
Example: "https://portal.workspace365.net".
In the AAD synctool configuration UI, verify the environment name:
The environment name has to be set, this can be found after the "/" in the environment URL.
Example: "https://portal.workspace365.net/john"
API key & User provisioning method:
Under the User provisioning settings in Workspace, check if the 'user provisioning method' is enabled for Azure Active Directory (AD) sync.
In the Azure AD configuration UI, the API authentication token must match exactly with the Azure AD sync API key in Workspace. f you're not sure anymore if these keys match (because the key is only displayed once after creation), regenerate the Azure AD sync API key in Workspace and fill in the same key in the synctool's configuration UI. Note down/save this key.
FirstName and LastName are required
NDAW.AdSyncApi.Client.Exceptions.ServerValidationException: Server
validation failed: FirstName:This field is required, LastName:This field is required
Explanation: a user must have a first name and last name in Entra ID (previously Azure AD) to be synced.
Solution: enter a first name and/or last name for the user in Entra ID.
Server validation failed: UserPrincipalName:Username is already taken.
NotificationService - Error during W365 notification
NDAW.AdSyncApi.Client.Exceptions.ServerValidationException: Server validation failed: UserPrincipalName:Username is already taken.
Explanation: there is already a user detected in the workspace with the same username. This error usually occurs when you have deleted a user from Entra ID (previously Azure AD), and then recreated them before the user was permanently deleted from the workspace.
Solution: follow the steps described under User with a reused UPN is not being added to the workspace
The remote server returned an error: (400) Bad Request
ActiveDirectoryToWorkspaceSyncTool.AzureAD.Exceptions.AzureAdParsedDataServiceException - Exception parsing failed
ActiveDirectoryToWorkspaceSyncTool.AzureAD.Exceptions.AzureAdParsedDataServiceException.Parse(:0) (null)
System.Net.WebException: The remote server returned an error: (400) Bad Request.
at System.Net.WebClient.DownloadDataInternal(Uri address, WebRequest& request)
at System.Net.WebClient.DownloadData(Uri address)
at ActiveDirectoryToWorkspaceSyncTool.AzureAD.GraphQuery.AzureAdGraphQuery.A()
2020-06-10 09:53:08.562 AzureAdParsedDataServiceException - Exception parsing failed
NDAW.AzureActiveDirectorySync.AzureAD.Exceptions.AzureAdParsedDataServiceException.Parse(:0) (null)
System.Net.WebException: The remote server returned an error: (400) Bad Request.
Explanation: this happens when the Azure AD token that is stored in the sync database is not working (anymore). Probably because the sync token is expired or you have copied the sync folder from customer A (already configured) to customer B.
Solution:
Always start a clean configuration for each customer. On the synctool VM/client, place a blank sync tool configuration from where you can start the configuration for each customer.
You can try to clear the cache (if its a new configuration).
Delete the database from the database folder.
The remote name could not be resolved
"The remote name could not be resolved: demo.workspace365.net”
Explanation: the machine (server) where the synctool is running, cannot be accessed by Workspace.
Solution: check if you can access the server. You can "ping" the server to test its network connectivity. Check the DNS and Firewall settings to see if it can be accessed by Workspace.
System.TimeoutException: Failed to make the request within '00:01:40'
2020-07-03 07:00:10.020 NotificationService - Error during W365 notification
NDAW.AzureActiveDirectorySync.ActiveDirectory.NotificationService.CreateOrUpdateUserNotification(:0) (null)
System.TimeoutException: Failed to make the request within '00:01:40'.
at NDAW.AzureActiveDirectorySync.AzureAD.AzureAdDataService.<MakeRequestWithTimeoutAsync>d__20`1.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at NDAW.AzureActiveDirectorySync.AzureAD.AzureAdDataService.MakeRequestWithTimeout[TResult](Func`2 request)
at NDAW.AzureActiveDirectorySync.AzureAD.AzureAdDataService.GetUserProfilePhoto(String userId)
at NDAW.AzureActiveDirectorySync.ActiveDirectory.NotificationService.ProcessProfilePicture(String activeDirectoryUserId, String email)
at NDAW.AzureActiveDirectorySync.ActiveDirectory.NotificationService.CreateOrUpdateUserNotification(String userPrincipalName, CreateOrUpdateUserParameters createOrUpdateUserParameters)
Explanation: since the Azure AD synctool version 3.0 we make use of the Microsoft Graph instead of the Azure AD Graph. This error is happening when you did update the synctool application, but didn't update the permissions on the Azure AD App registration.
Solution: update the synctool to the latest version. Furthermore, there is a known issue with the synctool and updating profile pictures in Workspace. Click here for more information.
API server failed with internal error
Explanation: this happens when "Your workspace site url" contains illegal characters, such as spaces.
Solution: please make sure to remove these illegal characters. The workspace site url is the root url from the workspace (environment name excluded).
2020-08-27 11:47:42.886 NotificationService - Error during W365 notification
NDAW.AzureActiveDirectorySync.ActiveDirectory.NotificationService.CreateOrUpdateUserNotification(:0) (null)
NDAW.AdSyncApi.Client.Exceptions.ServerException: API server failed with internal error
at NDAW.AdSyncApi.Client.Implementation.ActiveDirectorySyncApiClient.HandleErrors(HttpResponseMessage response)
at NDAW.AdSyncApi.Client.Implementation.ActiveDirectorySyncApiClient.CreateOrUpdateUser(CreateOrUpdateUserParameters parameters)
at NDAW.AzureActiveDirectorySync.ActiveDirectory.NotificationService.CreateOrUpdateUserNotification(String userPrincipalName, CreateOrUpdateUserParameters createOrUpdateUserParameters)
Invalid URI: The hostname could not be parsed
2022-02-16 08:50:31.472 AzureAdToWorkspaceSyncTool - Invalid URI: The hostname could not be parsed. NDAW.AzureActiveDirectorySync.AzureAD.AzureAdToWorkspaceSyncTool+<StartDifferentialSyncAsync>d__15.MoveNext(:0) (null) System.UriFormatException: Invalid URI: The hostname could not be parsed.
Explanation: this happens when "Your workspace site url" contains illegal characters, such as spaces.
Solution: remove spaces (just plain text).
User can’t be found in Workspace
Explanation: this happens when the AzureObjectID doesn't match with the user's UPN in Workspace.
Solution: follow the steps as described under User with a reused UPN is not being added to the workspace - option 2
Test connection failed! Please check AAD configuration settings!
Explanation: information put is, is invalid.
Solution: make sure the app registration information (tenant ID, object ID, etc.) is filled in correctly. If the same error remains, please delete and re-create the client app registration, explained in step 1.
DeltaLink older than 30 days is not supported
Solution:
Make sure you run the latest version of our synctool.
Reinstall the synctool Windows service (scroll down the page to see the list of ways to uninstall and deploy the service).
As last resort Clear cache and restart the service.
Invalid DeltaLink
Explanation: this error may occur after copying an existing synctool configuration (synctool folder) from an already configured customer, to use for a new customer. This folder will contain cached information from the old customer.
Solution: make sure you run the latest version of our synctool and reconfigure the synctool's configuration UI (step 3). This way, you will have a 'clean installation' while running the newest synctool version.