PRODUCT MANUALS

PaperCut NG & PaperCut MF Manual

PRODUCTS FEATURED

Configure an SMTP server for Google using OAuth2

If you have been using our Email Printing service, you may have already come across the steps of setting up an OAuth2 client for Google.

If you haven’t, don’t worry. This page is for you to learn the steps of setting up an OAuth2 compatible SMTP service with a Gmail account.

Setting up a client

First, we need to set up an OAuth client that represents the PaperCut MF application on the Google Cloud Platform.

For brevity, the same steps will not be repeated in detail in this instruction. Please head to this Knowledge Base Page and have a look around.

You will see a title named 1. Set up an SMTP server here, you can ignore that, because you are setting up an SMTP server right now.

What we are interested in here is how to set up the client. This page will only give an outline of the steps. More details on the knowledge base page linked above.

Please follow these steps:

• In Google’s API Library, start a new project (You can call it something like Gmail Services perhaps);
• Enable the Gmail API;
• Get the Google OAuth Client.

It is quite an involved process to go through the last step. It can be further divided into 2 stages.

Set up OAuth consent

1. Set up the OAuth Consent Screen. You may choose External for User Type. Click CREATE;
2. Fill in App name, User support email and Developer contact information (these should be your own organization’s IT support email). They are mandatory fields.
3. Click SAVE AND CONTINUE. You will then see the scopes page.
4. Click ADD OR REMOVE SCOPES and add https://mail.google.com as the scope value. This value will allow you to use the same client for both SMTP services and Email Printing services over OAuth2, even from 2 different email addresses. More on this at the end of this page;
5. Click UPDATE and you will see the scopes listed on the client as one of Your restricted scopes items. This is because we do need to send/read emails on behalf of the email account via PaperCut MF. Therefore, it is perhaps a good idea to set up an email address that does not belong to any individual as a designated SMTP sender (or email receiver);
6. Click SAVE AND CONTINUE and you will see the test users screen. This is where you define the allowed list of accounts that allow this client/application to access. Make sure you add your designated accounts here.
7. Add your email accounts that will allow this client to access, click ADD, review the table of accounts, then SAVE AND CONTINUE.

Set up credentials

1. Click Credentials in the left menu;
2. Click + CREATE CREDENTIALS to add OAuth2 clients;
3. Choose the OAuth client ID option;
4. On the next page, choose Web application for Application type;
5. Give the client a name, such as PaperCut Gmail Client, or whatever you like;
6. For the Authorised JavaScript Origins section, you may enter something like http://localhost:9191 or https://localhost:9192 (or however your organization has set up the MF server. For example, if your PaperCut MF server runs at https://print.someuniversity.edu, you need to set the Authorized JavaScript origins as https://print.someuniversity.edu:443. Note that the default port value is also within the origin, as it is mandatory, unless the default value is 80. Use port 9191 or 9192 if you are running on default ports.)
7. Enter the Authorized redirect URLs. This is important. Depending on how your organization runs your MF server, this Authorized URL will look different. The MF server will be listening on these paths. Some of you will be running your MF on port 9191 and some on 9192. It is therefore recommended adding 2 entries here: http://localhost:9191/google-oauth2-callback and https://localhost:9192/google-oauth2-callback. If your host has a host name and is public facing, swap out the localhost part and replace it with a proper host name. Do not use a public IP address or wildcard expressions here as they are not permitted by Google APIs and Services.
8. Click CREATE or SAVE, if you are editing. Record the client details. Click OK, then CLOSE.

Using the client details for SMTP over OAuth2

It is easy to get the SMTP service up and running from this point on.

1. Head to Options section of the admin UI and click on the tab name Notifications;
2. In the SMTP server dropdown menu choose Gmail with OAuth;
3. Fill in the designated email sender account as Username, and fill in the client ID and client secret into the input fields respectively;
4. Scroll down the page and click on the Apply button;
5. Back in the SMTP Server Options section, you should now see an Authorize button, provided that the username, client ID and client secret fields are appropriately populated;
6. Click on it, MF should take you to Google’s authentication interface. In the case of using multiple email accounts on one PC, be sure to select the correct email account for SMTP, i.e. the same account you put in as username just now;
7. If necessary, put in the password, and grant access to the MF app. You should see the consent screen you just set up a while earlier;
8. That should be it. The little status area above should now say Status: OK;
9. Now you may scroll down and try sending a notification to a user who has an email address registered with MF.

