User and Group Synchronization

One of the most important parts of managing PaperCut is to configure the User and Group synchronization options. PaperCut synchronizes user and group information from a source such as Windows Active Directory (Windows domains). This simplifies the administration of the system by avoiding the need to manage a separate database of users and groups. If a user is added to the domain or is removed from a group then PaperCut will automatically synchronize this information without any intervention from the administrator. For example:

Synchronization settings are configured via the OptionsUser/Group Sync tab.

Sync Source

The settings in the Sync Source section defines where PaperCut imports users and groups from.

User/group sync source options

Figure 13.1. User/group sync source options

The drop-down list under Primary sync source selects the type of directory server to be used. Options include Windows Active Directory, LDAP (Apple OpenDirectory, Novell eDirectory, OpenLDAP, etc.), Windows Standard (local users and groups for workgroup environments), Samba and Unix Standard (local users and groups / NIS / POSIX).

The Import users from option allows users to be imported from a specific group in the domain, rather than importing all the users in the domain. This can be useful if the domain contains old users or users who will not be printing.

If the PaperCut server is a member of an Active Directory domain it is recommended to use this option. The advantages over the "Windows Standard" include:

  • Allows using Active Directory organizational units.

  • Supports nested groups for simplified user management.

  • Allows importing of users from other trusted Active Directory domains.

Tip

By default, the Active Directory user source will import all users, including those that are disabled. It is possible to change this behavior using an advanced config entry. To do this:

  1. Navigate to the Options tab.

  2. Press the Config Editor (Advanced) action on the left.

  3. Find the user-source.config-arg property.

  4. Change the value to enabled-users-only .

  5. Press the Update button next to the config property.

Take care when changing this option if you temporarily disable user accounts for disciplinary or other reasons. If you do this, performing a user sync will cause disabled users to be deleted if you also have the Delete old users when syncing option enabled.

Tip

By default, PaperCut MF automatically syncs user and group information with your directory each night. However additional full user/group syncs may be performed by scheduling a script to run the appropriate server-command command. More information on using the server-command can be found in Appendix A, Tools - database, server-command scripting, and APIs (Advanced).

Sync Source Options

Depending on the selected sync source, additional options may be displayed, including:

For more information about synchronizing against Windows Active Directory, see the section called “Using Active Directory for user synchronization”.

For more information about synchronizing against LDAP, including descriptions of the various connection settings, see the section called “Using LDAP for user synchronization”.

Sync Options

The options listed in the Sync Options section control how the synchronization will take place.

  • Update users' full-name, email, department and office when synchronizing - if a user's details in PaperCut do not match those in the synchronization source, they will be updated.

  • Import new users and update details overnight - when selected, synchronization will be automated to occur each night at approximately 1:15am. This option will never delete users from PaperCut.

  • Delete users that do not exist in the selected source - deletes users from PaperCut if they no longer exist in the selected synchronization source.

    This option only applies to manual synchronization (clicking Synchronize Now) and will not delete users when automatically synchronizing overnight. Enabling the option will also only apply once (i.e. the option must be clicked before a manual sync each time when users are to be deleted).

    This option only affects users added via the synchronization source (e.g. the domain) and will not delete internal users.

Secondary Sync Source (Advanced)

Enabling a secondary sync source allows PaperCut to merge the results from two independent sources. Examples for where this may be useful include:

  • A school with an Active Directory domain for the majority of users and a separate LDAP server that is used and managed by one department.

  • An organization with a "new" LDAP server and an old "legacy" LDAP server with separate but unique users that have not been migrated to the new server.

  • A university with an Active Directory for the Windows student workstations and an Open Directory for the staff Mac workstations.

When enabled, PaperCut will query both sources to find users and groups. Usernames are treated as globally unique, so the same username existing in both sources will be treated as the same user (in this case, the details for the user will be merged, with the primary sync source taking priority). If there is an error connecting to or synchronizing against either source then no actions will take place.

Manual Synchronization

By default, PaperCut MF automatically re-syncs the user and group information each night, however the sync process can also be initiated manually. To initiate a manual sync:

  1. Navigate to the OptionsUser/Group sync tab.

  2. Press the Synchronize Now button.

  3. The sync process will start and a status window will open showing the status of the sync process.

Progress of a user/group synchronization process

Figure 13.2. Progress of a user/group synchronization process

Importing Card/Identity numbers from Active Directory or LDAP

In PaperCut MF a unique card/identity number can be associated with each user. The card number is used as an alternative to usernames/passwords for authentication at software release stations, or at hardware terminals attached to photocopiers. The card/ID number can also be searched in the user quick-find in the User List page.

