Syncing users from Okta

Syncing from Okta via User and group sync allows your organization to automatically provision your users. It connects PaperCut Hive or Pocket to your Okta directory via API, ensuring your User list is always up to date and matches your source of truth. Learn more about User and group sync.

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.

After your sync configuration is set up, you can also use the Groups feature to manage your users.

Set up “User and group sync” for Okta

Prerequisites

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

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.
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.
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.
Also consider any other methods used to add users to PaperCut Hive and 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.
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 — Okta

There are two versions of attributes in the Okta user profile: the initial label is the display name, and the version underneath is the variable name. PaperCut Hive and Pocket only accept the variable version of the label/name.

String-based custom attributes are also able to be mapped. Other types of custom attributes, such as array-based custom attributes, are not currently supported.

Blank, edited, and deleted user attributes - Okta

The user attributes you have configured in PaperCut Hive or Pocket are synced during a sync.

If a user attribute is blank, on sync, any user data in the matching field in PaperCut Hive or Pocket is not changed. No new data is imported.
If a user attribute is changed in PaperCut Hive or Pocket, any user data linked to that attribute will be imported into the PaperCut Hive or Pocket user profile for users during the next sync.
If a user attribute is deleted, it will not sync again. No changes are made to existing user data.

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:

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.
In the left navigation bar, select Settings. The Settings page is displayed.
Select the User and group sync tab. The User and group sync page is displayed.

Tip

If you're opening this page for the first time, you'll see the “Before you sync…” information. Ensure you review the related features and make any required changes.
Select Add sync configuration. The Select identity provider popup is displayed.
Select Okta. The Add sync configuration page is displayed.
Select Authorize connection. A popup is displayed containing required permissions to connect Okta and PaperCut Hive or Pocket:
1. Read existing users’ profiles and credentials (okta.users.read): Required to import user accounts. Without this, users cannot authenticate at physical printers to securely release print jobs. We use this data to create PaperCut user profiles for authentication and printing.
2. Read about groups and their members (okta.groups.read): Required to import group names & memberships. Admins use this synced data to automate access control and assign specific print policies (e.g., enabling color printing only for the “Accountant” group).
Review the required permissions, then select Continue. The Authorize connection pop-up is displayed.
Select PaperCut Hive Okta integration. A new browser tab opens, containing the PaperCut Hive and Pocket directory sync integration with Okta.
1. In the PaperCut Hive and Pocket directory sync integration page, select Add this integration, then sign in as an Okta administrator.
  
  Warning
  
  Ensure the authorized account has all the required administrator access to your identity provider tenant. Lower-level accounts can't authorize the connection between an identity provider and PaperCut Hive or Pocket.
2. Review the required scopes, then select Install & Authorize to connect PaperCut Hive or Pocket with Okta via the PaperCut Hive and Pocket directory sync integration.
3. Copy your client secret from the PaperCut Hive and Pocket directory sync integration, wthen return to your PaperCut Hive or Pocket sync configuration. Paste the client secret into the Client secret field in the sync configuration.
4. Copy your Okta Domain from the PaperCut Hive and Pocket directory sync integration, then return to your PaperCut Hive or Pocket sync configuration. Paste the Okta Domain into the Okta domain field in the sync configuration.
5. Copy your Client ID from the PaperCut Hive and Pocket directory sync integration, then return to your PaperCut Hive or Pocket sync configuration. Paste the Client ID into the Client ID field in the sync configuration.
6. Select Authorize connection 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 in PaperCut Hive or Pocket.
  
  Note
  
  You can't revoke authorization of an Identity Provider within the PaperCut Hive or Pocket admin console. If you need to revoke authorization, please revoke it from within your Identity Provider tenant.
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.
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: allows you to sync multiple, large groups of users (for example, “All print users”, “All staff”, or “All students”). Select the group(s) from the Groups dropdown.
  
  Tip
  
  Try to only select large groups of users. Selecting lower-level or smaller groups increases the likelihood that the same user is synced multiple times. There is no need to select fine-grained groups for policy and permission management at this stage.
  Note
  Identity provider groups are used in two separate ways in two separate places in PaperCut Hive and Pocket:
  - In Sync configuration > User source, groups are used to decide which users/data enter PaperCut Hive or Pocket via sync.
  - In Groups > Add group, groups are used to bulk manage policies and permissions for users based on their group membership in your identity provider.
  You don't need to use the same groups in both places. Most organizations use 1 to 3 groups as user sources (for example, “All staff” and “All students”), and might use additional, more fine-grained groups for policy and permission management (for example, “Year 8”, “Year 9”, etc.).
In Suspended user accounts, select whether or not you want users with suspended/disabled accounts in Okta 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.
In User attribute mapping, select Edit attribute mapping. The attribute mapping popup is displayed.
Review the Okta 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.
1. In the Test attribute mapping > Email field, enter a test email, then select Preview. Review the results in the Preview column to check that the displayed user data matches your expectations. Make any amendments and re-test as necessary. Common warnings to troubleshoot and notes include:
  1. No user data found: there is no associated data for this user.
  2. Unable to preview: the user does not have this custom attribute populated in their IDP or the custom attribute string is incorrect.
  3. Ignored: attribute not mapped, and will be skipped during a sync.
  4. Auto-generated: on sync, an access code will be auto-generated for this user. This may be because, for example, the attribute is not mapped, or a valid access code string is not mapped.
  5. Required data not found: no user data exists for a required attribute. Users without required attribute will be skipped during sync.
