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).

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="http://ramblings.mcpher.com/Home/excelquirks/oauthtoo">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  
 consentUrlThe link to the OAuth2 dialog. Must be rendered as a clickable item on the consent screen.
 redirectUrlCan be shown as a prompt to add to the App Dashboard redirect uri.
 packageNameThe credentials package name from which this dialog is generated.
 serviceNameThe 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 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.




Comments