Merge branch 'master' into locking

Author: Eric Koleda

README.md

@@ -31,12 +31,13 @@ in your manifest file, ensure that the following scope is included:
 ## Redirect URI
 
 Before you can start authenticating against an OAuth2 provider, you usually need
-to register your application with that OAuth2 provider and obtain a client ID and secret. Often
-a provider's registration screen requires you to enter a "Redirect URI", which is the
-URL that the user's browser will be redirected to after they've authorized access to their account at that provider. 
+to register your application with that OAuth2 provider and obtain a client ID
+and secret. Often a provider's registration screen requires you to enter a
+"Redirect URI", which is the URL that the user's browser will be redirected to
+after they've authorized access to their account at that provider.
 
-For this library (and the Apps Script functionality in general) the URL will always
-be in the following format:
+For this library (and the Apps Script functionality in general) the URL will
+always be in the following format:
 
  https://script.google.com/macros/d/{SCRIPT ID}/usercallback
 
@@ -350,8 +351,15 @@ headers.
 
 The most common of these is the `client_credentials` grant type, which often
 requires that the client ID and secret are passed in the Authorization header.
-See the sample [`TwitterAppOnly.gs`](samples/TwitterAppOnly.gs) for more
-information.
+When using this grant type, if you set a client ID and secret using
+`setClientId()` and `setClientSecret()` respectively then an
+`Authorization: Basic ...` header will be added to the token request
+automatically, since this is what most OAuth2 providers require. If your
+provider uses a different method of authorization then don't set the client ID
+and secret and add an authorization header manually.
+
+See the sample [`TwitterAppOnly.gs`](samples/TwitterAppOnly.gs) for a working
+example.
 
 
 ## Compatibility

samples/Domo.gs

@@ -41,15 +41,13 @@ function getService() {
  // Set the endpoint URLs.
  .setTokenUrl('https://api.domo.com/oauth/token')
 
+ // Set the client ID and secret.
+ .setClientId(CLIENT_ID)
+ .setClientSecret(CLIENT_SECRET)
+
  // Sets the custom grant type to use.
  .setGrantType('client_credentials')
 
- // Sets the required Authorization header.
- .setTokenHeaders({
- Authorization: 'Basic ' +
- Utilities.base64Encode(CLIENT_ID + ':' + CLIENT_SECRET)
- })
-
  // Set the property store where authorized tokens should be persisted.
  .setPropertyStore(PropertiesService.getUserProperties());
 }

samples/TwitterAppOnly.gs

@@ -43,15 +43,13 @@ function getService() {
  // Set the endpoint URLs.
  .setTokenUrl('https://api.twitter.com/oauth2/token')
 
+ // Set the client ID and secret.
+ .setClientId(CLIENT_ID)
+ .setClientSecret(CLIENT_SECRET)
+
  // Sets the custom grant type to use.
  .setGrantType('client_credentials')
 
- // Sets the required Authorization header.
- .setTokenHeaders({
- Authorization: 'Basic ' +
- Utilities.base64Encode(CLIENT_ID + ':' + CLIENT_SECRET)
- })
-
  // Set the property store where authorized tokens should be persisted.
  .setPropertyStore(PropertiesService.getUserProperties());
 }

src/OAuth2.js

