Case Study - Custom User Sync Integration

KB Home   |   Case Study - Custom User Sync Integration

Overview

This is a case study of an operating environment that revolves around a proprietary software system which is the primary handler of authentication and maintains and stores user records. Such systems can include proprietary industry-specific ERP and workflow systems that entire companies centralize around and can be difficult to interface with.

If one is lucky, the backend of such systems can be directly accessed or the software vendor provides utilities to allow for integration with external systems. This case study is a starting point to allow developers to integrate these custom and unique systems into PaperCut.

This type of integration utilizes PaperCut’s support for custom user directory and authentication programs. More information on this can be found in the PaperCut manual Chapter 24.

Technical Overview

Programs on the server can be specified in PaperCut to import users and groups and another for authentication. Depending on the request, parameters are passed to the program via command line arguments and standard-input. Information on data formats and triggers are available below. This allows developers to make utilities to bridge their system and Papercut together to the extent of user information and authentication.

PaperCut Sync Source

To achieve the above, we rely on the Sync Source feature in PaperCut, specifically, the Custom program option.

This can be accessed and enabled by doing the following:

  1. Navigate to the OptionsUser/Group Sync tab.
  2. The settings in the Sync Source section defines where PaperCut imports users and groups from. Change the Primary sync source to Custom program.
  3. Enter in the path to the program that enumerates user and group information in the field Custom user program.
  4. Enter in the path to the program that handles user authentication in the field Custom auth program.

Source code for an example program which utilizes this feature is provided with the PaperCut installation and can be found at [install-path]/server/bin/linux-x64/src/ or [install-path]/server/examples/.

Custom user program

Below are the different calls PaperCut will make to a configured custom user program as well as the valid and expected inputs and output.


Function: is-valid

Test to see if the custom command is valid and appropriately configured for use.

Program Call

[CustomUserProgram] - is-valid

Example Program Call

MyCustomUserProgram.exe - is-valid

Standard-input

N/A

Standard-output

  • Y\n when custom provider is functioning and valid.
  • Or; N\n when is not functioning and valid.

Trigger(s)

This is called on application server start, or setting page access and is used to validate that the custom provider is functional and working as expected. An example maybe to say check that the directory source is reachable. Most custom implementations will simply return Y\n.

Function: all-users

List all users on the network and their information (e.g. email address, office, department, …).

Program Call

[CustomUserProgram] - all-users

Example Program Call

MyCustomUserProgram.exe - all-users

Standard-input

N/A

Standard-output

username\tfullName\temailAddress\tdepartment\toffice\tcardNumber\n for each user.

Standard-error

Only on error. Return an error message [error message string/description]\n. An error may be an event such as the inability to contact the directory server.

Exit Code

Zero on success and non-zero on error (combine with error message on STDERR).

Trigger(s)

The command is called when PaperCut needs to list all system users. For example during a full network wide group sync. It many be called manually using Synchronize Now under the OptionsUser/Group Sync tab, or overnight as part of the automated sync.

Function: all-groups

List all user directory groups available.

Program Call

[CustomUserProgram] - all-groups

Example Program Call

MyCustomUserProgram.exe - all-groups

Standard-input

N/A

Standard-output

  • groupName\n for each group. The output must be UTF-8 encoded.

Standard-error

Only on error return on standard error an error message [error message string/description]\n.

Exit Code

Zero on success and non-zero on error (combine with error message on STDERR).

Trigger(s)

This command is called when PaperCut needs to list all groups on the network. Primarily it’s called when the system Administrator attempts to add groups to the Groups section so they can use this group for reporting or rules.

Function: get-user-details

List details about an individual user (e.g. email address, office, department, …).

Program Call

[CustomUserProgram] - get-user-details

Example Program Call

MyCustomUserProgram.exe - get-user-details

Standard-input

  • Single username\n

Standard-output

  • username\tfullName\temailAddress\tdepartment\toffice\tcardNumber\n for standard-input specified username. At a minimum username must be returned. The other fields are optional and may be left empty. The output must be UTF-8 encoded.

Standard-error

Only on error return on standard error an error message [error message string/description]\n.

Exit Code

Zero on success and non-zero on error (combine with error message on STDERR).

Trigger(s)

This command is called to fetch information about a single use. It’s called when a user is created in an individual operation (e.g. on first print) rather than a batch operation (e.g. a full user/group sync).

Function: group-member-names

List all members of a group. This command produces a list of usernames only. No user information is provided.

Program Call

[CustomUserProgram] - group-member-names [groupName]

Example Program Call

MyCustomUserProgram.exe - group-member-names “Engineering”

Standard-input

N/A

Standard-output

  • username\tfullName\temailAddress\tdepartment\toffice\tcardNumber\n for standard-input specified username. At a minimum username must be returned. The other fields are optional and may be left empty. The output must be UTF-8 encoded.

