Troubleshooting the Azure AD synctool

Table of Contents

 

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.

Back to top

 

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:

  1. Open the file location.
  2. Right click the configuration tool:
    xe2.png
  3. Go to Properties.
  4. Select the Details tab. 
  5. Check the File Version.

Version not up to date? Update to the latest version, you can download this here

Back to top

 

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.

Back to top

 

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):

  1. Stop the synctool’s Windows service from Task Manager or services.msc.
  2. Navigate to the synctool’s directory and run 'NDAW.AzureActiveDirectorySync.Runner.exe'.
    exe.png
  3. 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:
    sync_done.png
    You can review the log for error messages and subsequently close the CMD window.
     
  4. Start the Windows service again. 

Option 2:

  1. Restart the synctool’s Windows service from Task Manager or services.msc.

Back to top

 

Manual sync doesn't seem to do anything

When you are running a manual sync, it seems like nothing is happening:

SynctoolSeemsStuck.png

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.

Back to top

 

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:

expired_certificate__about_to_expire_.png

expired_certificate.png

Solution: you will then have to replace the client secret, or delete it and create a new one. To do this:

  1. Click the hyperlink as shown in the example above to create a new client secret.
  2. Fill in the Description and set a new Expiration date. 
  3. Click Add.
  4. Note down the Value (not to confuse with 'secret ID'!).
  5. Open the file location where the synctool is running. Open the configuration tool:
    xe2.png
  6. In the Connect to Azure AD window, replace the Client secret (value).
  7. 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.

Back to top

 

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

Back to top

 

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:

  1. Disable filtering entirely from the synctool's configuration UI. 
  2. Restart the Window service of the synctool. This will sync all users to Workspace. 
  3. Wait for the sync to complete.
  4. 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.
  5. Restart the synctool service and wait for the sync to complete.

Groups should be be synced accordingly.

Back to top

 

Users are not added to specific groups

If users are not added to groups, try to:

  1. Disable filtering entirely from the synctool's configuration UI. 
  2. Restart the Window service of the synctool. This will sync all users to Workspace. 
  3. Wait for the sync to complete.
  4. 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.
  5. Restart the synctool service.
  6. 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.

Back to top

 

Accidentally deleted a user from a group that is being synced to Workspace

If so, try to:

  1. Stop the Window service of the synctool.
  2. Re-add or recreate the user to the group (or create a new group) in Azure AD. 
  3. Make sure to include this group in the group filtering from the synctool's configuration UI.
  4. Restart the synctool service.
  5. Wait for the sync to complete.

The deleted user should now be synced accordingly. If not, check the synctool logs.

Back to top

 

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.

  1. Go to the Workspace setting page.
  2. Go to 'Users & groups'.
  3. Select 'User provisioning'.
  4. Disable the sync from Azure AD.
  5. Click 'Done'. 
  6. Go to 'User management'. 
  7. Select the tab 'Deleted users'.
  8. From here, delete the user you're trying to re-sync to Workspace.
  9. Go back to 'User provisioning'.
  10. Enable the sync from Azure AD.
  11. Click 'Done'. 
  12. Clear the synctool's cache. 
  13. Restart the synctool's Windows service. 

Back to top

 

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:

  1. Go to the Workspace admin setting page.
  2. Go to 'Users & groups'.
  3. Select 'User provisioning'.
  4. Uncheck the checkbox 'Enable sync from Azure AD'.
  5. Click 'Done'. 
  6. Go to 'User management'. 
  7. 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.
  8. Go back to the 'User provisioning' page.
  9. Enable the sync from AD and click 'Done'. 

Back to top

 

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

Back to top

 

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.

Back to top

 

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.

Back to top

 

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

Back to top

 

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.

Back to top

 

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. 

Back to top

 

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. 

Back to top

 

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)

  Back to top


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

Back to top

 

Test connection failed! Please check AAD configuration settings!

test_connection_failed.PNG

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.

Back to top

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.

Back to top

 

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. 

Back to top