Preparing to use UPN usernames with PaperCut when synching with the standard Azure AD sync method

AVAILABLE TO CUSTOMERS ON:

If you’re looking to use (or migrate your users to) the standard Azure AD sync option (sometimes referred to as ‘Microsoft Graph API’), it’s worth looking through these preparation steps before making the leap.

Using Azure AD sync involves migrating from usernames being sAMAccountNames (or MailNickNames) to usernames being UPNs. Even if you’re setting up a brand new environment using Azure AD as the sync source, this checklist will help you prepare for a successful deployment.

Why do UPNs matter?

If you are currently using the Windows Active Directory sync, or LDAP Sync, or even the Azure AD Secure LDAP Sync, you’ll notice that the usernames synced into PaperCut are the sAMAccountNames (alex.wallaby).

When you move to the standard Azure AD sync method, PaperCut will sync the UPN (alex.wallaby@papercut.com) as the username in PaperCut. This can have downstream effects such as how users log into the clients, or how print jobs are correctly matched with PaperCut users.

This guide helps sys admins planning to use UPNs as usernames, and helps ensure that there aren’t any surprises!

The step-by-step guide to UPN success:

• Step 1 - Review the FAQs and feature comparison of the sync methods
• Step 2 - Set up a test environment
• Step 3 - Confirm how print job ownership works in your environment
• Step 4 - Take a system backup
• Step 5 (Optional) - Set the Card number sync config key
• Step 6 - Rename your users in PaperCut
• Step 7 - Switch to the standard Azure AD sync method, and sync for the first time
• FAQs

Step 1 - Review the FAQs and feature comparison of the sync methods

Step 2 - Set up a test environment

It’s always worth testing large changes like this in a test environment. Install PaperCut NG or MF on a dedicated test server to try it out. The test install will use the 40-day trial by default, so you won’t have to purchase any extra licenses.

In your test environment you can then set up standard Azure AD sync, check that the sync is working as expected, and also test printing. This might be from workstations to the server print queues, or through Mobility Print or Print Deploy (ideally test whichever deployment and print methods you’ll be using in production).

If you’d like to test using your real ‘production data’ (including migrating your users etc) then it’s worth reviewing the Setting up a test environment KB. Ensure that your test server is on a separate network if possible, so that you can load your production database and perform a trial-run of renaming your users and a test sync.

What if I don’t perform testing?

We highly recommend trying all of this out in a test environment, but if you’re confident in the steps and checks below, we do highly recommend performing a database backup before performing a sync.

Step 3 - Confirm how print job ownership works in your environment

It’s important at this point to plan ahead to confirm how PaperCut will match the print jobs coming into the print system, with the PaperCut users that you’ve imported through the standard Azure AD sync.

Print jobs could appear with either the UPN or the sAMAccountName as the job owner (or something else!). This will depend on which print method you’re using (e.g. workstation > server or using Mobility Print, or deploying through Print Deploy etc.) and also whether your workstations are domain-joined to Azure AD. PaperCut will need to be able to match this job owner with the PaperCut username.

Note that this is also a good test to perform in your test environment, especially if you’re binding workstations to Azure AD for the first time as part of the wider migration to Azure AD.

As this illustration shows, if a job comes in as alex.wallaby, but the PaperCut username is the UPN (alex.wallaby@papercut.com), there won’t be a match.

To resolve this, you can either look in the PaperCut admin interface (in the Logs > Job Log, or in Logs > Application Log if jobs are getting denied) or better yet, in the Windows Print Queue, to identify the OS-level owner of the print job:

You’ll then need to select the best method to match that owner username with the usernames in PaperCut (UPN):

If the job owner is the UPN:

If the job owner is showing as the UPN (e.g. alex.wallaby@papercut.com), then you win! You’re already ready for UPN support. PaperCut will match the UPN of the print job owner, with the UPN username in PaperCut.

If the job owner is the sAMAccountName:

If the job owner is showing as alex.wallaby but the PaperCut username is alex.wallaby@papercut.com, options include:

• In the print provider config, set the UPNSuffix= key to e.g. UPNSuffix=papercut.com (this will only work if you have a single domain printing through any particular Print Provider).
• Enable username aliasing for the users in PaperCut
  • With PaperCut MF/NG version 22.0.9 or later you can sync aliases with Azure AD.
  • With PaperCut MF/NG version 22.0.8 or earlier, aliases are not able to be sync’d from Azure. Instead, you would need to bulk-update aliases periodically - as a result this method requires more overhead.

If the job owner is showing as something else:

If the job owner is showing as something else (or if you just prefer these to the methods above), options include:

• Use Mobility Print (users will log in to the Mobility Print client or app with UPN/password) to authenticate with PaperCut.
• Use the PaperCut User Client (using the ‘unauthenticated printer / print queues’ method), allowing users to use UPN/password to authenticate to PaperCut.
• Use Print Deploy in PROMPT mode (allowing users to authenticate with UPN/password), and if using server print queues, mix with one of the methods above, or switch to deploying Mobility Print queues.
• You could also use a combination of either user aliases or normalizing usernames (especially useful if you’re seeing the username in the format of AzureAD\alex.wallaby@papercut.com) depending on your environment.

What if I don’t confirm the job ownership of print jobs in my environment?

You may see that user’s print jobs are denied if the job is owned by the user in the format of sAMAccountName, which PaperCut is trying to match to the PaperCut username in UPN format.

Step 4 - Take a system backup

There’s no ‘going back’ if something unexpected happens during the initial sync with Azure AD, so we highly recommend performing a database backup before proceeding!

What if I don’t take a backup?

There can be instances (if the steps below are missed) where you may land up with duplicate users. You will be able to recover from this using server commands and batch scripts, but it’s a lot safer (and quicker!) to be able to return to a backup taken prior to the migration.

Step 5 (Optional) - Set the Card number sync config key

(Optional) If your organization uses card numbers, set the config key user-source.update-user-details-card-id to Y.

1. Head into the config editor through the PaperCut admin interface > Options > Actions > Config Editor.
2. Search for the key above, update the value to Y.
3. Click Update.

If you’re wanting to sync Card numbers/IDs from Azure AD into PaperCut (so that users can use card readers to log into devices or release stations), the EmployeeID field from Azure will be sync’d into the Primary Card Number field in PaperCut - if this key is set to ‘Y’.

What if I don’t set this key?

Card numbers will not be synced into PaperCut, however setting this key later, and performing another sync will then pull the EmployeeID field into PaperCut as the primary card number.

Step 6 - Rename your users in PaperCut

Note: If you’re using the ‘Azure AD’ sync source for the first time and you don’t have any users to migrate, you can skip this step!

As documented on the Overview of syncing user and group details with Azure AD page, with the standard Azure AD sync, users are synced into PaperCut using their UPN.

If you’re currently using a sync source that pulls the users from your directory into PaperCut with e.g. the sAMAccountName as the username, we highly recommend renaming all your users to the UPN format prior to the first sync.

• Use the Renaming User Accounts process to rename all your users from e.g. alex.wallaby to the UPN alex.wallaby@papercut.com
• (Optional) You can also use this step to enable username aliasing, and bulk-update your users with the sAMAccountName as the alias - if you’ve determined that you need to do this for backwards-compatibility temporarily (see Step 3 above).

What if I don’t rename my users?

When using the standard Azure AD sync method for the first time, and users already in PaperCut are re-synced from the new Azure AD source, one of two things could happen:

• If the user exists in PaperCut as the sAMAccountName e.g. alex.wallaby AND they do have their UPN listed as their email address or username alias (e.g. alex.wallaby@papercut.com), PaperCut will sync that user and retain the sAMAccountName (alex.wallaby) as their username.
• If the user exists in PaperCut as the sAMAccountName e.g. alex.wallaby AND they do not have their UPN listed as their email address or username alias, PaperCut will sync the ‘new user’ as alex.wallaby@papercut.com, and their original alex.wallaby user record will also remain - leading to duplicate users in your user list.

Furthermore, when subsequent users are added to Azure AD (and they do not already exist in PaperCut), PaperCut will sync the new user into PaperCut using their UPN e.g. alex.wallaby@papercut.com. This is only an issue if all of the users so far existed in PaperCut with their UPN as their email (see the first case from above) which means that 99% of your users are now listed with sAMAccountName as the username and any new users added will appear as the UPN.