Standard-error

Only on error return on standard error an error message [error message string/description]\n. An error may include a event such as a call for a non-existent group.

Exit Code

Zero on success and non-zero on error (combine with error message on STDERR).

Trigger(s)

This command is called to list all members in a group. It’s called as part of a full user/group sync.

Function: group-members

This command is similar to Group-Member-Names, however it returns user information as well as the username.

Program Call

[CustomUserProgram] - group-members [groupName]

Example Program Call

MyCustomUserProgram.exe - group-members “Engineering”

Standard-input

  • N/A

Standard-output

  • username\tfullName\temailAddress\tdepartment\toffice\tcardNumber\n for standard-input specified username. At a minimum username must be returned. The other fields are optional and may be left empty. The output must be UTF-8 encoded.

Standard-error

Only on error return on standard error an error message [error message string/description]\n. An error may include a event such as a call for a non-existent group.

Exit Code

Zero on success and non-zero on error (combine with error message on STDERR).

Trigger(s)

This command is called if the administrator has selected a group as a sync source.

Function: is-user-in-group

Test to see if a user is in a given group.

Program Call

[CustomUserProgram] - is-user-in-group [groupName] [username]

Example Program Call

MyCustomUserProgram.exe - is-user-in-group “Engineering” “bobsmith”

Standard-input

  • N/A

Standard-output

  • Y\n when valid.
  • Or; N\n when invalid.

Standard-error

Only on error return on standard error an error message [error message string/description]\n. An error may include a event such as a call for a non-existent user.

Exit Code

Zero on success and non-zero on error (combine with error message on STDERR).

Trigger(s)

This command is called when a user is added to the system in an individual even such as a on-first-print event. The information is used to see if group based setup rules should apply to this user.

Custom auth program

Below is a table containing the different calls PaperCut will make to a configured Custom auth program as well as the valid and expected inputs and output. A custom authentication program is used to validate a user’s username and password.

Program Call

[CustomAuthProgram]

Example Program Call

MyCustomAuthProgram.exe

Standard-input

  • username\nplaintextPassword. The input must be UTF-8 encoded.

Standard-output

  • OK\n when authentication is successful.
  • Or; OK\nusername\n when authentication is successful. This is useful for removing diacritic marks from usernames. PaperCut will use the username returned instead.
  • Or; ERROR\n if the username and password is invalid, or a general error of any description occurs.

Standard-error

Only on error or invalid authentication return on standard error an error message [error message string/description]\n. In line with best security practice on authentication failure return “Invalid username or password\n”. Do not disclose the existing of a valid username or invalid password via independent messages.

Exit Code

The exit code should always be zero (0).

Trigger(s)

Program is called only when authentication of a user is required.

Synchronisation Workflow

The following is the order each step occurs in during a typical manual or overnight use synchronisation run.

  1. all-users or group-members (if syncing against a group)
  2. group-member-names called for each active group listed in PaperCut

Individual User Addition Workflow

The following is the order each step occurs during an event where are new user is added on demand (say on first print or first login).

  1. get-user-details called for the supplied user
  2. is-user-in-group called for the supplied user for each group defined in PaperCut

Notes

  • The working-directory of the program(s) when called is [install-path]\server\ (Eg: C:\Program Files (x86)\PaperCut MF\server\)
  • If groups are defined in [install-path]\server\data\conf\additional-groups.txt this will override the custom auth program and it will not be called for any groups defined in this file.
  • A sample Python script that shows a simple implementation for both custom user sync and custom authentication is available. Please note this is a simple example and is not indented for production use.

FAQ

Q If “Delete users that do not exist in the selected source” is disabled, what happens if User is missing from selected source? Is account disabled?

The account will be left and not deleted from PaperCut. To delete these accounts, run a sync with the delete option selected, or manually delete the user via the interface (or via server-command.exe).

Q What happens when “Enable internal users” is disabled?

Internal users is disabled by default. Internal users are mutually exclusive form the sync source and only exist in the PaperCut database. PaperCut will not call any workflow operations on any internal users if define.

Q Groups still must be added manually through “Add/Remove Groups”?

Yes. In many environments there are often thousands of groups in the user directory. Most are defined for purposes such as file permissions, etc. and are not relevant to printing. Each group added into PaperCut adds some sync overhead as users and groups are match up in the database. For this reason the administrators must select the groups appropriate for printing (e.g. rules, reports, filters, …). Automatically importing all groups would cause performance problems.

PaperCut would like thank Jarad for his contribution to this article.


keywords: userdir.exe, custom synchronization, user plugin,integration, technical integration

Comments

Share your findings and experience with other PaperCut users. Feel free to add comments and suggestions about this Knowledge Base article. Please don't use this for support requests.

Article last modified on November 10, 2017, at 12:05 AM
Printable View   |   Article History   |   Edit Article