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.2. 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 a subset of users option allows users to be imported from a list of selected groups 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.

Tip

If you are using Active Directory and have a long list of groups, you can set the config key user-source.ad.group-ou-filter to only display groups under a certain organizational unit. For example, if you set it to "myorganization.local/Import OU/Sub Import OU" then it will only display groups under "Sub Import OU".

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, PaperCut NG 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 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 12:55am. 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 NG 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.3. Progress of a user/group synchronization process

Card/Identity Numbers Sync

Card and ID numbers are 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. See the section called “User card and ID numbers” for more information.

In PaperCut NG one or two unique card/ID numbers can be associated with each user. These are known as the Primary and Secondary card/ID number. You may choose to automatically import or generate these card/ID numbers for each user.

Very commonly, card/ID numbers are already assigned by other systems, in which case it is required to import these numbers into PaperCut from Active Directory or LDAP. Unlike other fields like full-name and email address there is no standard field used exclusively for card numbers. For this reason PaperCut allows specifying the field to import the card/ID number from.

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

For your convenience, PaperCut also allows you to generate a random card/ID number for either the primary or secondary card/ID number. To auto-generate, select the option Auto-generate random ID (if blank) and specify the length or number of digits. Short numbers are easier to remember and faster to key in, but it is also easier to guess someone else's number. If your number is too short, PaperCut may not be able to generate sufficient numbers to cover all your users.

Important

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

When generating card/ID numbers, you are asked to specify the length or number of digits you require in the generated numbers.

Card/ID number Sync Options

Figure 13.4. Card/ID number Sync Options

Importing the Card/ID number from Active Directory

Active Directory has a number of user fields that can be used to store the user's card/ID 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 NG will import the primary card/ID 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 NG 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 NG should be employeeNumber as shown on the Employee-Number attribute page here: http://msdn2.microsoft.com/en-us/library/ms675662.aspx

A secondary card number field can be specified by selecting Sync from AD/LDAP field under Secondary number.

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 NG uses the employeeNumber field to retrieve the primary card number. This is a standard LDAP field, but if this is not suitable, you can choose any valid LDAP user field.

A secondary card number field can be specified by selecting Sync from AD/LDAP field under Secondary number.

If using a secondary sync source, then select Sync from AD/LDAP field under Secondary number to specify the field. If defined, then the same regular expression that is applied to the first card number will be applied to the second card as well.

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 NG 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, authenticate via 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 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 NG.

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 NG 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 NG 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 NG 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.5. On demand user creation options

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

Using Active Directory for user synchronization

PaperCut NG'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 NG 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.

  • Import other email addresses - Advanced option to allow importing a user's other (secondary) email addresses from a custom field. The field is configured using user-source.ad.other-emails-field.

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 NG 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.

    The Admin DN and password is optional if your LDAP server allows anonymous binds for querying.

  • 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 NG 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 NG searches. This is discussed in Appendix C, Advanced LDAP Configuration.

Tip

Advanced features such as Nested Groups and OU are supported by the Windows Active Directory sync option. See the section called “Using Active Directory for user synchronization”