Syncing users from Microsoft Entra ID

Syncing from Microsoft Entra ID (formerly Azure AD) allows your organization to automatically provision your users. It connects PaperCut Hive or Pocket to your Entra ID directory, ensuring your User list is always up to date and matches your source of truth.

This method can sync user details such as their full name, email address, and department. You can also sync associated user information, like access codes and access card numbers.

There are three options for syncing from Microsoft Entra ID:

• (Recommended) Via User and group sync in the admin console — a full-featured, API-based sync that allows adding and deleting users, mapping attributes, updating user data, and enabling the Groups functionality in PaperCut Hive and Pocket.
• Microsoft Entra ID User Sync Add-on (certified app) — the classic, SCIM-based add-on that allows adding and deleting users. Does not support groups.
• Custom Microsoft Entra ID User Sync Add-on — a custom, SCIM-based add-on that allows adding users (but not deleting users), and limited custom attribute mapping (access card and access code). Does not support groups.

Comparing the Microsoft Entra ID sync options

Since there are three potential ways to set up syncing from Microsoft Entra ID, which one is best for your organization? Let’s compare the features, benefits, and limitations of each choice.

For most organizations, User and Group Sync is the best choice — particularly because it allows Groups to be enabled in PaperCut Hive and Pocket. However, some long-term organizations already using the Add-on versions and organizations that specifically require SCIM provisioning might prefer to stay with the add-on versions.

Now it’s time to select your preferred sync option and learn how to set up a sync:

• Set up User and group sync for Microsoft Entra ID
• Set up the User Sync Add-on for Microsoft Entra ID (certified app version)
• Set up a custom User Sync Add-on for Microsoft Entra ID

Set up “User and group sync” for Microsoft Entra ID

Prerequisites

Before setting up User and group sync, check these related settings:

1. Check your PaperCut Hive or Pocket access code default format. New users without synced access code attributes will receive an access code according to this setting.
2. If you want to track costs-per-page or use features like quotas and restricting user accounts, enable Cost Tracking in PaperCut Hive or Pocket. Ensure you have set up at least one cost profile.
3. Check your authentication settings in PaperCut Hive or Pocket, and ensure that your users are able to log in. Note that syncing from an identity provider does not enable Single Sign-on or social login (OAuth) from the same identity provider. Authentication methods like these are enabled separately.
4. Also consider any other methods used to add users to PaperCut Hive and Pocket:
   • If you are using an existing user sync add-on for the same identity provider, the two syncs will sequentially overwrite each other. We strongly recommend only using User and group sync or a user sync add-on — not both.
   • If you are using an existing user sync add-on and want to change to User and group sync, first disconnect the user sync add-on. When the user sync add-on is disconnected, your users will remain in PaperCut Hive or Pocket.
   • If your organization previously used the Microsoft Entra ID user sync Add-on: before starting to use User and group sync, ensure that Email is a populated value for users in your identity provider. Review best practices before migrating.
   • Be aware that importing users (or user data) via the User data import tool (CSV or TSV file import) will do a one-time override of synced data. Subsequent syncs will overwrite user data where user attributes are mapped.
5. If necessary, complete any tidying of data in your identity provider tenant, for example, optionally creating a “Print Users” group, or ensuring users have correct group memberships of existing groups.

Identity provider attributes overview

Part of syncing an identity provider is mapping its attributes to PaperCut Hive or Pocket attributes. At a minimum, Email and Username must be mapped; all other attributes are optional.

If you don’t map the Access code attribute, PaperCut Hive or Pocket will auto-generate access codes for all new users and all existing users who don’t have an access code, then send a notification email to those users to let them know what their access code is.

If you store sensitive data, such as access card numbers and access codes, in another system, it can also be imported into PaperCut Hive or Pocket via the User data import tool (CSV).

Editing attributes — Microsoft Entra ID