@@ -64,8 +64,8 @@ function createService(serviceName) {
  * @return {string} The redirect URI.
  */
 function getRedirectUri(scriptId) {
- return Utilities.formatString(
- 'https://script.google.com/macros/d/%s/usercallback', scriptId);
+ return 'https://script.google.com/macros/d/' + encodeURIComponent(scriptId) +
+  '/usercallback';
 }
 
 if (typeof module === 'object') {

src/Service.js

@@ -713,8 +713,8 @@ Service_.prototype.lockable_ = function(func) {
 
 /**
  * Obtain an access token using the custom grant type specified. Most often
- * this will be "client_credentials", in which case make sure to also specify an
- * Authorization header if required by your OAuth provider.
+ * this will be "client_credentials", and a client ID and secret are set an
+ * "Authorization: Basic ..." header will be added using those values.
  */
 Service_.prototype.exchangeGrant_ = function() {
  validate_({
@@ -725,6 +725,20 @@ Service_.prototype.exchangeGrant_ = function() {
  grant_type: this.grantType_
  };
  payload = extend_(payload, this.params_);
+
+ // For the client_credentials grant type, add a basic authorization header:
+ // - If the client ID and client secret are set.
+ // - No authorization header has been set yet.
+ var lowerCaseHeaders = toLowerCaseKeys_(this.tokenHeaders_);
+ if (this.grantType_ === 'client_credentials' &&
+ this.clientId_ &&
+ this.clientSecret_ &&
+ (!lowerCaseHeaders || !lowerCaseHeaders.authorization)) {
+ this.tokenHeaders_ = this.tokenHeaders_ || {};
+ this.tokenHeaders_.authorization = 'Basic ' +
+ Utilities.base64Encode(this.clientId_ + ':' + this.clientSecret_);
+ }
+
  var token = this.fetchToken_(payload);
  this.saveToken_(token);
 };

src/Storage.js

@@ -40,6 +40,13 @@ function Storage_(prefix, properties, optCache) {
  */
 Storage_.CACHE_EXPIRATION_TIME_SECONDS = 21600; // 6 hours.
 
+/**
+ * The special value to use in the cache to indicate that there is no value.
+ * @type {string}
+ * @private
+ */
+Storage_.CACHE_NULL_VALUE = '__NULL__';
+
 /**
  * Gets a stored value.
  * @param {string} key The key.
@@ -48,21 +55,27 @@ Storage_.CACHE_EXPIRATION_TIME_SECONDS = 21600; // 6 hours.
  * @return {*} The stored value.
  */
 Storage_.prototype.getValue = function(key, optSkipMemoryCheck) {
+ var prefixedKey = this.getPrefixedKey_(key);
+ var jsonValue;
+ var value;
+
  if (!optSkipMemoryCheck) {
  // Check in-memory cache.
- if (this.memory_[key]) {
- return this.memory_[key];
+ if (value = this.memory_[key]) {
+ if (value === Storage_.CACHE_NULL_VALUE) {
+ return null;
+ }
+ return value;
  }
  }
 
- var prefixedKey = this.getPrefixedKey_(key);
- var jsonValue;
- var value;
-
  // Check cache.
  if (this.cache_ && (jsonValue = this.cache_.get(prefixedKey))) {
  value = JSON.parse(jsonValue);
  this.memory_[key] = value;
+ if (value === Storage_.CACHE_NULL_VALUE) {
+ return null;
+ }
  return value;
  }
 
@@ -77,7 +90,13 @@ Storage_.prototype.getValue = function(key, optSkipMemoryCheck) {
  return value;
  }
 
- // Not found.
+ // Not found. Store a special null value in the memory and cache to reduce
+ // hits on the PropertiesService.
+ this.memory_[key] = Storage_.CACHE_NULL_VALUE;
+ if (this.cache_) {
+ this.cache_.put(prefixedKey, JSON.stringify(Storage_.CACHE_NULL_VALUE),
+ Storage_.CACHE_EXPIRATION_TIME_SECONDS);
+ }
  return null;
 };
 

src/Utilities.js

@@ -76,3 +76,22 @@ function extend_(destination, source) {
  }
  return destination;
 }
+
+/* exported toLowerCaseKeys_ */
+/**
+ * Gets a copy of an object with all the keys converted to lower-case strings.
+ *
+ * @param {Object} obj The object to copy.
+ * @return {Object} a shallow copy of the object with all lower-case keys.
+ */
+function toLowerCaseKeys_(obj) {
+ if (obj === null || typeof obj !== 'object') {
+ return obj;
+ }
+ // For each key in the source object, add a lower-case version to a new
+ // object, and return it.
+ return Object.keys(obj).reduce(function(result, k) {
+ result[k.toLowerCase()] = obj[k];
+ return result;
+ }, {});
+}

test/mocks/urlfetchapp.js

@@ -12,7 +12,7 @@ var MockUrlFetchApp = function() {
 
 MockUrlFetchApp.prototype.fetch = function(url, optOptions) {
  var delay = this.delayFunction();
- var result = this.resultFunction();
+ var result = this.resultFunction(url, optOptions);
  if (delay) {
  sleep(delay).wait();
  }

test/test.js

@@ -13,6 +13,11 @@ var mocks = {
  }
  },
  UrlFetchApp: new MockUrlFetchApp(),
+ Utilities: {
+ base64Encode: function(data) {
+ return Buffer.from(data).toString('base64');
+ }
+ },
  __proto__: gas.globalMockDefault
 };
 var OAuth2 = gas.require('./src', mocks);
@@ -108,6 +113,37 @@ describe('Service', function() {
 
  assert.deepEqual(service.getToken(true), newToken);
  });
+
+ it('should load null tokens from the cache',
+ function() {
+ var cache = new MockCache();
+ var properties = new MockProperties();
+ for (var i = 0; i < 10; ++i) {
+ var service = OAuth2.createService('test')
+ .setPropertyStore(properties)
+ .setCache(cache);
+ service.getToken();
+ }
+ assert.equal(properties.counter, 1);
+ });
+
+ it('should load null tokens from memory',
+ function() {
+ var cache = new MockCache();
+ var properties = new MockProperties();
+ var service = OAuth2.createService('test')
+ .setPropertyStore(properties)
+ .setCache(cache);
+
+ service.getToken();
+ var cacheStart = cache.counter;
+ var propertiesStart = properties.counter;
+ for (var i = 0; i < 10; ++i) {
+ service.getToken();
+ }
+ assert.equal(cache.counter, cacheStart);
+ assert.equal(properties.counter, propertiesStart);
+ });
  });
 
  describe('#saveToken_()', function() {
@@ -294,6 +330,81 @@ describe('Service', function() {
  });
  });
  });
+
+ describe('#exchangeGrant_()', function() {
+ var toLowerCaseKeys_ = OAuth2.toLowerCaseKeys_;
+
+ it('should not set auth header if the grant type is not client_credentials',
+ function(done) {
+ mocks.UrlFetchApp.resultFunction = function(url, urlOptions) {
+ assert.isUndefined(toLowerCaseKeys_(urlOptions.headers).authorization);
+ done();
+ };
+ var service = OAuth2.createService('test')
+ .setGrantType('fake')
+ .setTokenUrl('http://www.example.com');
+ service.exchangeGrant_();
+ });
+
+ it('should not set auth header if the client ID is not set',
+ function(done) {
+ mocks.UrlFetchApp.resultFunction = function(url, urlOptions) {
+ assert.isUndefined(toLowerCaseKeys_(urlOptions.headers).authorization);
+ done();
+ };
+ var service = OAuth2.createService('test')
+ .setGrantType('client_credentials')
+ .setTokenUrl('http://www.example.com');
+ service.exchangeGrant_();
+ });
+
+ it('should not set auth header if the client secret is not set',
+ function(done) {
+ mocks.UrlFetchApp.resultFunction = function(url, urlOptions) {
+ assert.isUndefined(toLowerCaseKeys_(urlOptions.headers).authorization);
+ done();
+ };
+ var service = OAuth2.createService('test')
+ .setGrantType('client_credentials')
+ .setTokenUrl('http://www.example.com')
+ .setClientId('abc');
+ service.exchangeGrant_();
+ });
+
+ it('should not set auth header if it is already set',
+ function(done) {
+ mocks.UrlFetchApp.resultFunction = function(url, urlOptions) {
+ assert.equal(toLowerCaseKeys_(urlOptions.headers).authorization,
+ 'something');
+ done();
+ };
+ var service = OAuth2.createService('test')
+ .setGrantType('client_credentials')
+ .setTokenUrl('http://www.example.com')
+ .setClientId('abc')
+ .setClientSecret('def')
+ .setTokenHeaders({
+ authorization: 'something'
+ });
+ service.exchangeGrant_();
+ });
+
+ it('should set the auth header for the client_credentials grant type, if ' +
+ 'the client ID and client secret are set and the authorization header' +
+ 'is not already set', function(done) {
+ mocks.UrlFetchApp.resultFunction = function(url, urlOptions) {
+ assert.equal(toLowerCaseKeys_(urlOptions.headers).authorization,
+ 'Basic YWJjOmRlZg==');
+ done();
+ };
+ var service = OAuth2.createService('test')
+ .setGrantType('client_credentials')
+ .setTokenUrl('http://www.example.com')
+ .setClientId('abc')
+ .setClientSecret('def');
+ service.exchangeGrant_();
+ });
+ });
 });
 
 describe('Utilities', function() {
@@ -313,4 +424,33 @@ describe('Utilities', function() {
  assert.deepEqual(o, {foo: [100], bar: 2, baz: {}});
  });
  });
+
+ describe('#toLowerCaseKeys_()', function() {
+ var toLowerCaseKeys_ = OAuth2.toLowerCaseKeys_;
+
+ it('should contain only lower-case keys', function() {
+ var data = {
+ 'a': true,
+ 'A': true,
+ 'B': true,
+ 'Cc': true,
+ 'D2': true,
+ 'E!@#': true
+ };
+ var lowerCaseData = toLowerCaseKeys_(data);
+ assert.deepEqual(lowerCaseData, {
+ 'a': true,
+ 'b': true,
+ 'cc': true,
+ 'd2': true,
+ 'e!@#': true
+ });
+ });
+
+ it('should handle null, undefined, and empty objects', function() {
+ assert.isNull(toLowerCaseKeys_(null));
+ assert.isUndefined(toLowerCaseKeys_(undefined));
+ assert.isEmpty(toLowerCaseKeys_({}));
+ });
+ });
 });