The card/ID number can be entered manually in the user interface, imported using the batch user import/update feature (see the section called “Batch User Data Import and Update”), or imported using the batch user card/identity update feature (see the section called “Batch User Card/Identity Update”), however it is usually more convenient to automatically import them from Active Directory or LDAP. Unlike other fields like full-name and email address there is no single field used exclusively for card numbers. For this reason PaperCut MF allows specifying the field to import the card/ID number from.

To enable importing the card/identity number, first enable the Update users' full-name, email, department and office when synchronizing and the Update the users' unique card/ID number from the AD/LDAP field options. Then enter the field name to import the card/identity number from and press Apply. For more information on the field names to use, see the sections on Active Directory and LDAP below.

Important

The card/ID number must uniquely identify a user, so you should ensure that no two users have the same card/identity number. The card/identity numbers you have defined in your user source should be unique. If PaperCut MF finds a non-unique card/identity number it will not update the user's details, and will display a warning in the synchronization results.

Importing the Card/Identity number from Active Directory

Active Directory has a number of user fields that can be used to store the user's card/identity number. Some of these fields are editable in the user's properties in the Active Directory Users and Computer tool, but others can only be updated with other tools. By default, PaperCut MF will import the card/identity number from the user's pager number field (i.e. the pager field). This field was chosen because it is rarely used and is also editable in the Windows user interface. If this field is not suitable, you can choose any valid Active Directory user field.

The list of standard Active Directory user fields can be found on the Microsoft web site here: http://msdn2.microsoft.com/en-us/library/ms683980.aspx. The field name entered in PaperCut MF must be in the LDAP display name format. For example, if you want to use the Employee-Number field, then the field name entered into PaperCut MF should be employeeNumber as shown on the Employee-Number attribute page here: http://msdn2.microsoft.com/en-us/library/ms675662.aspx

Important

If the field name is entered incorrectly, the synchronization will fail. It is therefore important to test your configuration changes. To test the changes, press the Test Settings button. If the card number is retrieved correctly, then they will be listed as the 4th user field in the test output.

Importing the Card/Identity number from LDAP

LDAP provides a very flexible way to store a variety of user related information. The fields available depend on LDAP server being used and how that is configured. Many LDAP servers also allow administrators to create custom fields to store additional custom user information. It is recommended you consult your LDAP server's documentation or talk to your LDAP administrator to understand which LDAP field your stores the user card/ID number.

By default, PaperCut MF uses the employeeNumber field to retrieve the card number. This is a standard LDAP field, but id this is not suitable, you can choose any valid LDAP user field.

Important

It is important to test the card numbers are being retrieved correctly. To test the changes, press the Test Settings button. If the card number is retrieved correctly, then they will be listed as the 4th user field in the test output.

Using a regular expression to extract the card/id number from an LDAP/AD field

The vast majority of sites store the full card number in a single field in AD/LDAP. In this situation there is no need to use a regular expression (regex) to extract the card number. A regular expression is only required under some unusual specific circumstances, including:

  1. The field contains more then just the card number. For example, if the field contained a card number and student number separated by a comma (e.g. 12345678,0003456).

  2. The multi-valued LDAP/AD field contains multiple values and only one representing the card number. e.g. Some third party authentication management systems store external IDs (like card numbers) in a single multi-valued LDAP field. NOTE: For multi-value fields, PaperCut will import all the field values separated by TABs by default. The regex may be used to extract the required portion of the field.

To use a regular expression to extract the card/id number, enable the Apply regular expression to extract card number option on the User/Group Sync page. Then enter the regular expression used to extract the card number. The regular expression must contain a capture group (represented by parentheses), that represents the part of the field that the card number is extracted from.

The simplest way to create a regular expression is to start from one of the examples that follow.

Regular ExpressionDescription

([\d]+)

Extracts the first sequence of digits. e.g. if the field contains 12345678,005678 then 12345678 is extracted.

([\d]{5})

Extracts the first sequence of 5 digits. e.g. if the field contains 12345678 then 12345 is extracted.

=([\d]+)

Extracts the sequence of digits after the = character. e.g. if the field contains 12345678=56789" then 56789 is extracted.

([\d]+)::abc

Extracts the sequence of digits preceding the text ::abc. This is a common notation when storing identities in a multi-valued field in LDAP. The ::abc notation is used to indicate the different identity types. In this example, if the field contains 1234::xyz 5678:qrs 9876::abc then 9876 is extracted.

Table 13.1. Example regular expressions to extract card numbers

Regular expressions are an advanced topic and can be tricky to get just right. For more information on regular expressions and a test tool see http://www.fileformat.info/tool/regex.htm. If you need assistance, please contact support.

On Demand User Creation

The On Demand User Creation setting defines if and when PaperCut MF will create new users. The settings applied to newly created users are defined by their group membership (for more information see the section called “New User Creation Rules”). By default, new users are created automatically when they print for the first time, use the internet, start the user client tool or log into the user web tools. This makes administration much easier, as there is no need for additional administration when new users come along; they can use PaperCut MF straight away.

