Add default behavior for client_credentials grant type.

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/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/Service.js

@@ -698,8 +698,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: Baseic ..." header will be added using thos values.
  */
 Service_.prototype.exchangeGrant_ = function() {
   validate_({
@@ -710,6 +710,19 @@ 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 and no authorization header has
+  // been set yet (AKA do the expected thing).
+  if (this.grantType_ === 'client_credentials' &&
+      this.clientId_ &&
+      this.clientSecret_ &&
+      !getValueCaseInsensitive_(this.tokenHeaders_, 'Authorization')) {
+    this.tokenHeaders_ = this.tokenHeaders_ || {};
+    this.tokenHeaders_.Authorization = 'Basic ' +
+        Utilities.base64Encode(this.clientId_ + ':' + this.clientSecret_);
+  }
+
   var token = this.fetchToken_(payload);
   this.saveToken_(token);
 };

src/Utilities.js

@@ -76,3 +76,27 @@ function extend_(destination, source) {
   }
   return destination;
 }
+
+/* exported getValueCaseInsensitive_ */
+/**
+ * Gets the value stored in the object under the given key, in a
+ * case-insensitive way.
+ * @param {Object} obj The object to search in.
+ * @param {string} key The key to search for.
+ * @return {Object} the value under that key, or undefined otherwise
+ */
+function getValueCaseInsensitive_(obj, key) {
+  if (obj == null || typeof obj !== 'object' ||
+      key == null || !key.toString) {
+    return undefined;
+  }
+  if (key in obj) {
+    return obj[key];
+  }
+  return Object.keys(obj).reduce(function(result, k) {
+    if (result) return result;
+    if (k.toLowerCase() === key.toLowerCase()) {
+      return obj[k];
+    }
+  }, undefined);
+}

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);
@@ -236,6 +241,82 @@ describe('Service', function() {
       });
     });
   });
+
+  describe('#exchangeGrant_()', function() {
+    var getValueCaseInsensitive_ = OAuth2.getValueCaseInsensitive_;
+
+    it('should not set auth header if the grant type is not client_credentials',
+        function(done) {
+      mocks.UrlFetchApp.resultFunction = function(url, urlOptions) {
+        assert.isUndefined(
+            getValueCaseInsensitive_(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(
+            getValueCaseInsensitive_(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(
+            getValueCaseInsensitive_(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(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(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() {
@@ -255,4 +336,35 @@ describe('Utilities', function() {
       assert.deepEqual(o, {foo: [100], bar: 2, baz: {}});
     });
   });
+
+  describe('#getValueCaseInsensitive_()', function() {
+    var getValueCaseInsensitive_ = OAuth2.getValueCaseInsensitive_;
+
+    it('should find identical keys', function() {
+      assert.isTrue(getValueCaseInsensitive_({'a': true}, 'a'));
+      assert.isTrue(getValueCaseInsensitive_({'A': true}, 'A'));
+      assert.isTrue(getValueCaseInsensitive_({'Ab': true}, 'Ab'));
+    });
+
+    it('should find matching keys of different cases', function() {
+      assert.isTrue(getValueCaseInsensitive_({'a': true}, 'A'));
+      assert.isTrue(getValueCaseInsensitive_({'A': true}, 'a'));
+      assert.isTrue(getValueCaseInsensitive_({'Ab': true}, 'aB'));
+      assert.isTrue(getValueCaseInsensitive_({'a2': true}, 'A2'));
+    });
+
+    it('should work with non-alphabetic keys', function() {
+      assert.isTrue(getValueCaseInsensitive_({'A2': true}, 'a2'));
+      assert.isTrue(getValueCaseInsensitive_({'2': true}, '2'));
+      assert.isTrue(getValueCaseInsensitive_({2: true}, 2));
+      assert.isTrue(getValueCaseInsensitive_({'!@#': true}, '!@#'));
+    });
+
+    it('should work null and undefined', function() {
+      assert.isUndefined(getValueCaseInsensitive_(null, 'key'));
+      assert.isUndefined(getValueCaseInsensitive_(undefined, 'key'));
+      assert.isUndefined(getValueCaseInsensitive_({'a': true}, null));
+      assert.isUndefined(getValueCaseInsensitive_({'a': true}, undefined));
+    });
+  });
 });