Configure an SMTP server for Google using OAuth2

If you have been using our Email Printing service, you might 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 for 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 page. Please head to the Setting Up Google OAuth2 for your Gmail account for Email to Print knowledge base page and have a look around. Ignore the step named 1. Set up an SMTP server  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 outlines of the steps. More details are on the knowledge base page linked above.

In summary, the steps are:

1. In Google’s API Library, start a new project and call it something like Gmail Services.
2. Enable the Gmail API.
3. Get the Google OAuth Client. Set up OAuth consent and set up Credentials.

Set up OAuth consent

1. Set up the OAuth consent screen. For User type, select External, and click CREATE.
2. Fill in the 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. The Scopes page is displayed.
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. You’ll see the scopes listed on the client as one of Your restricted scopes items. This is because we need to send/read emails on behalf of the email account via PaperCut MF. Therefore, it is 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. The Test users screen is displayed. This is where you define the allowed list of accounts that allow this client/application to access. 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. In the left menu, click Credentials.
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, for example, PaperCut Gmail Client.
6. For the Authorised JavaScript Origins section, 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, 9192, or 9195 if you are running on default ports.
7. Enter the Authorized redirect URLs. This is important. Depending on how your organization runs your PaperCut MF server, this Authorized URL will look different. The MF server will be listening on these paths. Because PapeCut MF could be running on port 9191, 9192 or 9195, it’s recommended to add 3 entries:
   http://localhost:9191/google-oauth2-callback
   https://localhost:9192/google-oauth2-callback
   https://localhost:9195/google-oauth2-callback
   
   If your host has a hostname and is public-facing, swap out the localhost part and replace it with a proper hostname. 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. In the Web admin interface, click Options > Notifications tab.

2. In the SMTP server dropdown, select Gmail with OAuth.

3. In the Username field, enter the designated email sender account, then enter the client ID and client secret into their fields.

4. Scroll down and click Apply.
   
   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.

5. Click Authorize. Google’s authentication interface is displayed. In the case of using multiple email accounts on one PC, be sure to select the correct email account for SMTP, that is, the same account you put in as Username.

6. If necessary, enter the password, then grant access to the PaperCut MF app. The consent screen redisplays and the status area above shows Status: OK.
   

7. Scroll down and try sending a notification to a user who has an email address registered with PaperCut 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, for example,  print@yourorg.com for Email Printing while notif@yourorg.com for notifications. They must both be added to the test users list, and 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 (for example, reading emails) while another one for something different (for example, sending emails), while they are used for the same application, at the same time.

You will encounter a 401 unauthorized error that way.

You can, 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 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, that is, 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:

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

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 Authorize directly without first clicking Apply to save the client details, the authorization attempt will also be blocked by the PaperCut 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.

If/when you do decide 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, you can 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. One of them does not apply to us - where a full scope must be requested even if we only do either 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’s 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 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 who use a certain email address from different IPs, different OSs, and different browsers for other business purposes, do not use this email account as your SMTP service account.