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_({}));
+    });
+  });
 });