• Scenario: By default, in a user’s profile, the Microsoft Entra ID “department” string is mapped to the PaperCut Hive and Pocket “Department” field, but you want to show the city where the user is based instead.
  Solution: In the Microsoft Entra ID properties (attributes) list, delete the “department” string, and instead add the “city” string.
• Advanced scenario: You have created custom fields (extensions) in Microsoft Entra ID to store specific types of user data.
  Solution: Map custom strings into the PaperCut Hive or Pocket sync configuration attribute mapping. Here’s what’s supported:

  • Extension attributes (on-premises extensions)
    Map the string onPremisesExtensionAttributes.extensionAttribute1
    (Note that the “1” in the example “extensionAttribute1” can be replaced by any value between 1 and 15.)

  • Directory extensions
    Map the string additionalData.<extensionName>
    (where <extensionName> is the unique name for the extension attribute returned as the “name” attribute in the Graph API response that created the extension)

  • Schema extensions
    Map the string additionalData.<schemaId>.<propertyName>
    (where <schemaId> is the unique identifier for the schema, returned in the response that created it, and <propertyName> is the name of the property in the schema you wish to use)

  • Open extensions
    Map the string extensions.<extensionID>.<propertyName>
    (where <extensionID> is the unique identifier for the extension, set in the request that created it, and <propertyName> is the name of the property in the extension you wish to use)

To find potential attributes, review the Microsoft Entra ID properties (attributes) list.

How to set up a “User and group sync” identity provider configuration

Each PaperCut Hive or Pocket organization can have up to five identity provider sync configurations. Here’s how to set up a sync configuration:

1. Log in to the PaperCut Hive or Pocket admin console. Ensure you are also an administrator with all the required permissions to your organization’s identity provider tenant.

2. In the left navigation bar, select Settings. The Settings page is displayed.

3. Select the User and group sync tab. The User and group sync page is displayed.

4. Select Add sync configuration. The Select identity provider popup is displayed.

5. Select Microsoft Entra ID. The Add sync configuration page is displayed.

6. Select Authorize connection. A popup is displayed.

7. Select Continue, then follow the prompts to authorize the connection between your identity provider tenant and PaperCut Hive or Pocket. After authorization has finished you’ll see a success message on the Add sync configuration page.

8. In the Name field, enter a name for this identity provider configuration. This name is used to recognize the identity configuration in PaperCut Hive or Pocket, and is especially helpful if you have multiple sync configurations.

9. In User source, select which users to sync into PaperCut Hive or Pocket:

   • Sync all users: every user in your connected identity provider is synced.

   • Only sync users from specific groups/administrative units: allows you to sync multiple, large groups and/or administrative units of users (for example, “All print users”, “All staff”, or “All students”). Select the group(s) or administrative unit(s) from the Groups and administrative units dropdown.

10. In Suspended user accounts, select whether or not you want users with suspended/disabled accounts in Microsoft Entra ID to be included during a sync (that is, synced into PaperCut Hive or Pocket). Note that users with suspended/disabled accounts who are synced into PaperCut Hive or Pocket can’t log in, or use functions such as printing — but they still appear in your Users page.

11. In User attribute mapping, select Edit attribute mapping. The attribute mapping popup is displayed.

12. Review the Microsoft Entra ID attribute column, and enter, edit, or delete attributes in the fields. Use the attribute strings from your identity provider tenant to add or edit these user data types into PaperCut Hive or Pocket during a sync. Select Apply to return to the main sync configuration editor.

    

13. In Email invitation for new users, select an invitation setting for any new users that are created during a sync:

    • Don’t send invitation emails automatically (for example, invite later)
    • Email a link to the User Portal (user self-service)
    • Email a classic invitation (no log in, for example, for guests)

14. In Sync frequency, select how and how often PaperCut Hive or Pocket will sync with your identity provider.

    • Manual: No automatic or scheduled syncing occurs. Syncs must be initiated in the admin console > User and group sync > Sync now.

    • Scheduled: PaperCut Hive or Pocket will sync with your identity provider on a regular schedule. Use the Frequency drop-down to select Weekly or Monthly.

