Contact Importing

Your Google OAuth Credential is Broken (and you won’t even know it)

Google’s OAuth set up and verification can mislead you into thinking you are ready for production, but in fact your users are seeing a broken UX

Nothing kills an OAuth user experience like Google’s danger screen. It is to be avoided at all costs. But your users might be seeing this screen even if you believe that your OAuth has been verified by Google.

Will anyone click the ‘advanced’ link and then continue to grant access to your app? Not likely.

How is this possible?

Here’s what happens. Google shows the danger screen to everyone the first time your app requests permission. As a developer/tester/owner of your app, you’ve likely already granted permission. So Google probably won’t show you the danger screen or the permission request page anymore.

This can lead to a false sense of assurance that your Google OAuth project is fine for everyone else.

But it may not be. Just because you aren’t seeing the danger screen, doesn’t mean your app is verified.

What could be wrong?

There are three common traps the people get caught in and I’m going to look at each.

  • You may have not requested verification
  • You may have requested verification and Google is waiting on you for modifications
  • You may not have included the sensitive scopes in your verification request

Let’s look at each of these at a time.

Pitfall #1: You have not requested verification

As described, Google remembers that you’ve already granted access to your app and for the sake of efficiency, will skip the entire OAuth flow. The first time you tested your app, you would have seen the danger screen and clicked through it. And since nothing has changed with your application, Google will continue to skip it.

How do you know if this applies?

If you haven’t looked at your OAuth consent screen in a while, take another look. You should not see either message below in the Verification Status section.

screenshot of Google's verification not required message
Your app needs some attention if you see this message.

If you see the message “Verification not required” then Google doesn’t think you want to use any sensitive scopes in your application. You’ll need to add the proper scopes (and possibly enable the associated APIs) in order to get them to take you seriously.

Google's needs verification message
Your app OAuth setting may be correct, but you haven’t yet requested verification.

The “Needs verification” message indicates that you have added the correct scopes, but you haven’t yet requested verification from Google. No problem, edit your OAuth settings and “Submit for verification”.

Pitfall #2: Google is waiting on you

After you request Google’s verification, your OAuth account will reflect that verification is in progress.

Google's verification in progress message
Your verification request is in progress!

Great! The trouble is that this message won’t change until the verification is complete. It won’t reflect whether Google is waiting on you for additional information or changes to your app.

They might be waiting on you for:

  • Additional information, such as a demo video
  • Changes to your OAuth project, such as making the name of your application consistent with your public brand
  • Changes to your application, such as making your link to the OAuth flow confirm to Google’s branding guidelines

Your Google developer project doesn’t currently show you if Google wants anything else. The one and only place you learn about it will be your email inbox. Google will send an email to you so watch carefully for an email from them.

This is a bad situation because if you miss that email, you can get stuck here. Forever.

A bit of good planning will help you avoid this pitfall.

  1. Make sure you include two monitored email addresses, double check it for typos.
  2. After you submit your app for verification, watch for a confirmation email from Google that should arrive within 24 hours. If you don’t get this email you might re-submit your request for verification by making a minor change to your OAuth to re-enable the button.
  3. Add a coworker as an owner to your project. Or if you are a CloudSponge customer, add us. We’ve started to see Google’s emails going to all project owners. Make use of this to build some redundancy into their process.
  4. Watch for their emails. They use api-oauth-dev-verification-reply@google.com for their verification replies. Here’s a pre-populated search for this email address within Gmail. (The email address they use actually also contains a hashed value)

Pitfall #3: You did not include the sensitive scopes for review

It’s easy to miss this one. But it’s super important.

If you requested verification but didn’t include your sensitive scopes Google will verify your brand only. They may even send you an email telling you that everything is all good.

Google only verifies your app for the individual scopes that you have added. This actually makes some sense when you think of it from their perspective: yes, you’ve enabled the Contacts API for your project, but will you be using the read-only scope or a read/write scope? Google is smart, but not clairvoyant (yet). So make sure you have added all the sensitive scopes that you are going to request from users to ensure that Google verifies your app for them.

Take another look at your OAuth consent settings page and make sure that you’ve included the scopes that you are using here.

sensitive scopes included in Google's consent page
This is how you tell Google which permissions you are going to request from users.

If your sensitive scopes are not included in this list, you’ll need to add them. If you cannot find the scopes you are searching for, you may need to visit the Library page and enable the associated API before you can add the scope.

So, how can I be sure?

As I mentioned at the start of this article, you might have fallen into one of these pitfalls and not even know it because Google will hide the danger screen from you because you’re testing it with a Google account that has already granted permission.

The simple solution is to revoke your app’s permissions on your Google account, or to do your testing with a different Google account entirely. This lets you visit every step in the OAuth flow, including the danger screen if it’s being shown.

Here’s how to revoke access.

  • Visit your permissions page
  • Find your application in the list
  • Click Remove Access
  • Wait a few seconds (to let the permission change propagate).

Now go back to your app and visit the OAuth flow. If you see the danger screen, you’ve hit a pitfall, go back to your OAuth consent screen and check your email for any correspondence from Google.

If you don’t see the consent screen, it’s almost time to celebrate! You’ve avoided these 3 ugly traps.

I say “almost”, because while you are here, you’ll want to confirm a few other details to be sure that your users are having the best possible experience as you ask for their consent.

Have a look at the consent page and look for the following:

  • Your app’s name – this will show your domain until Google has verified your brand
  • Your apps’ logo (if you uploaded one) – this is hidden until Google verifies your brand
  • A request for the sensitive scopes – this should match the scopes you indicated
a properly branded OAuth screen highlighting the things to check for
Here’s a properly branded OAuth screen

Now it’s finally time to celebrate! 🍻

Now that you know these dangers exist, you are better equipped to avoid them. And you have an easy process to check if you’ve gotten trapped in any of them.

By the way, if you are using CloudSponge to integrate with Google’s Contacts and People APIs, you can just sign in to your account and look at your OAuth credential. If you’ve indicated that it is used for production, we monitor it for you daily and report any problems to you.

Cloudsponge's OAuth health monitor
CloudSponge monitors your Google OAuth credential for you.

Sign up for CloudSponge to get our help integrating with Google’s Contacts and the other most popular online address books.

Graeme Rouse, CTO at CloudSponge

Follow @thunderouse

Comments

Try CloudSponge for free in your
testing environment

Get a Free Sandbox Account

Have a questions or prefer a guided tour?
Schedule a consultation with our Founder.