2. Select Apply to return to the main sync configuration editor.
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)
Users are notified of access code updates

Whenever a user's access code is updated, including via a sync, the user is notified via email. The email type is controlled by the setting in Email Print & Scan > User Invites > Default manual invitation email.
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.
  
  Note
  
  At any time, you can immediately sync PaperCut Hive or Pocket with your identity provider. On the User and Group sync page, simply select Sync now for the configuration you want to sync.
Select Save. Your sync configuration is now displayed on the User and group sync page.
If you want to immediately start the sync, select Sync now.
Note
- Syncs can take a while to process. To find out if a sync has finished, go to Logs > Activity Log and locate the log entry related to the sync. This also includes any related information (for example, errors).
- New users added during a sync will receive email invitations — either the classic email invitation or the User Portal invitation, (as per your organization’s setting in Easy Print & Scan > User Invites > Automatic invitation email).
- If you've chosen not to send invitation emails, ensure your users are invited later.

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

Edit or delete a User and group sync configuration for Okta

Refer to the main procedural guides for these tasks:

Frequently asked questions

Can I sync groups from Okta?

You can sync groups from Okta into PaperCut Hive or Pocket by setting up an Okta sync configuration in User and group sync, then setting up Groups.

Learn how to manage Groups in PaperCut Hive and Pocket

Can I sync from Okta and another identity provider service at the same time?

Yes, you can have up to five sync configurations and a mixture of identity providers.

How often does PaperCut Hive or Pocket sync with my identity provider? When does the syncing start?

As part of setting up User and group sync in PaperCut Hive and Pocket, you’ll select whether you want to sync manually (ad hoc, on demand, when you press the Sync now button in the admin console) or whether you want to automatically sync on a weekly or monthly schedule.

The sync will start at the next time the schedule is triggered.

To immediately sync your sync configuration, you can always Sync now.

User restrictions and balances aren’t synced attributes, and I’m migrating from PaperCut NG/MF. How do I get these into PaperCut Hive or Pocket?

To import existing balances and restricted status against your migrated users:

Set up User and group sync, and complete a sync.
Use the Import user data (CSV) tool to export the user list from PaperCut NG/MF.
Re-import the CSV/TSV file containing the email, balance, and restricted status columns into PaperCut Hive or Pocket.

What happens if an error prevents PaperCut Hive or Pocket from synchronizing with my identity provider?

When a sync can't start due to an error, no changes are made to the PaperCut Hive or Pocket organization. In this situation, check the Activity Log for an error message.

If a sync fails partway through, PaperCut Hive or Pocket will attempt to process as much information as possible. Some information may not be available to process. Check the Activity Log for an error message and try re-syncing later.

If a sync fails or partially fails due to data errors (for example, multiple users with the same access code), go to the Activity Log and download the report. Review any errors in the report, amend the data in the identity provider, and sync again.

Does User and group sync support just-in-time provisioning (on demand provisioning)?

No. We may consider this in the future.

How can I test User and group sync?

Set up a User and group sync configuration with:
User source: a test group with test users in it that do not already exist in your PaperCut Hive or Pocket Users list
Sync frequency: manual.
Select Sync now.
After the sync completes, check the Activity Log for a report, and check how the users were imported into your PaperCut Hive or Pocket organization.
When you're ready, you can change your User source to your real users, and change your Sync frequency if desired.

If you need tips and assistance, contact your Accredited Reseller for support.

If a sync fails, where do I find error messages?

If a sync fails, you can view the details in Logs > Activity Log.

How do I delete users during a sync?

If you deleted users in your connected identity provider, and want those users deleted from your PaperCut Hive or Pocket Users list, perform a manual sync and choose to delete these users. Be careful — after this data has been deleted, it can't be recovered.

To perform a manual destructive sync:

In the admin console, go to Settings > User and group sync and locate the correct sync configuration.
Select Sync now.
In If users are deleted in the synced user source: select Delete the users in PaperCut Hive (or Pocket).
Select Start sync.

Here are some common scenarios of deleting users and/or groups, either in the IdP and/or in PaperCut Hive or Pocket:

Identity provider source	Selection in sync configuration User source	Change and outcome
Some users are deleted	All users	If users are deleted in the identity provider source, they will be deleted in PaperCut Hive or Pocket on a destructive sync.
Some teachers are deleted	Teachers	If users are deleted in "Teachers" in the identity provider, on next destructive sync, those same users will be deleted in PaperCut Hive or Pocket.
Teachers; Students	Teachers; Students	If "Teachers" is removed as a sync configuration User source, on next sync, all users only associated with "Teachers" are deleted in PaperCut Hive or Pocket.
All staff; Teachers; Students	All staff; Teachers; Students	If "Teachers" is removed as a sync configuration User source, on next destructive sync, no changes are made to the PaperCut Hive or Pocket user list. This is because members of the "Teachers" group are also members of "All staff". They are still included in a user source.

What happens to suspended/disabled and other account statuses in my identity provider?

If your sync configuration's connected identity provider User Source includes suspended or disabled accounts, they are synced into PaperCut Hive or Pocket in a suspended state. This means that they can't access MFD functions like printing and copying, and they also can't log in.

Here are the specific treatments of Okta user statuses by PaperCut Hive and Pocket during a sync:

Staged/deprovisioned: not included in a sync.
Suspended: synced as suspended users.
Active/Provisioned/Password expired/Locked out/Recovery: synced as active users.

Comments

Comments are not available in this preview environment. On papercut.com, this space shows the live Disqus comment thread for this page.