15. Select Save. Your sync configuration is now displayed on the User and group sync page.

16. If you want to immediately start the sync, select Sync now.

You can then check Logs > Activity Log for entries related to a sync.

Set up the User Sync Add-on for Microsoft Entra ID (certified app version)

To set up the User Sync Add-on for Microsoft Entra ID:

1. Log in to the admin console.
2. Select Add-ons > User management > Microsoft Entra ID User Sync.
3. Follow the steps to complete setup.

Set up a custom User Sync Add-on for Microsoft Entra ID

Step 1. Enable the Microsoft Entra ID User Sync add-on

1. In the PaperCut Hive admin interface, click Add-ons. Locate the Microsoft Entra ID User Sync add-on and click Add.

2. Agree to the terms. The instructions panel displayed.

3. Make a note your Tenant URL and Secret Token. You'll need these details later to connect your custom Microsoft Entra ID Enterprise Application.
   
   Ignore the other information, including the step-by-step tutorial.

Step 2. Create application

1. Navigate to the Microsoft Entra admin center.

2. If you have an existing Enterprise Application configuration to synchronize users with PaperCut Hive or Pocket, switch off provisioning for this application.
   a. Go to Enterprise Applications and select the application.
   b. In the Provisioning section, toggle Provisioning Status to Off.

3. On the Microsoft Entra ID admin center homepage, click Add > Enterprise Application.
   

   

4. Click Create your own application.
   

   

5. Name your application, for example, PaperCut-Hive-User-Sync.

6. Make sure that Integrate any other application you don't find in the gallery (Non-gallery) is selected.

7. Click Create.
   

   

Step 3. Configure provisioning

1. From the left-hand menu, select the Provisioning tab.
   

   

2. Under Manage, click Provisioning.

3. Set Provisioning Mode to Automatic.
   

   

4. In the Admin Credentials section, paste your PaperCut Cloud Management Tenant URL and Secret Token you noted earlier.

5. Click Test Connection and ensure Microsoft Entra ID can connect to PaperCut Hive or Pocket. If the connection fails, ensure you've entered the correct Tenant URL and Secret Token and try again.
   

   

6. Click Save.

7. Click the Settings dropdown.

8. Select the Send an email notification when a failure occurs checkbox.

9. In the Notification Email field, type the email address of a person or group who should receive the provisioning error notifications.
   

   

10. Click Save.

Step 4. Configure Attribute Mappings

1. In the Mappings section, select Provision Microsoft Entra ID Users.
   

   

2. In the Attribute Mappings section, the second column shows the user attributes synchronized from Microsft Entra ID into PaperCut Hive or Pocket. Delete all attributes except:
   userName
   displayName
   emails[type eq “work”].value
   

   The attributes selected as matching properties are used to match the user accounts in PaperCut Hive or Pocket for update operations.
   
   If you change the matching target attribute, ensure that the PaperCut Hive or Pocket API supports filtering users based on that attribute.
   

   

A downside of having the Delete option enabled is that users might need to reauthenticate with PaperCut Hive or Pocket if accidental misconfiguration occurs in Microsoft Entra ID. For example, if users are taken out of scope for syncing, they will be deleted from PaperCut Hive or Pocket. This renders their authentication token invalid, so when they are re-added they must relink the software as they are treated as a new user.

Step 5. Configure access card and/or access code syncing

1. Under Attribute Mappings select Show advanced options, then click Edit attribute list for customappsso.
   

   

2. At the bottom of the list of attributes, add one or both of the following two new attributes (depending on your requirements). Leave all options as default.
   urn:ietf:params:scim:schemas:extension:papercut:2.0:User:accessCard

   urn:ietf:params:scim:schemas:extension:papercut:2.0:User:accessCode
   

   

3. At the top of the list, click Save. The Attribute Mapping screen is displayed.

4. Under the list of Microsoft Entra ID Mappings, click Add New Mapping. The Edit Attribute screen is displayed.
   

   

