Troubleshooting Email to Print issues when using IMAP OAuth for Microsoft 365, Office 365, Outlook.com

What’s this about?

In version 22.0.1 of PaperCut MF and NG, we introduced the ability to configure Email to Print with an O/M365 mailbox over IMAP using OAuth. This was necessary because basic (username and password) authentication is to be disabled for these accounts as of October 1st, 2022.


Generally speaking, what does the process of configuring this involve?

Glad you asked! It should go something like this:

  1. Create an App registration in your Azure tenancy.
  2. Fill out the Host, Username, Application (client) Id, and Directory (tenant) Id in the PaperCut admin web interface, and click Apply.
  3. The status box will present you with a device code. You will then open a new tab in your browser, navigate to https://microsoft.com/devicelogin, enter the code, and authenticate yourself.
  4. You can then return to the PaperCut admin web interface and wait until the status changes to OK.



When attempting to configure Email to Print with this new option, there are some common questions you might have, and errors you might encounter. We’ve done our best to list them below, and how you can resolve them!

Note 💡 If you encounter any of the problems listed in this article, and you attempt to fix them with the resolutions provided, you may need to completely disable Email to Print in PaperCut, click Apply, restart the PaperCut Application Server service, and start the configuration again from the beginning in order to proceed.

When I make an App registration in the Azure portal, do I need to configure a Redirect URI, API Permissions, or generate a client secret at all?

You do not need to configure a Redirect URI, or generate a client secret. All that’s explicitly required is that you Allow public client flows in your App registration in the Azure portal, in Manage > Authentication > Advanced settings:

There is a possibility you might need to add some API Permissions manually (in Manage > API Permissions), depending on how your tenant/mailbox account is configured, but we’ll touch more on that a little later!

Those instructions from Microsoft on creating an App registration seem complicated, can you simplify it for me?

Sure thing!

  1. Login to the Azure portal as a global admin of your tenancy.
  2. Navigate to App registrations using the search bar at the top of the page.
  3. Click + New registration at the top of the page, and enter an appropriate name that will help you remember what this app is for.
  4. Choose an option for the Supported account types. For the majority of installations this will be Accounts in this organizational directory only.
  5. Leave the Redirect URI blank; we do not need to configure one for this functionality to work.
  6. Click Register at the bottom of the page, then navigate to Manage > Authentication > Advanced settings - ensure Allow public client flows is enabled, and click Save.
  7. Finally, head to the Overview section by clicking the link towards the top left-hand corner of the page, and copy down the Application (client) ID and Directory (tenant) ID from the top of the page; these are the two values you will need to enter into the PaperCut admin web interface when configuring Email to Print.

Is there anything else I should check in Azure before I start configuring Email to Print in the PaperCut admin web interface?

Yes! Obviously you’ll need an account in your tenancy which has a mailbox. This account will also need to have IMAP enabled. You can check this by logging into https://admin.microsoft.com as a global admin of your tenancy, and then navigating to Users > Active users and clicking on the user account you wish to use for Email to Print. From the menu on the right-hand side, in the Licenses and apps tab, make sure the account is configured with a mailbox (exactly what the license will be called will depend on your subscription). Then in the Mail tab, under Email apps, click Manage email apps and ensure IMAP is ticked:

I don’t want to enable IMAP; can I configure Email to Print with OAuth without using IMAP?

Nope; IMAP is the only protocol we can use to download mail from a mailbox in this instance.

I have Okta, or another identity provider, and we use federated accounts. Can I use one of these accounts for my mailbox?

Potentially! We’ve seen this work fine for some customer, but cause problems for others. If you’re having issues, and none of the other advice on this page has worked, please raise a request through our support portal and let us know so we can try to troubleshoot.

Okay, I’ve created my App registration, ensured my mailbox is setup correctly, and entered all the relevant details into the PaperCut admin web interface. The status box is telling me to wait, but I’ve been waiting a while now and nothing is happening. If I click Refresh, the IDs I entered become blank. What gives?

The first thing that’s worth doing is ensuring that your PaperCut Application Server can access the following endpoint on port 443:

https://login.microsoftonline.com/*

This endpoint is necessary for PaperCut to ask Microsoft for a device code, and then retrieve a token later on. You can read about the OAuth workflow we have implemented here.

I’ve ensured my PaperCut Application server can reach the endpoints necessary for this to work, but the status box is still just telling me to wait.

For some installations, the configuration process can get into a state whereby the status box is asking you to wait, but the Application Server isn’t actually trying to connect to anything. We do have an open bug to improve this, and if you’re having this issue, please raise a request through our support portal and quote PO-1012.

The good news is that for now, there is a way to reliably proceed to the next stage (where you get a device code), as follows:

  1. Although not always necessary, if you’ve encountered problems already it’s best to start with a clean slate. In the PaperCut admin web interface, navigate to Enable Printing > Mobile & BYOD > Email to Print and uncheck Enable Email to Print, then hit Apply towards the bottom of the page.
  2. Restart the PaperCut Application Server service.
  3. Once you’re back into the admin web interface, check Enable Email to Print once more and ensure the Status is listed as Not Configured.
  4. Enter the Host, Username, Application (client) Id, and Directory (tenant) Id, then click Apply.
  5. Underneath the status box, click Refresh; this will cause the two ID fields to become blank. Enter the two IDs once more, then click Apply again.
  6. Click the Refresh button again; the IDs may disappear again, but that’s okay. Continue clicking ‘Refresh’ until the Status changes to Waiting to sign in, and displays a device code, allowing you to continue on to the next step:


I entered my device code and authenticated, but now I’m seeing an error?