Important information about using OAuth2 clients with Google

It is important that you set up a client with the scopes of https://mail.google.com when using OAuth2 authentications with MF. See image above about scopes.

This is because while you can use different email addresses for OAuth Email Printing and OAuth SMTP, e.g. print@yourorg.com for Email Printing while notif@yourorg.com for notifications, provided that they are both added to the test users list, they have to use the same client ID and client secret.

Google does not permit the usage of 2 different clients, with one for one purpose (e.g. reading emails) while another one for something different (e.g. sending emails), while they are used for the same application, at the same time.

You will encounter a 401 unauthorized error that way.

You may of course create multiple clients with different client IDs and client secrets within one project on the Google Cloud Platform. However, please use only one of them if you are using Email Printing and Notifications over OAuth at the same time. It is perhaps good practice to rotate through client details on MF over time, at regular intervals such as 6 months or 1 year, and retire older ones by deleting them from the GCP.

To safeguard this process, some extra validation checks have been introduced.

Adding client information for either Email to Print or SMTP server will NOT work if:

• One of these 2 services is already up and running, i.e. in an OK state; AND
• An attempt to add and save a different set of client details or even directly clicking on the authorize button for the other service.

Sample error messages:

Above: a sample error message when Email to Print is already running on Gmail over OAuth AND when the user tries to save a different set of client details for the SMTP server

Above: a sample error message when SMTP service is already running on Gmail over OAuth AND the user tries to save a different set of client details for Email to Print service

In the second case, if the user tries to click on the Authorize button directly without saving the client details first by clicking on the Apply button, the authorization attempt will also be blocked by the MF server. This is because if we let it through, Google will return a 401 Unauthorized, and once that happens, the app server will be blocked from further authentication attempts with Google for a period of time, which is a bad user experience.

If / when you do decide, as a sysadmin, to update the client information on the system for security reasons, you must stop these services first at a scheduled downtime. Once they are not in an operating OK state, it’s perfectly OK to put in a new set of client details, so long as they are the same for both services.

Occasional Problems With Shared Accounts - OAuth2 Asked For More

Occasionally with shared gmail accounts, while negotiating with Google’s authentication services, the user may run into an error that says “Reason: OAUTH2 asked for more”, while seeing the SMTP client failing to send a notification, after what should have been a successful authentication process.

Generally there are 2 reasons why this might happen, but one of them does not apply to us, where a full scope must be requested even if we only either do IMAP or SMTP with a JavaMail client, as MF will always request the full scope https://mail.google.com.

The other reason why this happens could be related to how the account is being used. If it is an organizational account that is shared between a few users who log in now and then from different OSs, different browsers and different IP addresses, there is a greater chance that the authentication process will be pulled up by Google to do a random spot check, just to confirm that the user is who they say they are. This could be in the form of entering a verification code coming through a text message or clicking on a “YES” button on a smartphone’s Google or YouTube apps.

Normally, this shouldn’t happen to a set-and-forget, dedicated SMTP account used by an organization. In the rare case that it does happen, you may need to set up the client information and then authorize again. To do this, you may have to change the SMTP type to “choose…” or “custom”, save, and choose “Gmail over OAuth” again, and enter the client details again.

This is because when the SMTP manager is in an error state, we disable the “Authorize” button. Most of the time, the SMTP manager is only in an error state because the details of the client are wrong. We encourage you to check and change them before attempting to authorize through Google again.

When the SMTP manager runs into an error state because it gets asked “for more”, it doesn’t mean the client details are wrong. For this problem that should normally not happen, you will need to use the workaround method mentioned above.

To avoid this, please don’t use a shared account for SMTP purposes. If you know different people from your organization use a certain email address from different IPs, different OSs and different browsers for other business purposes, please do not use this email account as your SMTP service account.