Troubleshooting User/Group Sync with Active Directory

Importing users & groups from Active Directory is the most popular and widely-used method of managing users in PaperCut NG/MF. It’s a highly efficient and reliable service, which provides the flexibility to administer a wide range of environments.

However like most things in life, problems can and do arise, and in this article we will address how you can resolve the most common synchronization issues with Active Directory.

NOTE: It’s important to mention that this article only covers troubleshooting the standard connection to Active Directory. We discuss troubleshooting LDAP synchronization and synchronization from other directory sources in the manual and in other articles.

The Basics

In this article we discuss some basic checks on configuration that can affect the success of your user/group synchronization with PaperCut, as well as specific issues and errors that you may encounter with your sync.

Our article here details a few potential limitations with AD. We recommend taking a look over that article to make sure that the sync issue you are experiencing isn’t related to any of those limitations.

Here are some basic troubleshooting checks you can perform to help rule out the possibility that the problem isn’t the result of your current configuration:

1. A common cause of sync problems is changes in your environment - such as on the network, domain, permissions, etc. Check your change-control records, and discuss with your team, to see whether this applies in your case.

2. Because PaperCut NG/MF’s user list is essentially a mirror of the directory source that you point it to, your sync will only find what you ask it to find. The User/Group Sync page (found on the PaperCut admin web interface, in Options → User/Group Sync) provides the option to either ‘Import all users’ or ‘Import users from selected Groups’ - so make sure that this option is set correctly for your requirements. If you are using the ‘sync users from selected groups’ option, take a careful look through the list to ensure that the relevant groups containing your PaperCut users are included.

3. PaperCut NG/MF has a simple way to test the sync source connection. In the PaperCut admin web interface navigate to Options, then click on the User/Group Sync tab.

Scroll down to Test Settings.

Watch the pop-up window for any error messages, like the example below.

4. By default PaperCut NG/MF runs as the local SYSTEM service account. Generally this is adequate to facilitate a successful read-only sync with AD to obtain the relevant user and group attributes and OU profiles from Active Directory.

However, in some instances (e.g. if the Active Directory server has restricted access or is a member of a different domain) then the local SYSTEM account may lack adequate permissions, in which case a service account with adequate read privileges to Active Directory is required in order for the sync to succeed.

If you need to change the PaperCut’s service account, review our article here for guidance on achieving this.

5. The server on which PaperCut NG/MF is installed requires a connection to a valid Domain Controller (DC). PaperCut uses that connection to provide the sync process.

To confirm an AD connection for the server, open command-prompt on the server and type:

echo %logonserver%

A valid response will be the Domain Controller that the PaperCut Server is connected to.

I’ve covered “The Basics” but I’m still having issues!

Ok, so you checked the items above but these suggestions didn’t help to fix your issue. No problem, we’ll now focus on a few specific scenarios that can occur.

• My sync fails to run successfully
• I see an “error creating user” message in the sync status popup
• I see an “error creating new users” in the Application Log
• A particular user/group is failing to sync
• User details are not updating via the sync
• Group membership is not updating via the sync

My sync fails to run successfully

When PaperCut syncs with Active Directory, it relies on a separate executable called UserDirAd.exe. You need to ensure that this directory is included in your Anti-Virus exceptions.

When troubleshooting sync issues, we recommend following this knowledge base article which details how to obtain debug output from AD to help determine the exact reason for the failure.

I see an “error creating user” message in the sync status popup

Starting User synchronization…
Synchronizing users and groups
Synchronization process starting
Retrieving users (may take a while on large networks)…
Retrieving existing users from database…
Checking for new users to add…
**ERROR creating user** bobsmith in the application database. Could not execute JDBC batch update; SQL

Typically this error indicates an issue writing to the PaperCut NG/MF database. We recommend restoring the database from your most recent backup in order to resolve this user sync issue.

I see an “error creating new users” in the Application Log

This is a very generic error message that doesn’t provide specific details of the problem, so we need to gather more information. We recommend using the Test Settings button on the sync page or performing the AD debug steps in order to help isolate the cause of these errors.

A particular user/group is failing to sync

1. In order to keep the sync process compatible with older Windows environments, PaperCut NG/MF relies on the pre-Windows 2000 variant of usernames, known as the sAMAccountName which imposes a strict 20 character limit. You can see an example in this knowledge base article which clarifies where to find it within a user’s Active Directory Properties panel.
2. If you have a large number of AD groups and previously configured a group override (as mentioned here), check the PaperCut NG/MF config editor to see if there is still a group filter or list override in place.

You can find the config editor by opening the PaperCut admin web interface, and going to the Options → Actions → Config editor (advanced) page.

The relevant keys are:

• User-source.ad.group-ou-filter
• User-source.group-list-override

If it’s a user that is missing, you might have ignored users set, in which case search config editor for these keys:

• User-source.ignored-users
• User-source.ignored-users.x

Also it would be worth checking whether the missing user object is disabled in Active Directory. By default, PaperCut NG/MF does not synchronize users with a ‘disabled’ status in the directory source, so this needs to be manually enabled if you want these users included in the sync (see “Import disabled users’ checkbox at the top of the User/Group Sync settings, or following this article here).

Disabled users are being imported

Since PaperCut NG/MF 14.0, disabled users are no longer imported by default. If you are seeing disabled Active Directory users in PaperCut then one of two things might be happening:

• The Make sure the Import disabled users checkbox is off, found on Options > User/Group Sync. If this box is checked, then disabled users will be imported.

• More likely, the users were disabled after they were imported into PaperCut. To remove these users go to Options > User/Group Sync, select Delete users that do not exist in the selected source… then select Test Settings and review the results of the test sync. When you are ready to make the change permanent, select Synchronize Now.

   

User details are not updating via the sync

The first thing to check in this scenario is that the following checkbox is enabled on the User/Group Sync page:

This ensures that all details relating to email addresses, departments, card/id numbers, etc, are imported from the directory source.

Once you select that option, you can either leave the sync to run again overnight, or you can press Synchronize Now to immediately test the results of using this option for your sync.

• NOTE - If you would like to synchronize a secondary email address for your users, you can follow the instructions https://www.papercut.com/kb/Main/SyncingFromASecondaryEmailAddressInActiveDirectory .

If you are still experiencing an issue with the retrieval of some details for your users, we recommend that you run the AD debug tool to help establish the cause.

If necessary, you may need to change the service account that is running your PaperCut Application Server service. The details of this step are detailed here.

Group membership is not updating via the sync

If you completed the standard troubleshooting steps above regarding user and group sync, and there is still a specific issue with regards to your user’s group membership not updating via the sync, then it’s worth mentioning a common issue with Active Directory, and applications that use its API to import users. The API cannot grab the user objects based on group membership if the group that PaperCut NG/MF is pointing to is the user’s “Primary Group”. Take a look at this article here which provides further details.

If a user has a $ within their username they will not be synced into a group. A workaround for this is to create an internal group, more information on this can be found here which provides details on how to enable these.

Users lose group membership overnight

Prior to the 23.0.3 MR release, Windows AD customers reported that problems with the overnight sync caused users to lose their association with groups and any PaperCut features that relied on Group Memberships such as Quotas, Print Deploy Zones, Filters and Restrictions, Shared Account Access, Scan Action Access, and Admin rights. If after upgrading to 23.0.3 you have any problems related to this issue, please let us know by raising a support ticket.