Goa v8 changes and enhancements

v8 and other HTML service changes meant I had to make a few small changes to cGoa. The good news it’s easier to use than ever and supports a few new services too. It’s best to look at the service list on Github, as that’ll be kept up to date. Here’s a reminder of how to use it.

Once you’ve set up your credentials in the property store of choice (see one time settings later) for an example, there are just 3 steps. Here is the pattern for a 3 legged OAuth that needs user consent via a web page. This is the most complex type of OAuth.

function doGet(e) {
 
  // step 1 make a goa to control the process - important that e is passed
  const goa = cGoa.make ('linkedinabc' , PropertiesService.getScriptProperties(), e);
 
  // step 2 it's possible that we need consent - this will cause a consent dialog and recurse back here
  if (goa.needsConsent()) {
    return goa.getConsent();
  }
 
  // step 3 if we get here its time for your webapp to run and we should have a token, or thrown an error somewhere
  if (!goa.hasToken()) throw 'something went wrong with goa - did you check if consent was needed?';
  Logger.log('has token');

  // here's the token
  return HtmlService.createHtmlOutput (goa.getToken())
    .setSandboxMode(HtmlService.SandboxMode.IFRAME);
  
}

How it works.

Oauth2 can be a maze of callbacks that are quite difficult to follow. With goa, you don’t need to bother with all of that as it’s taken care of automatically.

Step 1. Add a doGet() function to your app – whether or not it’s a web app and publish it. You can delete it later if your app is pure apps script.

You create a goa, which looks up the credentials for the name given (this will match with the name you used in the one time settings)

const goa = cGoa.make ('linkedinabc' , PropertiesService.getScriptProperties(), e);

Step 2. Check to see if consent is needed. Goa manages refreshing tokens so if there is already one around from before, it won’t bother with the consent dialog.

// step 2 it's possible that we need consent - 
// this will cause a consent dialog and recurse back here 
if (goa.needsConsent()) { 
  return goa.getConsent(); 
}

What getConsent does is to create the consent dialog and link to the provider you are trying to authenticate to. Once that’s done it restarts the doGet(e). The e parameter this time tells it that the consent stage has already happened and how to discover what the result was. This is stored in the property store so future consent checks will first try to refresh any token it already knows about from previous times. That’s why the consent screen will generally only ever happen once.

Step 3. That’s it  – you should have the token available via goa. Every time you access it checks to ensure it hasn’t expired and gets a new one in the background if required.

  // step 3 if we get here its time for your webapp to run and 
  // we should have a token, 
  // or thrown an error somewhere
  if (!goa.hasToken()) throw 'something went wrong with goa - did you check if consent was needed?';

You’ll want to close off the doGet now with some kind of message

  // here's the token
  return HtmlService.createHtmlOutput (goa.getToken())
    .setSandboxMode(HtmlService.SandboxMode.IFRAME);

Using the token

Unless you are actually creating a web app, you won’t need to bother with the doGet again. You’d just get it and use it like this in a server side app.

function testmygoa () {

  const goa = cGoa.make ('linkedinabc' , PropertiesService.getScriptProperties()); 
  if (!goa.hasToken()) throw 'something went wrong with goa - looks like you need to get consent';
  // you can use the token now
  Logger.log(goa.getToken());
}

And that’s all there is to it.

One off function

Naturally, you have to go through the motions of creating an app with whichever provider you use. The format is pretty much standard across providers. Here’s a pattern to write those details to the property store. You can delete this function once you’ve run it.  Here’s an example of using the Linkedin API.

function oneTimeSetProperties () {

   // used by all using this script
  var propertyStore = PropertiesService.getScriptProperties();

  cGoa.GoaApp.setPackage (propertyStore , { 
    clientId : "7...1",
    clientSecret : "Z...z",
    scopes : ['r_emailaddress'],
    service: 'linkedin',
    packageName: 'linkedinabc'
  });

}

For more like this, see Oauth2 for Apps Script in a few lines of code.

Why not join our forum, follow the blog or follow me on Twitter to ensure you get updates when they are available.