Nylas’ Google Auth Guide

Accurate and straightforward steps for a successful Google authentication.

Jerome Villegas | September 27, 2021

At Nylas, we’ve updated our Google authentication flow to meet Google’s new User Data Policy for their API services. This guide will help arm you with the information you need to quickly and securely authenticate Google users into your application.

As of September 30th, 2021, Google is requiring developers to allow users who are authenticating to manually select the scopes they agree to share 

Want a PDF of this article?

Share it with a friend or save it for later reading.

Anytime additional steps are required in authentication, you’ll typically see a massive drop-off; so reducing the amount of work required by the user to authenticate, while still authenticating securely, is critical to growing your user base.

New OAuth Consent Required Information

During authentication, your application must explain your app’s need for accessing the user’s Google data. 

Users must consent and opt-in for the application to access their restricted scopes. Now, you must include the information below for the authentication process to work with Google’s policy:

  • Scopes needed
  • Access required

Before users continue, they must agree and manually check the checkbox of the necessary scopes to allow your application to access their data.

You can use the solutions below to increase successful authentication rates and prevent friction in the new flow:

  • Split OAuth Requests into Two Steps – Removes checkbox prompts, creates a two-step authentication process
  • Add an Additional OAuth Screen – Keeps checkbox prompts, adds an explanation of scope and access requirements

Split OAuth Requests into Two Steps

To prevent drop-off in the new authentication flow, you can use two authentication requests that circumvent users’ need to check every box manually. The first request would surface identity scopes and the second request surfaces additional Gmail scopes. By separating the scopes, you can avoid having your users select checkboxes.

First Request: Identity Scopes

For users in your application, make an initial authentication request with the formatting from the following URL. This structure contains identity scopes in line 3. From here, the authentication process brings users to an account selection page to select an account.

This example separates URI parameters by line for visibility.

https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=https://us.email-connect.sample.com/connect/callback
&response_type=code&client_id=50650754255-gq1sninukbp9d4id181dq87noofllcha.apps.googleusercontent.com
&scope=openidemail
&access_type=offline

Separating the authentication into this first request lets your application redirect to Google with the necessary credentials.

Second Request: Adding Gmail Scopes

Once users have selected an account to authenticate, make a second request using the following URL formatting. The example link below includes the login information as well as the additional necessary scopes. Replace the <USER_EMAIL> with the account email from the first request. The additional request parameters are in the example below, and the URL removes the prompt=consentrequest parameter for this second request.

This example separates URI parameters by line for visibility.

https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=https://us.email-connect.sample.com/connect/callback&response_type=code
&client_id=50650754255-gq1sninukbp9d4id181dq87noofllcha.apps.googleusercontent.com
&scope=https://www.googleapis.com/auth/gmail.readonly
&access_type=offline
&login_hint=<USER_EMAIL>

Working with the first request, this second request brings your users through the authentication process without user missing scopes.

Add an Additional OAuth Screen

Another option to help users navigate your app’s authentication process is to have an additional screen or prompt to explain the changes. With Google’s requirements for using API services, the added page can explain the requested scopes and how they are used. This step lets users agree to their data being managed in your application and check off the boxes themselves.

Speak to a platform specialist to learn more about Google’s Authentication process and how we can help!

Jerome Villegas

Jerome is a Technical Writer at Nylas working on improving content for developers. Find him reassuring his talkative Husky mix and reflecting over a freshly brewed cup of coffee.