Add method to refresh a token using a refresh_token

src/auth/OAuthAuthenticator.js

@@ -179,6 +179,61 @@ OAuthAuthenticator.prototype.passwordGrant = function(userData, cb) {
   return this.oauthWithIDTokenValidation.create(params, data);
 };
 
+/**
+ * Sign in using a refresh token
+ *
+ * @method    refresh
+ * @memberOf  module:auth.OAuthAuthenticator.prototype
+ *
+ * @example <caption>
+ *   Given a refresh token from a previous authentication request
+ *   it will return a JSON with the access_token and id_token.
+ *   More information in the
+ *   <a href="https://auth0.com/docs/api/authentication#refresh-token">
+ *     API Docs
+ *   </a>.
+ * </caption>
+ *
+ * var data = {
+ *   client_id: '{CLIENT_ID}',  // Optional field.
+ *   refresh_token: '{REFRESH_TOKEN}',
+ * };
+ *
+ * auth0.oauth.refresh(data, function (err, userData) {
+ *   if (err) {
+ *     // Handle error.
+ *   }
+ *
+ *   console.log(userData);
+ * });
+ *
+ * @param   {Object}    userData                User credentials object.
+ * @param   {String}    userData.refresh_token  Refresh token.
+ *
+ * @return  {Promise|undefined}
+ */
+OAuthAuthenticator.prototype.refresh = function (userData, cb) {
+  var params = {
+    type: 'token'
+  };
+  var defaultFields = {
+    client_id: this.clientId,
+    grant_type: 'refresh_token'
+  };
+  var data = extend(defaultFields, userData);
+  if (!userData || typeof userData !== 'object') {
+    throw new ArgumentError('Missing user data object');
+  }
+  if (typeof data.refresh_token !== 'string'
+    || data.refresh_token.split().length === 0) {
+    throw new ArgumentError('refresh_token field is required');
+  }
+  if (cb && cb instanceof Function) {
+    return this.oauthWithIDTokenValidation.create(params, data, cb);
+  }
+  return this.oauthWithIDTokenValidation.create(params, data);
+};
+
 /**
  * Sign in using a social provider access token.
  *

src/auth/index.js

@@ -543,4 +543,39 @@ utils.wrapPropertyMethod(
  */
 utils.wrapPropertyMethod(AuthenticationClient, 'passwordGrant', 'oauth.passwordGrant');
 
+/**
+ * Sign in using a refresh token
+ *
+ * @method    refresh
+ * @memberOf  module:auth.OAuthAuthenticator.prototype
+ *
+ * @example <caption>
+ *   Given a refresh token from a previous authentication request
+ *   it will return a JSON with the access_token and id_token.
+ *   More information in the
+ *   <a href="https://auth0.com/docs/api/authentication#refresh-token">
+ *     API Docs
+ *   </a>.
+ * </caption>
+ *
+ * var data = {
+ *   client_id: '{CLIENT_ID}',  // Optional field.
+ *   refresh_token: '{REFRESH_TOKEN}',
+ * };
+ *
+ * auth0.oauth.refresh(data, function (err, userData) {
+ *   if (err) {
+ *     // Handle error.
+ *   }
+ *
+ *   console.log(userData);
+ * });
+ *
+ * @param   {Object}    userData                User credentials object.
+ * @param   {String}    userData.refresh_token  Refresh token.
+ *
+ * @return  {Promise|undefined}
+ */
+utils.wrapPropertyMethod(AuthenticationClient, 'refresh', 'oauth.refresh');
+
 module.exports = AuthenticationClient;

test/auth/oauth.tests.js

@@ -44,7 +44,7 @@ describe('OAuthAuthenticator', function() {
   });
 
   describe('instance', function() {
-    var methods = ['signIn', 'socialSignIn', 'passwordGrant', 'authorizationCodeGrant'];
+    var methods = ['signIn', 'socialSignIn', 'passwordGrant', 'authorizationCodeGrant', 'refresh'];
     var authenticator = new Authenticator(validOptions);
 
     methods.forEach(function(method) {
@@ -405,6 +405,109 @@ describe('OAuthAuthenticator', function() {
     });
   });
 
+  describe('#refresh', function () {
+    var path = '/oauth/token';
+    var userData = {
+      refresh_token: 'refresh_token'
+    };
+    beforeEach(function () {
+      this.authenticator = new Authenticator(validOptions);
+      this.request = nock(API_URL)
+        .post(path)
+        .reply(200);
+    });
+    it('should require an object as first argument', function () {
+      expect(this.authenticator.refresh)
+        .to.throw(ArgumentError, 'Missing user data object');
+    });
+    it('should require a refresh_token', function () {
+      var auth = this.authenticator;
+      var refresh = auth.refresh.bind(auth, {});
+      expect(refresh)
+        .to.throw(ArgumentError, 'refresh_token field is required');
+    });
+    it('should accept a callback', function (done) {
+      this
+        .authenticator
+        .refresh(userData, done.bind(null, null));
+    });
+    it('should return a promise when no callback is provided', function (done) {
+      this
+        .authenticator
+        .refresh(userData)
+        .then(done.bind(null, null))
+        .catch(done.bind(null, null));
+    });
+    it('should perform a POST request to ' + path, function (done) {
+      var request = this.request;
+      this
+        .authenticator
+        .refresh(userData)
+        .then(function () {
+          expect(request.isDone())
+            .to.be.true;
+          done();
+        })
+        .catch(done);
+    });
+    it('should include the user data in the request', function (done) {
+      nock.cleanAll();
+      var request = nock(API_URL)
+        .post(path, function (body) {
+          for (var property in userData) {
+            if (userData[property] !== body[property]) {
+              return false;
+            }
+          }
+          return true;
+        })
+        .reply(200);
+      this
+        .authenticator
+        .refresh(userData)
+        .then(function () {
+          expect(request.isDone())
+            .to.be.true;
+          done();
+        })
+        .catch(done);
+    });
+    it('should include the Auth0 client ID in the request', function (done) {
+      nock.cleanAll();
+      var request = nock(API_URL)
+        .post(path, function (body) {
+          return body.client_id === CLIENT_ID;
+        })
+        .reply(200);
+      this
+        .authenticator
+        .refresh(userData)
+        .then(function () {
+          expect(request.isDone())
+            .to.be.true;
+          done();
+        })
+        .catch(done);
+    });
+    it('should use refresh_token as default grant type', function (done) {
+      nock.cleanAll();
+      var request = nock(API_URL)
+        .post(path, function (body) {
+          return body.grant_type === 'refresh_token';
+        })
+        .reply(200);
+      this
+        .authenticator
+        .refresh(userData)
+        .then(function () {
+          expect(request.isDone())
+            .to.be.true;
+          done();
+        })
+        .catch(done);
+    });
+  });
+
   describe('#socialSignIn', function() {
     var path = '/oauth/access_token';
     var userData = {