Setting Up Google OAuth2 for your Gmail account for Email to Print

“Google is switching off their basic authentications for third party apps at the end of May 2022! What now?” What’s happening at Google Google is switching off its support for basic authentications for free Gmail accounts used on third-party applications. This means, for example, if you want to use a Gmail account to do email printing on PaperCut MF/NG, and if you are not a Google Workspace subscriber, printing will no longer work with an email address and a password, even if it’s an “App Password”. Similar things are happening at Microsoft as well. Basic authentications with a username and a password is now regarded as not secure. OAuth(2) is fast becoming the industry standard. If your organization is using Google Workspace, your basic authentication will still work for now, but Google really wants you to switch away from using it and get on the OAuth train. Introducing new support for Google’s OAuth in PaperCut MF/NG Email to Print Version 22.0.3 of PaperCut MF and NG includes support for Google OAuth2 so that even free-tier Gmail users can continue to use Email to Print. Setting up OAuth2 Authentication for Your Gmail account Prerequisites Before you start you need to do the following, which are all described below: Set up the SMTP/Notification side of settings to be able to enable Email to Print. Start a new project on the Google Cloud Platform - available to any Google user. Enable the Gmail API, which is public and free. Get the GoogleOAuth client, so you can communicate with the Gmail API. 1. Set up an SMTP server If you’re already using email printing, you’re probably already familiar with the process of setting up an SMTP server. If you need a refresher, however, take a look at Configure email for further details. 2. In Google’s API Library, start a new project You can find Google’s API Library at https://console.cloud.google.com/apis/library and it includes most of the modern APIs. Gmail is one of the free, public APIs that anyone can use without having to be a subscriber of Google Workspace. Scroll around the lower half of the API Library page to browse the APIs. If you’ve never used a Google API before, you’ll need to start a new project. Name it anything that makes sense to you. There are two ways to create a project: At the top left of the blue banner, next to Google Cloud Platform click the three-dot icon. Wait until after you enable an API, and Google will automatically set up a project for you. 3. Get and enable the Gmail API To get the Gmail API, click the Gmail API tile. The Gmail API screen is displayed. Click Enable. If you hadn’t yet set up a project, Google will create one and call it My First Project. 4. Get the Google OAuth Client When setting up Gmail printing for the first time You need to start by configuring the OAuth consent screen. If you’ve done this before, you can scroll down to When you’ve set up OAUTH consent. On the left menu, click OAuth Consent Screen. Select the type of user and click CREATE. You’ll see the OAuth consent screen. Type the App name (PaperCut MF perhaps), User support email (your admin email, or email printing service email etc.), and down at the bottom of the page, Developer contact information. These fields are mandatory. You can leave the other fields blank. Click SAVE AND CONTINUE. The Scopes page is displayed. This is where you define what your client needs to do. NOTE: Google’s OAuth system operates on an as-needed basis. You need to declare what type of data you need the user to authorize you to be able to access. The user can decide if they want to authorize the app. By “user” here we are talking about an organizational service email account that’s used for the printing service; it’s not a private email account. So, as the sysadmin, what you are letting PaperCut MF/NG do is basically access the particular Gmail account for reading mails, pulling the attachments and deleting emails etc. Click ADD OR REMOVE SCOPES and browse the pages of scopes until you find https://mail.google.com . This scope will allow PaperCut MF/NG to read, compose, send, and permanently delete all your emails from Gmail, inside the service account only, of course. Click UPDATE. Now, when you scroll down, you’ll see the scope listed on the client as one of Your restricted scopes. (Email content is, of course, sensitive data for a private user. It’s just in this case, the user is a service account that we use for the organization’s email printing service.) Click SAVE AND CONTINUE. The Test users screen is displayed. This screen basically defines which users’ email accounts can be potentially used to authorize the PaperCut MF/NG app to access their emails. Under User Type click MAKE EXTERNAL. Then click ADD USERS and add the email address you intend to use for the Email to Print service in PaperCut MF/NG. IMPORTANT: the user(s) added here do not automatically get exposed to the PaperCut MF/NG app. They still need to do a normal sign in to Google and explicitly authorize the PaperCut MF/NG application before PaperCut MF/NG can read, compose, and delete on behalf of the account. You only need to add the service account you are going to use, for example, print@your-org.com . Click ADD. The email address shows in the table below. Click SAVE AND CONTINUE. The Summary page is displayed. This is the summary page of what you’ve entered so far for the OAuth consent screen. Phew… finally, the OAUTH consent screen is set up! Now we can go back to the Credentials page to obtain an OAuth client. When you’ve set up OAUTH consent In the left menu, click Credentials. Click + CREATE CREDENTIALS to add OAuth2 clients. Choose the OAuth client ID option. On the next page, for Application type, choose Web application, since PaperCut MF/NG is serving up the admin pages as a web app. Give this client a name; anything will do. Why not “PaperCut E2P Client” or something like that? For the Authorised JavaScript Origins section, you may enter something like “http://localhost:9191” or “https://localhost:9192”. Enter the Authorised redirect URIs. IMPORTANT The redirect URIs are the URIs Google will send the authentication information back onto your PaperCut MF/NG server. The 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 to add 2 entries here: http://localhost:9191/google-oauth2-callback and https://localhost:9192/google-oauth2-callback . Click CREATE (or SAVE if you are editing the details of this client). You are given an opportunity to download the client details in a JSON file onto your computer. If you accidentally clicked past it, don’t worry, the Credentials page lists the OAuth Clients in a list and you can edit, delete, or download their details at any time. Click OK. The API key created dialog is displayed. Click CLOSE. Warning If you have set up your callback URL with Google’s client to be something like http://localhost:9191/google-oauth2-callback or https://localhost:9192/google-oauth2-callback , instead of a public facing Internet address, then you must complete the set up process set out below for the Email Printing service on the server itself, or at least use remote desktop to operate on the server itself. You shouldn’t use an internal IP address such as http://10.x.y.z:9191/ in your browser from a different computer to log in as an admin to do this. Using the Google API Client in PaperCut MF/NG Congratulations - at this point, you’ve already got most of the work done! Save the client information JSON file somewhere safe. Considering that it is a file containing relatively sensitive information, do not share it around. You may delete an OAuth client off your credentials list any time you want, by using the Google Cloud Platform console. It’s perhaps best practice for information security to actually do so every 6 months and set up a new one. Just be mindful that once you delete a client from the Google Cloud Platform console, it can be no longer used to access the Gmail API. Inside the JSON file, we want 2 pieces of information to get your Gmail account going. One is the client ID, the other is the client secret. On the PaperCut web admin UI, click Email Printing > Mobile & BYOD and scroll down to Email to Print. Click Enable Email to Print. For the Protocol select ‘Gmail OAuth2’. The fields change into what is required for Google OAuth. For Username, type the service email address. This email address should have been added as one of the “test users” in the steps above. Copy and paste your client ID and client secret into their respective boxes. A message will appear telling you that because the details of these fields have changed, you need to authorize via Google. Click the Authorize via Google button next to the message to complete the authorization process. Note that this will take you away from the PaperCutMF web admin UI momentarily. Complete the log in and authorization process with Google. You’ll be automatically returned to the PaperCut MF/NG page. To check the progress of the authentication, under the black Email to Print status box, click Refresh. With everything done correctly, you’ll see the Status: OK message pretty soon. Should anything go wrong and lead the email printing service to an error state, the refresh button will clear up previously filled information. NOTE: By this stage you may have noticed that every time you change any of the 3 fields related to the Google API client on this page, the message will show up to warn you that the information has been changed and you will need to re-authorise the PaperCut MF/NG application. This is because different email addresses (Google regards it as user ID) or different client details would of course affect the authentication and authorization processes. IMPORTANT: A likely mistake in this process is that you put in one email address for the username on PaperCut MF/NG’s admin UI while picking another email account outside PaperCut MF/NG during Google’s log in and authorization process. We all have a few email accounts for daily dev work and receiving merchant promotions! Be extra careful while you click through the account picker with Google where you see a list of your accounts in the browser. Make sure you choose the account you would like to use for email printing service. Otherwise the token will have been issued for an account other than the one PaperCut MF/NG is going to try to pull emails from, which of course would lead to an error. If this is the first time you set up the OAuth2 protocol for Gmail, you’ll be taken to Google’s consent screen, which you set up yourself earlier on the Google Cloud Print console. It also means, without the consent of the email address owner, PaperCut MF/NG cannot access the content of that email address. If you change other details on this page while having Google OAuth as the email to print protocol, you will not be prompted to log in or authorize PaperCut MF/NG again. Hope this article has been helpful. Upcoming fixes: Currently there is a minor problem that prevents the authentication of OAuth2 on Google if the MF server runs on default ports (e.g. 80 and/or 443, instead of any other ports, say 9191 and 9192). This is being addressed and hotfixes/upgrades will be available soon. 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.