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