Trying to like OAuth2


EzyOauth2 has now been superseded by Goa, so this document is for legacy information. For more information see OAuth2 for Apps Script in a few lines of code. If you are using EzyOauth2, it's easy to migrate. If you are starting up, consider using Goa instead - it's easier and has more features.

Every time I think about what my next project will be, I almost always use whether or not I need to use Oauth2 as the deciding factor, because I know I'll spend more time wrestling with it than actually doing the interesting parts. One of the trickiest projects on this site is Google Oauth2 VBA authentication, and that was quite fun, and the implementation is such that the gory details of how it was implemented is hidden, by design. This means though, that every time I do reach for oAuth2 I have to learn it all over again. Similarly if you are using the Google Apps Script advanced services, all that is taken care of for you, and for javaScript apps, you can often use the gapi. JavaScript library. The common theme then is to protect people from Oauth2 because apparently it gives you a headache.

I hate these things about OAuth2
  • Inconsistent naming across implementations. The client secret, consumer secret, client key, client ID , token Url, service account, client email etc.. etc.. are all mixed up in a big melting pot of confusion. The Cloud console and the documentation give the same things different names, as do individual app write ups, and these of course all change across implementations. 
  • Redirection Urls. It can be an app that doesn't support this, so of course this means that you have to jump through workarounds and hoops to make it work. Sometimes you can't know in advance what the apparent script URL you are executing against is, and when you write shareable libraries for multiple people to use you have to carry all that complication with your library and pass it on to people who use them. It's built around an expectation of interactivity that might not be part of the purpose application.
  • When it gets to the important part of writeups of Oauth2 implementations, the author usually pushes you off to some general Oauth2 writeup, as if he never wants to speak about his terrible experience again. This means there are no good write ups of Oauth2 implementations around that can be adapted to specific problems

Laying out some examples

In this article I'll try to lay out some OAuth2 scenarios, and avoid shying away from the nasty bits. Hopefully the excercise will also help me having to relearn from scratch every time I need to implement something with Oauth2, and with any luck, you'll find it useful too.

What is Oauth2?

It's an authentication dance, designed to ensure that whoever is asking for access to a resource is a) allowed to b) likely to be who he says he is, accessing from an expected place

It goes like this.
  • You register an app, and get some credentials.
  • You request access and go through a 'user consent' dialog. This let's the user know that the application is about to access some protected resource, and gives the opportunity to allow it.
  • If the user allows it, the application gets an access code as proof. How to get that is the first tricky part. A redirect URL that you need to have previously registered with your app receives this access code. This code gives the application the right to ask for a token to allow it to subsequently communicate with the resource it is after.
  • With the access code, and some other secret information, the application can now ask for a token which it will use for subsequent requests
  • An access token is returned and can be used up to some expiry time. In addition a refresh token is returned. Using this refresh token, a new access token can be asked for if the original one has expired, thus avoiding the entire dialog.

As a process it's fairly straightforward. However, implementation can be challenging.

You want to learn Google Apps Script?

Learning Apps Script, (and transitioning from VBA) are covered comprehensively in my my book, Going Gas - from VBA to Apps script, All formats are available from O'Reilly, Amazon and all good bookshops. You can also read a preview on O'Reilly

If you prefer Video style learning I also have two courses available. also published by O'Reilly.
Google Apps Script for Developers and Google Apps Script for Beginners.