If the Status changes to Error, exactly what you’ll need to do will depend on the specific error you’re seeing. You might see an error in the status box itself, or you may need to follow the Logs link to see the error in the PaperCut Application Log.

A3 BAD User is authenticated but not connected.



When you are prompted to enter your device code, Microsoft will need to authenticate you. When you do authenticate, you must do so using the same account you’ve setup the mailbox for, and entered into the “Username” field in the PaperCut admin web interface.
If you authenticate with a different account (such as a global admin) the token we receive back will be invalid when we try to access the mailbox.

I can’t authenticate as the mailbox account, because it’s not an admin and I’m being asked to grant consent with a global admin account.

Depending on how your tenant is configured, you may need to provide global admin credentials to Microsoft during the device code stage of the setup. Because you’re authenticating as a different user than the one you’ve configured the mailbox for, the token we receive back from Microsoft will be invalid when we attempt to access the mailbox.
There are likely two ways for us to get around this problem

  1. Complete the setup, and when prompted for admin credentials, supply them in order to grant the necessary API Permissions’ to the App registration in Azure. Once that’s done, disable Email to Print in PaperCut entirely, and complete the setup process again from the beginning. This time, when you enter the device code′ ’, authenticate as the mailbox account, and with any luck, you will not be additionally prompted to grant consent with an admin account. This means the token we get back from Microsoft will be legitimate to access the mailbox.
  2. Pre-emptively add API Permissions to the App registration in Azure, before attempting to configure with PaperCut. This can be done in Manage > API Permissions. By default, User.Read will already have been added as a Delegated permission, but you may also need to add IMAP.AccessAsUser.All and email, both of which are also Delegated permissions. You may then also need to click Grant admin consent on the same page. Once added you can proceed with the PaperCut configuration, and when prompted to authenticate during the device code portion of the process, authenticate as the mailbox account, and with any luck, you will not be additionally prompted to grant consent with an admin account.


AUTHENTICATE failed.



There are two reasons we’re aware of why this might happen:

  1. This error can be generated when Email to Print is working fine, without issue. If the Status appears as OK, Email to Print is working, but your Application Log is littered with these messages, it’s very likely the cause of a bug that we’re presently fixing. The good news is these errors are false positives! If you’d like to be kept up to date as to when this issue is fixed, please raise a request through our support portal and quote PO-944.
  2. If Email to Print is not working, this is likely because the IMAP port and security scheme configured in PaperCut are wrong. Microsofts cloud mail services only allow mail to be retrieved using IMAP on a secure connection (using SSL and port 993), but at the moment, if you came from another type of Email to Print configuration (using basic authentication), PaperCut might not be configured to communicate this way. This specific error might mean we’re configured to use port 143 and STARTTLS instead. We have an open bug for this, to make sure that in future versions, we automatically set the port/security scheme appropriately when using the Microsoft OAuth Email to Print option; If you’d like to be kept up to date as to when this issue is fixed, please raise a request through our support portal and quote PO-984. The good news is that there’s a simple fix! In the PaperCut admin web interface, navigate to Options > Config Editor, and use the search box to find two configuration keys (email-printing.port and email-printing.security-scheme). You will need to ensure the VALUE of these two keys are set to 993 and SSL respectively, making sure to apply the changes by clicking Update after modifying each one:


No login methods supported!



Similar to the previous error, this is likely because the IMAP port and security scheme configured in PaperCut are wrong. Microsofts cloud mail services only allow mail to be retrieved using IMAP on a secure connection (using SSL and port 993), but at the moment, if you came from another type of Email to Print configuration (using basic authentication), PaperCut might not be configured to communicate this way. This specific error might mean we’re configured to use port 143 and NONE instead. We have an open bug for this, to make sure that in future versions, we automatically set the port/security scheme appropriately when using the Microsoft OAuth Email to Print option; If you’d like to be kept up to date as to when this issue is fixed, please raise a request through our support portal and quote PO-984. The good news is that there’s a simple fix! In the PaperCut admin web interface, navigate to Options > Config Editor, and use the search box to find two configuration keys (email-printing.port and email-printing.security-scheme). You will need to ensure the VALUE of these two keys are set to 993 and SSL respectively, making sure to apply the changes by clicking Update after modifying each one.

Error AADSTS7000218: The request body must contain the following parameter: ‘client_assertion’ or ‘client_secret’.

This is likely because Allow public client flows was not enabled for your App registration. To enable this, navigate to the App registration you’ve made in the Azure portal, then navigate to Manage > Authentication > Advanced settings - ensure Allow public client flows is enabled, and click Save.

Error AADSTS70020: The provided value for the input parameter ‘device_code’ is not valid. This device code has expired.

When the PaperCut Application Server asks Microsoft for a device code, that code expires in 900 seconds, by default. If you wait too long to navigate to https://microsoft.com/devicelogin and enter the code, this message will appear in the status box in PaperCut.
To fix this, disable Email to Print entirely in PaperCut, Apply the change, and start the process again from the beginning.

Error AADSTS70000: Provided grant is invalid or malformed.



This error is very rare, but if you do encounter it, the most likely thing to rectify the problem is disable Email to Print in PaperCut, click Apply, restart the PaperCut Application Server service, and start the configuration again from the beginning in order to proceed.
If you still have no luck, please raise a request through our support portal and let us know so we can try to troubleshoot.

I have another problem or error that isn’t covered here. What do I do?

Please raise a request through our support portal and let us know so we can try to troubleshoot :)


Still have questions?

Let us know! We love chatting about whatโ€™s going on under the hood. Feel free to leave a comment below or visit our Support Portal for further assistance.


Categories: Troubleshooting Articles, Email to Print

Keywords: O365, M365, Office 365, Microsoft 365, Email to Print, OAuth, IMAP, basic authentication

Comments