Ultimately this could then cause issues with matching logins and job owners with the PaperCut username (see Step 3 above).

Step 7 - Switch to the standard Azure AD sync method, and sync for the first time

Once you’ve run through the steps above, and you’ve taken a backup, you’re ready to enable the standard Azure AD sync method, and synchronize your users.

Important Note 1: When you use the standard Azure AD sync, On demand user creation will be disabled by default. This is to avoid duplicate users being created accidentally in your PaperCut user list.

Important Note 2: If you do have MFA / 2FA enabled in your Azure AD tenancy - now is the time to ensure that your security policy within the MS tenancy does not enforce 2FA on the PaperCut app (note that this doesn’t mean that you have to disable 2FA globally). User/password authentication through PaperCut with Azure AD does not currently support 2FA.

See the section below for more information on MFA/2FA.

More about MFA/2FA requirements

PaperCut does not currently support MFA with Azure AD. However, this does not mean that you have to disable MFA globally.

Microsoft has a lot of documentation on Azure AD multi-factor authentication, which is worth a read. However, the method that you’ll need to use to bypass MFA for PaperCut will depend on your subscription level or ‘edition’ of your Microsoft AD tenancy. Any security policies you have set up for your tenancy will also factor in to your decision making.

There’s a couple of different ways to bypass MFA when using PaperCut for Azure AD sync:

Trusted IP addresses

You may be able to make use of Trusted IPs if your Azure tenancy provision allows it (see the Microsoft documentation link for more information on which tenancy editions have access to this configuration).

You will want to use the PaperCut App Server IP address for your trusted IP address (not the client IP addresses). From an Azure AD point of view, it’s the PaperCut Application Server hostname/IP address that is authenticating the users, and therefore it is the PaperCut Application Server IP address that must be trusted (or excluded from MFA policies).

Conditional access policies

If you have the ability to use conditional access rules (as detailed in the Microsoft documentation) - then one option is to keep MFA enabled for all user logins from all devices and platforms - and then exclude the PaperCut app from the MFA policy.

Organisations may already have multiple policies set up with different ‘signals’ (basically rules like IP address or location or device type etc). Examples include not applying a certain policy for someone logging in from a secure Lab, vs applying a policy for everyone using web access - or policies based on user location or application. It’s that last example that we’re interested in - applying policies (in our case excluding an application from the MFA policy) based on Application or IP address.

This article has a walk through example of someone enabling a specific MFA policy for an app. So, depending on what policies you have in place already, you’d want to apply logic that excludes the PaperCut App (or the PaperCut Application Server IP address) from the MFA policy. Setting that up effectively bypasses MFA for anyone using the PaperCut app (or App Server IP address) to authenticate. This is somewhat fuzzy, since you will know what policies you have in place already - you wouldn’t want to create a brand new policy if it’s going to conflict with another policy that you’ve already set up in your environment, but there may be a current policy that you can edit instead.

Errors relating to MFA/2FA authentication

See the known issue for more information on errors AADSTS50079 and AADSTS50079, related to using 2FA/MFA scenario with Azure AD standard sync. If you’re receiving these errors, then it means that MFA has been applied to the PaperCut Application Server / PaperCut app, so authentication will fail.

FAQs

When you switch to using the standard Azure AD sync, this key will be automatically set to Y.

Note: when using the standard Azure AD method, this key will not alter the sync behavior or the type of PaperCut username created. The sync will always populate the UPN as the PaperCut username.

When matching usernames of logins or print jobs, PaperCut will retain the full UPN (it will not truncate the username to a sAMAccountName), when the key is set to Y. If this key is incorrectly set to N, PaperCut will trim off the domain from any usernames attempting to log in, or from any job owner usernames. For example if a user is trying to log in as alex.wallaby@papercut.com, the username will be truncated to alex.wallaby and the login may fail since it doesn’t match the UPN in PaperCut. This could result in users complaining that they’re unable to log into their PaperCut client (e.g. Mobility Print / web interface / Print Deploy / User client).

In addition, any print jobs being sent to server queues may have the domain stripped from the username, resulting in denied print jobs or ‘missing print jobs’ if PaperCut cannot match the job owner name with the PaperCut username (the UPN).