Merge pull request #155 from gsuitedevs/params

Add support for custom callback parameters.

Author: Eric Koleda

README.md

@@ -325,6 +325,39 @@ if (service.hasAccess()) {
 Note that calling `Service.reset()` will remove all custom values from storage,
 in addition to the token.
 
+#### Passing additional parameters to the callback function
+
+There are occasionally cases where you need to preserve some data through the
+OAuth flow, so that it is available in your callback function. Although you
+could use the token storage mechanism discussed above for that purpose, writing
+to the PropertiesService is expensive and not neccessary in the case where the
+user doesn't start or fails to complete the OAuth flow.
+
+As an alternative you can store small amounts of data in the OAuth2 `state`
+token, which is a standard mechanism for this purpose. To do so, pass an
+optional hash of parameter names and values to the `getAuthorizationUrl()`
+method:
+
+```js
+var authorizationUrl = getService().getAuthorizationUrl({
+  // Pass the additional parameter "lang" with the value "fr".
+  lang: 'fr'
+});
+```
+
+These values will be stored along-side Apps Script's internal information in the
+encypted `state` token, which is passed in the authorization URL and passed back
+to the redirect URI. The `state` token is automatically decrypted in the
+callback function and you can access your parameters using the same
+`request.parameter` field used in web apps:
+
+```js
+function authCallback(request) {
+  var lang = request.parameter.lang;
+  // ...
+}
+```
+
 #### Using service accounts
 
 This library supports the service account authorization flow, also known as the

src/Service.js

@@ -306,9 +306,11 @@ Service_.prototype.setGrantType = function(grantType) {
  * have the user visit this URL and approve the authorization request. The
  * user will then be redirected back to your application using callback function
  * name specified, so that the flow may continue.
+ * @param {Object} optAdditionalParameters Additional parameters that should be
+ *     stored in the state token and made available in the callback function.
  * @return {string} The authorization URL.
  */
-Service_.prototype.getAuthorizationUrl = function() {
+Service_.prototype.getAuthorizationUrl = function(optAdditionalParameters) {
   validate_({
     'Client ID': this.clientId_,
     'Script ID': this.scriptId_,
@@ -317,16 +319,20 @@ Service_.prototype.getAuthorizationUrl = function() {
   });
 
   var redirectUri = getRedirectUri(this.scriptId_);
-  var state = eval('Script' + 'App').newStateToken()
+  var stateTokenBuilder = eval('Script' + 'App').newStateToken()
       .withMethod(this.callbackFunctionName_)
       .withArgument('serviceName', this.serviceName_)
-      .withTimeout(3600)
-      .createToken();
+      .withTimeout(3600);
+  if (optAdditionalParameters) {
+    Object.keys(optAdditionalParameters).forEach(function(key) {
+      stateTokenBuilder.withArgument(key, optAdditionalParameters[key]);
+    });
+  }
   var params = {
     client_id: this.clientId_,
     response_type: 'code',
     redirect_uri: redirectUri,
-    state: state
+    state: stateTokenBuilder.createToken()
   };
   params = extend_(params, this.params_);
   return buildUrl_(this.authorizationBaseUrl_, params);

src/Utilities.js

@@ -42,7 +42,7 @@ function validate_(params) {
   Object.keys(params).forEach(function(name) {
     var value = params[name];
     if (!value) {
-      throw Utilities.formatString('%s is required.', name);
+      throw new Error(name + ' is required.');
     }
   });
 }

test/mocks/script.js

@@ -0,0 +1,34 @@
+var MockScriptApp = function() {};
+
+MockScriptApp.prototype.getScriptId = function() {
+  return Math.random().toString(36).substring(2);
+};
+
+MockScriptApp.prototype.newStateToken = function() {
+  return new MockStateTokenBuilder();
+};
+
+var MockStateTokenBuilder = function() {
+  this.arguments = {};
+};
+
+MockStateTokenBuilder.prototype.withMethod = function(method) {
+  this.method = method;
+  return this;
+};
+
+MockStateTokenBuilder.prototype.withArgument = function(key, value) {
+  this.arguments[key] = value;
+  return this;
+};
+
+MockStateTokenBuilder.prototype.withTimeout = function(timeout) {
+  this.timeout = timeout;
+  return this;
+};
+
+MockStateTokenBuilder.prototype.createToken = function() {
+  return JSON.stringify(this);
+};
+
+module.exports = MockScriptApp;

test/test.js

@@ -4,14 +4,11 @@ var MockUrlFetchApp = require('./mocks/urlfetchapp');
 var MockProperties = require('./mocks/properties');
 var MockCache = require('./mocks/cache');
 var MockLock = require('./mocks/lock');
+var MockScriptApp = require('./mocks/script');
 var Future = require('fibers/future');
 
 var mocks = {
-  ScriptApp: {
-    getScriptId: function() {
-      return '12345';
-    }
-  },
+  ScriptApp: new MockScriptApp(),
   UrlFetchApp: new MockUrlFetchApp(),
   Utilities: {
     base64Encode: function(data) {
@@ -405,6 +402,32 @@ describe('Service', function() {
       service.exchangeGrant_();
     });
   });
+
+  describe('#getAuthorizationUrl()', function() {
+    it('should add additional parameters to the state token', function() {
+      var service = OAuth2.createService('test')
+          .setAuthorizationBaseUrl('http://www.example.com')
+          .setClientId('abc')
+          .setClientSecret('def')
+          .setCallbackFunction('authCallback');
+      var authorizationUrl = service.getAuthorizationUrl({
+        foo: 'bar'
+      });
+
+      // Extract the state token from the URL and parse it. For example, the
+      // URL http://www.example.com?state=%7B%22a%22%3A1%7D would produce
+      // {a: 1}.
+      var querystring = authorizationUrl.split('?')[1];
+      var params = querystring.split('&').reduce(function(result, pair) {
+        var parts = pair.split('=').map(decodeURIComponent);
+        result[parts[0]] = parts[1];
+        return result;
+      }, {});
+      var state = JSON.parse(params.state);
+
+      assert.equal(state.arguments.foo, 'bar');
+    });
+  });
 });
 
 describe('Utilities', function() {