Add support for custom callback parameters.

Author: Eric Koleda

README.md

@@ -325,6 +325,38 @@ 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({
+  lang: 'fr'
+});
+```
+
+These values will be stored along-side Apps Script's internal information in the
+cryptographically secure `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);