How to customize the consent screen

This describes how to customize a consent screen using the Goa library as described in Oauth2 for Apps Script in a few lines of code (which you should read first for background).

Page Content hide
1 What is a consent screen ?
2 Providing your own consent screen
3 Consent screen parameters
4 Where to put it?
5 Share with your network

What is a consent screen ?

This is used to get permission to go ahead and authenticate with the OAuth2 provider, and looks like this by default. It is rendered in response to goa.getConsent();

Providing your own consent screen

You can create your own consent screen by simply providing a function that generates the html string.
Here is the default.
/**
   * the standard consent screen
   * these parameters can be used to consreuct a consent screen
   * it must at a mimum contain a clickable line to the consentUrl
   * @param {string} consentUrl the consent URL
   * @param {string} redirect Url the redirect URL
   * @param {string} packageName the pckage name
   * @param {string} serviceName the service name
   * @param {boolean} offline whether offline access is allowed
   * @return {string} the html code for a consent screen
   */
  goaApp.defaultConsentScreen = function  (consentUrl,redirectUrl,packageName,serviceName,offline) {
    
    return '<link rel="stylesheet" href="https://ssl.gstatic.com/docs/script/css/add-ons1.css">' + 
      '<style>aside {font-size:.8em;} .strip {margin:10px;} .gap {margin-top:20px;} </style>' +
      '<script>' +
        'function handleCon(con) { ' +
          'var o=document.getElementById("conAnchor");' +
          'var newUrl=o.href.toString().replace(/access_type=\\w+/, "access_type=" + (con.checked ? "off" :"on") + "line");' +
          'o.setAttribute ("href", newUrl);' +
        '}' +
      '</script>' +
      '<div class="strip">' +

        '<h3>Goa has detected that authentication is required for a ' + serviceName + ' service</h3>' + 
          
        '<div class="block"></div>' +
        '<div><label for="redirect">Redirect URI (for the developers console)</label></div>' + 
        '<div><input class="redirect" type="text" id="redirect" value="' + redirectUrl + '" disabled size=' + redirectUrl.length + '></div>' +

        '<div class="gap">' +
          '<div><label><input type="checkbox" onclick="handleCon(this);"' + 
            (offline ? ' checked' : '') + '>Allow ' + packageName + ' to always access this resource in the future ?</label></div>' + 
        '</div>' +
          
        '<div class="gap">' +
          '<div><label for="start">Please provide your consent to start authentication for ' + packageName + '</label></div>' + 
        '</div>' +
          
        '<div class="gap">' +
          '<a href = "' + consentUrl + '" target="_parent" id="conAnchor"><button id="start" class="action">Start</button></a>' +
        '</div>' +
          
        '<div class="gap">' +
            '<aside>For more information on Goa see <a href="https://ramblings.mcpher.com/oauth2-for-apps-script-in-a-few-lines-of-code/migrating-from-cezyoauth2/trying-to-like-oauth2">Desktop Liberation</aside>'+ 
        '</div>' + 
       '</div>'
  };

It can be overridden like this.

goa.setConsentScreen (function (consentUrl , redirectUrl , packageName, serviceName, offline) { ... return your own code; } );

Consent screen parameters

The consent function receives these arguments, which should  be useful in building a consent screen. At a minimum, the consent screen should provide a clickable link to consentUrl, which kicks off the providers OAuth2 dialog.

 property  purpose  
 consentUrl The link to the OAuth2 dialog. Must be rendered as a clickable item on the consent screen.
 redirectUrl Can be shown as a prompt to add to the App Dashboard redirect uri.
 packageName The credentials package name from which this dialog is generated.
 serviceName The service that is being used.
 offline  whether to allow automatic refreshing (true is refreshing is allowed)
Here’s how they map to the default consent screen.

Where to put it?

It’s possible that your script will be executed a couple of times depending on the authentication state at the time you run it. If you are changing the consent screen you need to do it after a goa is instantiated, but before execute() is run. Note that setConsentScreen simply declares a function that is able to generate a consent screen and which is expecting to receive parameters about the authentication account. An example of one is available in goaApp.defaultConsentScreen, and you should use this as your template.
  • Copy goaApp.defaultConsentScreen to your project and call it myConsentScreen.
  • Modify it as required, but be careful to retain the start button and the script info.
  • Override the consent screen with yours using a pattern like the one below
var goa = cGoa.GoaApp
  .createGoa('asanaCredentials',PropertiesService.getScriptProperties())
  .setConsentScreen(myConsent)
  .execute(e);

Note – for chaining as above, you’ll need v24 or above of Goa.

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.