Goa Setup

This describes how to set up a script to use the Goa library as described in Oauth2 for Apps Script in a few lines of code (which you should read first for background).

The library, cGoa, is available under this project key, or on github. All the tests described for this topic are also available on github.


Getting a Goa

A Goa class is created from the GoaApp namespace like this.

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

createGoa (packageName , propertyStore , timeout , impersonate)

 argument purpose  
 packageName A package is the credentials , service, scope and control data used to authenticate. You should give each package a unique name
 propertyStore This is the PropertiesStore in which to store the package. Pick the appropriate store depending on whether the authentication applies to the script or the user   .
 timeout Optional. Normally this is not needed as the default should be adequate. Can be used to set how long the token is active for.                    
 impersonate Optional. A service account package is able to impersonate another user. This is the email address of whom to impersonate. Only relevant for service accounts.

One off credentials set up

Goa needs the credentials package to be stored in the property store to create a dialog, or to refresh an access token automatically if it expires. GoaApp provides a function to set these. Firstly these should be obtained from the App dashboard of the service you want to use. 

This example shows the App dashboard for Microsoft Live, to allow the use of OneDrive from Apps Script, from which you can  get the client id and client secret.

 Here is how to set up the package. This should be executed once. You can then  remove it from your script to avoid having credentials stored in scripts you might want to share with others.

 var propertyStore = PropertiesService.getScriptProperties();

 cGoa.GoaApp.setPackage (propertyStore , {  
    clientId : "0-------3",
    clientSecret : "N----------EM",
    scopes : ["wl.signin","wl.basic","wl.offline_access","wl.skydrive_update"],
    service: 'live',
    packageName: 'onedrive'

Package properties.

A package has a number of  properties which are maintained by Goa, but these are the most common properties you can set with setPackage.

 property purpose  
 packageName A package is the credentials , service, scope and control data used to authenticate. You should give each package a unique name
 clientIdThe id from the service's app dashboard. Some services have names other than clientId (such as appId), but you should set the clientId with the value from the service's dashboard. If you are using a service account, this does not need to be provided.
 clientSecretThe secret from the service's app dashboard.  If you are using a service account, this does not need to be provided .         
 scopesAn array of scopes which define the specific types of access required to the service. Each service has a different list and format of scopes. They should be entered here as an array of strings. If a service doesnt use scopes, just put an empty array here ([]).
 service This is the name of service (as it is known by Goa).  Currently known service names can be obtained here. The service name for Microsoft is 'live'    
fields for service account Optional. If you are using a service account in place of the normal web OAuth2 flow, these need an additional set of properties such as encryption keys. To avoid adding them manually, a function is available to set them from the service account JSON file which can be downloaded from the Developer Console when the service account is first created by simply supplying the fileid of the downloaded JSON.file as below. In this case only the package name, service name and scopes are needed. Client ID and Client Secret are extracted from the JSON key file. Note that your DriveApp is passed as an argument. This avoids an unnecessary scope requirement for users of this library who don't need to use service accounts.

cGoa.GoaApp.setPackage (propertyStore , cGoa.GoaApp.createServiceAccount (DriveApp , {
    packageName: 'DriverDatastore_serviceaccount',
    scopes : cGoa.GoaApp.scopesGoogleExpand (['datastore','userinfo.email']),

Now you can use Goa to manage OAuth2 for this script by simply providing the property store and package name.

For more like this, see Oauth2 for Apps Script in a few lines of code. Why not join our forumfollow the blog or follow me on twitter to ensure you get updates when they are available. 

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'ReillyAmazon 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.