How OAuth2 works and Goa implementation

Oauth2 for Apps Script in a few lines of code (which you should read first for background) has many pages of videos and tutorials about different OAuth2 scenarios for Apps Script and is used daily in many projects by many users. Newcomers often have some conceptual problems with what OAuth2 is, how it works, and how this library takes care of the complications.

The main conceptual issue is that, in the case that your app is a webapp and needs user consent, it brings up a dialog in the browser to get consent, then restarts the webapp (actually the OAuth2 API calls it back using a redirect URI) – which is now in a new context. Goa hides all that complication, so that it seems like you are writing a single sequential pattern that is exactly the same whether or not the consent part actually happened.

I’m not going to repeat the tutorials here, but instead try to give an overview of the different approaches you can take, depending on your app.

Page Content hide

Flow approaches

In all cases, a Properties Store is used in which to store App credentials and scopes you require access to. These come from your API dashboard and take various formats. The first step for OAuth2 is to set that up, then run a one off script to store them in the Script Properties store so that Goa can use them. Depending on whether you are accessing Script or User specific resources, Goa will also maintain token refresh info in either the Script or User Properties store for its own use.

Depending on your app , OAuth2 platform, and use case, you can take a number of approaches.

App characterisitics	Who do the resources required belong to	Properties store for credentials	Properties store for token refresh info	Approach
Server side Apps script and API supports Service Accounts	Script	Script	Script	Service Account flow. This is the simplest as it doesn’t need a consent dialog
Server side Apps script and API doesn’t support Service Accounts	Script	Script	Script	Create a doGet function with Goa consent built in, publish it to run as the script owner, run it and authorize access to the scripts resources. Thereafter allow goa to maintain refresh tokens with no further need for doGet function
WebApp	Script	Script	Script	Create a doGet function with Goa consent built in, publish it, to run as script owner. The first time it is run it, it will request access to the script’s resources, so the script owner should run it. Thereafter goa will maintain refresh tokens and not request authorization again
WebApp	User	Script	User	Create a doGet function with Goa consent built in, publish it, to run as user. For this flow, the first step in a user flow clones the Script Credentials to the User Properties store from the Script Properties store. The first time each user runs it, it will request access to the user’s resources, so the script owner should run it. Thereafter goa will maintain refresh tokens and not request authorization again for that user.
Add-on				Add-ons work the same as each of the cases above. See the documentation for consent dialogs in sidebars or modal dialogs.

How does Goa work

When a request to create and execute goa is made, as in the example below, it will check for the given profile in the given property store. One of these things can happen.

It’ll find an access token with some time left on it or…
It’ll refresh an access token if it has previously been given consent or….
If it’s a service account it will go through the service account flow. It doesn’t need consent for that or…
It will need to re-enter your script as a webapp to be able to ask for consent in the browser. When that’s obtained it will again restart your webapp, where option 1 above will be true.

var goa = cGoa.GoaApp.createGoa('onedrive', PropertiesService.getScriptProperties()).execute(e);

To detect whether consent is needed, after creating and executing the goa, you can check and kick off a consent dialog like this. This is option 4, described earlier.

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

Finally, you complete the pattern with a check to see that everything has worked.

// 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?';

Now you can be sure that you have an access token with time on it any time you need it. You can get it with goa.getToken()

Expiring

In the case of server side apps, goa will always ensure there is enough time on the token to last the maximum running time of your script, but it’s possible that you have a webapp or add-on which sits around for a while doing nothing, during which time the access token (which only has a limited lifetime depending on your OAuth2 API platform) expires.

If that’s likely to happen, it’s easy to avoid by simply repeating the execute() just before you need an unexpired token.

var goa = cGoa.GoaApp.createGoa('onedrive', PropertiesService.getScriptProperties()).execute(e);

UserProperties

If you are running a web-app as the “user running the script“, then Goa will need to use the UserProperties so that each individual user gets his own consent dialog and refresh structure. Goa provides an easy way of synching the credentials (which are stored in the ScriptProperties) with the UserProperties for this situation.

Before creating and executing a goa, first use the useClone method, and then refer to the userproperties when creating the goa. That’s the only difference.

// this starts with a package copy for a specific user if its needed
  cGoa.GoaApp.userClone(packageName, scriptPropertyStore , userPropertyStore);
  
  // create a user specific package. 
  var goa = cGoa.GoaApp.createGoa (packageName,userPropertyStore).execute(e);

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.