In some situations it may be preferable to change the way new users are treated. For example when just one department is being tracked, but there are other departments using the same printers, it may be preferable to allow the other departments' users to print, but not to track them using PaperCut MF.

There are three options available for the setting When the user does not exist:

  1. create the user on demand (default) - users are created when they interact with PaperCut MF for the first time. E.g. when they print for the first time.

  2. do not create the user and allow usage - users interacting with PaperCut MF who do not already exist will not be created, but their usage will be allowed. The usage will not be logged.

  3. do not create the user and deny usage - users interacting with PaperCut MF who do not already exist will not be created, and their usage will be denied. The usage will not be logged.

On demand user creation options

Figure 13.3. On demand user creation options

To change the behavior, select the desired option and press Apply.

Using Active Directory for user synchronization

PaperCut MF's Active Directory integration is performed at a native level and supports advanced features such as nested groups and OU's. Some additional options provided with the Active Directory interface include:

  • Import disabled users - If set, all users, including disabled accounts will be imported from the domain. In an education environment it is recommended to leave this option on as often student accounts are disabled for disciplinary actions, and removing the account from PaperCut MF is not appropriate.

  • Enable multi-domain support - This is an advanced option and is appropriate for larger sites running multiple trusted domains. For example, in an education environment it is common to have separate domains for students and staff/teachers with a one-way trust relationship. This option can bring in groups, OU's and users from both domains.

    The list of domains is semicolon separated (;). This list should contain the name of the domains in DNS dot notation, and should include the name of the current domain if importing from this domain is desired.

    Trust domain relationships are a complex area and administrators are advised to use the Test button to verify that the settings result in the desired behavior. The total number of user accounts is a good measure.

Using LDAP for user synchronization

LDAP (Lightweight Directory Access Protocol) directories usually store information about user and groups in an organization. One of the most common uses of LDAP is to provide single sign-on on a network that comprises multiple platforms and applications. When a network consists of only Windows computers, then an Active Directory domain can be used. But when there is a mix of Windows, Apple and Linux machines then LDAP can provided the single source of user, group and authentication information. (It is worth noting that both Active Directory and Novell eDirectory implement the LDAP protocol).

PaperCut MF can use an LDAP directory for user authentication and as a source of user and group information. LDAP can either be enabled at installation time, or by changing the user source option in OptionsUser/Group sync. When enabling LDAP, a number of configuration settings must be specified to allow the application to connect to the LDAP server. Please ask your LDAP administrator what values to use for the various options:

  • LDAP Server Type - Determines which LDAP fields are used to get user and group information.

  • LDAP Host address - The hostname or IP address of the LDAP server.

  • Use SSL - Indicates if an encrypted SSL connection should be used to connect to the LDAP server. The LDAP server requires SSL support to be enabled and should accept connections on the standard LDAPS port 636.

  • Base DN - This is the Base DN of the LDAP server. This is the equivalent of the "suffix" config setting of the OpenLDAP server. For example, if the domain hosted by the LDAP server is "domain.com" then the Base DN might be DC=domain,DC=com. The format of the Base DN can differ significantly depending on configuration. Some older Novell eDirectory installations may require a blank Base DN to operate. Some examples:

        DC=myschool,DC=edu,DC=au
        DC=myorganization,DC=com
        OU=OrgUnit,DC=domain,DC=com
        DC=local
                            

  • Admin DN - The DN of the user who has permission to connect to and query the LDAP server. This is typically an administrative user, although it can be a user that only has read-only access to the LDAP server. An example of the DN of the Administrator user on a Windows AD domain "domain.com", would be CN=Administrator,CN=Users,DC=domain,DC=com. The exact format of the DN depends on the LDAP server. Some examples:

    • Windows Active Directory: CN=Administrator,CN=Users,DC=domain,DC=com

    • Windows Active Directory (in organizational unit): CN=administrator,OU=OrgUnit,DC=domain,DC=com

    • Mac Open Directory: uid=diradmin,CN=users,DC=domain,DC=com

    • Unix Open LDAP: uid=root,DC=domain,DC=com, or uid=ldapadmin,DC=domain,DC=com

    • Novell eDirectory: CN=root,DC=domain,DC=com, or CN=ldapadmin,OU=users,DC=domain,DC=com.

  • Admin password - The password for the above user.

Tip

Some LDAP servers are configured to allow 'anonymous' LDAP query access. In these situations, the Admin DN and Admin password may be left blank.

PaperCut MF supports the following server types:

  • Novell eDirectory

  • Microsoft Active Directory

  • Unix / Open Directory

However, it is easy to support other server types by adjusting the LDAP fields PaperCut MF searches. This is discussed in Appendix C, Advanced LDAP Configuration.