5. To sync the Access Card attribute:

   1. In the Source attribute field, select the attribute that will be read from the source object.

   2. In the Target field, select:
      urn:ietf:params:scim:schemas:extension:papercut:2.0:User:accessCard

   3. Leave the remaining fields set to the default.

   4. Click OK.

6. To sync the Access Code attribute:

   1. In the Source attribute field, select the attribute that will be read from the source object.

   2. In the Target field, select:
      urn:ietf:params:scim:schemas:extension:papercut:2.0:User:accessCode

   3. Leave the remaining fields set to the default.

   4. Click OK.

7. Click Save.

Example
This example adds mappings from the employeeId and extensionAttribute10, but these could be any fields where you store the information you want to sync.

Optional

Configure scoping filters according to the instructions in the Scoping Filter tutorial.

Step 6. Add users and groups

1. In the breadcrumbs at the top of the screen, click Provisioning. The Provisioning screen is displayed.

2. In the left-hand menu, click Users and Groups.

3. Click on Add user/group, select who should be assigned this application, and therefore be synced into PaperCut Hive or Pocket.

4. Click Assign. You will be returned to the Users and Groups view, where you can validate your selection.

5. Click Provisioning in the left-hand menu.

6. Scroll to the Settings section at the bottom of the screen and select Sync only assigned users and groups.
   

   

7. Set Provisioning Status to On to enable the Microsoft Entra ID provisioning service for PaperCut Hive or Pocket.
   

   

8. When you are ready to provision, click the Save at the top of the screen.

9. The setup is now complete. To confirm success, check if the users are synced into the PaperCut Hive or Pocket admin console.

Migrating from a user sync Add-on to User and group sync

It is possible to change from a user sync Add-on to User and group sync.

If you’ve previously used a Microsoft Entra ID user sync Add-on, be aware that there are some slight differences in how PaperCut Hive and Pocket Microsoft Entra ID user sync Add-on and User and group sync handle the Email field in Attribute Mapping.

Before changing to User and group sync, check if the following scenarios apply.

Scenario one: email value populated in Microsoft Entra ID

1. The organization’s users have values in the Email field.
2. The organization starts using the Microsoft Entra ID user sync Add-on.
3. The organization changes to User and group sync.

Outcome: Because your users were previously synced into PaperCut Hive or Pocket with an email attribute, the users successfully continue syncing.

Scenario two: email value not populated in Microsoft Entra ID

1. The organization’s users do not have values in the Email field.
2. The organization starts using the Microsoft Entra ID user sync Add-on. Because the users lack a value for Email, the Add-on automatically applies the userPrincipalName value to the Email attribute in PaperCut Hive or Pocket.
3. The organization changes to User and group sync.

Outcome:

• Existing users previously synced via the Microsoft Entra ID user sync Add-on will successfully sync via User and group sync with warnings. To avoid these warnings in future syncs, add data to the users’ Email attribute in Microsoft Entra ID.
• Any new users can’t be synced unless they have data in their Email attribute in Microsoft Entra ID. Ensure that these users have data in Email, then try syncing again.

How to prepare to migrate from the Microsoft Entra ID user sync Add-on to User and group sync

To ensure a successful migration from the Microsoft Entra ID user sync Add-on to User and group sync, for any existing users previously synced via Add-on:

• If these users were synced without Email in Microsoft Entra ID, userPrincipalName was automatically applied as their email in PaperCut Hive or Pocket. After User and group sync is configured, these users will sync with warnings. To avoid these warnings in future syncs, add userPrincipalName to the users’ Email attribute in Microsoft Entra ID.
• If these users were synced with Email in Microsoft Entra ID, their emails were applied as their email in PaperCut Hive or Pocket. After User and group sync is configured, no changes are required (Email and userPrincipalName do not need to match), and these users will continue to sync.

Note that when setting up a sync configuration in User and group sync, you must review the Attribute mapping, and make any necessary changes.