Added service integration OAuth support

Author: Majid Mallis

CHANGELOG.md

@@ -6,9 +6,13 @@ See [DocuSign Support Center](https://support.docusign.com/en/releasenotes/) for
 ## [Unreleased]
 More information later on.
 
+## [3.2.0] - 2017-08-01
+### Added
+- Support for DocuSign JWT OAuth for service integration (2-legged authentication)
+ 
 ## [3.1.0] - 2017-06-17
 ### Added
-- Added support for DocuSign OAuth
+- Support for DocuSign OAuth
 
 ## [3.0.0] - 2017-03-10
 ### BREAKING

README.md

@@ -146,6 +146,7 @@ Run this script using node command
 ```javascript
 var docusign = require('docusign-esign');
 var async = require('async');
+var path = require('path');
 
 var integratorKey = '***';                    // Integrator Key associated with your DocuSign Integration
 var email = 'YOUR_EMAIL';                     // Email for your DocuSign Account
@@ -157,23 +158,31 @@ var templateId = '***';                       // ID of the Template you want to
 var templateRoleName = '***';                 // Role Name of the Template
 
 var baseUrl = 'https://' + docusignEnv + '.docusign.net/restapi';
+var userId = 'YOUR_USER_ID';
+var oAuthBaseUrl = 'account-d.docusign.com'; // use account.docusign.com for Live/Production
+var redirectURI = 'https://www.docusign.com/api';
+var privateKeyFilename = 'keys/docusign_private_key.txt';
 
-// initialize the api client
 var apiClient = new docusign.ApiClient();
-apiClient.setBasePath(baseUrl);
-
-// create JSON formatted auth header
-var creds = JSON.stringify({
-  Username: email,
-  Password: password,
-  IntegratorKey: integratorKey
-});
-apiClient.addDefaultHeader('X-DocuSign-Authentication', creds);
-
-// assign api client to the Configuration object
-docusign.Configuration.default.setDefaultApiClient(apiClient);
 
 async.waterfall([
+  function initApiClient (next) {
+    apiClient.setBasePath(baseUrl);
+    // assign the api client to the Configuration object
+    docusign.Configuration.default.setDefaultApiClient(apiClient);
+    
+    // IMPORTANT NOTE:
+    // the first time you ask for a JWT access token, you should grant access by making the following call
+    // get DocuSign OAuth authorization url:
+    var oauthLoginUrl = apiClient.getJWTUri(integratorKey, redirectURI, oAuthBaseUrl);
+    // open DocuSign OAuth authorization url in the browser, login and grant access
+    console.log(oauthLoginUrl);
+    // END OF NOTE
+    
+    // configure the ApiClient to asynchronously get an access to token and store it
+    apiClient.configureJWTAuthorizationFlow(path.resolve(__dirname, privateKeyFilename), oAuthBaseUrl, integratorKey, userId, 3600, next);
+  },
+  
   function login (next) {
     // login call available off the AuthenticationApi
     var authApi = new docusign.AuthenticationApi();

package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusign-esign",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "DocuSign Node.js API client.",
   "license": "MIT",
   "main": "src/index.js",
@@ -40,6 +40,7 @@
   },
   "semistandard": {
     "globals": [
+      "before",
       "describe",
       "it"
     ],
@@ -50,6 +51,7 @@
     ]
   },
   "dependencies": {
+    "jsonwebtoken": "7.4.1",
     "passport-oauth2": "1.4.0",
     "superagent": "1.7.1"
   },

src/ApiClient.js

@@ -84,17 +84,17 @@
      */
     this.cache = true;
   };
-  
+
   /**
    * Sets the API endpoint base URL.
-   */  
+   */
   exports.prototype.setBasePath = function setBasePath(basePath) {
     this.basePath = basePath;
   };
 
   /**
    * Adds request headers to the API client. Useful for Authentication.
-   */  
+   */
   exports.prototype.addDefaultHeader = function addDefaultHeader(header, value) {
     this.defaultHeaders[header] = value;
   };
@@ -426,7 +426,7 @@
     if (accept) {
       request.accept(accept);
     }
-    
+
     var data;
     if (request.header['Accept'] === 'application/pdf') {
         request.buffer();
@@ -556,6 +556,68 @@
     }
   };
 
+  /**
+   * Helper method to build the OAuth JWT grant uri (used once to get a user consent for impersonation)
+   * @param clientId OAuth2 client ID
+   * @param redirectURI OAuth2 redirect uri
+   * @param oAuthBasePath DocuSign OAuth base path (account-d.docusign.com for the developer sandbox
+   * 			  and account.docusign.com for the production platform)
+   * @returns {string} the OAuth JWT grant uri as a String
+   */
+  exports.prototype.getJWTUri = function(clientId, redirectURI, oAuthBasePath) {
+    return "https://" + oAuthBasePath + "/oauth/auth" + "?" +
+      "response_type=code&" +
+      "client_id=" + encodeURIComponent(clientId) + "&" +
+      "scope=" + encodeURIComponent("signature+impersonation") + "&" +
+      "redirect_uri=" + encodeURIComponent(redirectURI);
+  };
+
+  /**
+   * Configures the current instance of ApiClient with a fresh OAuth JWT access token from DocuSign
+   * @param privateKeyFilename the filename of the RSA private key
+   * @param oAuthBasePath DocuSign OAuth base path (account-d.docusign.com for the developer sandbox
+   *   			and account.docusign.com for the production platform)
+   * @param clientId DocuSign OAuth Client Id (AKA Integrator Key)
+   * @param userId DocuSign user Id to be impersonated (This is a UUID)
+   * @param expiresIn in seconds for the token time-to-live
+   * @param callback the callback function.
+   */
+  exports.prototype.configureJWTAuthorizationFlow = function(privateKeyFilename, oAuthBasePath, clientId, userId, expiresIn, callback) {
+    var _this = this;
+    var jwt = require('jsonwebtoken')
+      , fs  = require('fs')
+      , private_key = fs.readFileSync(privateKeyFilename)
+      , now         = Math.floor(Date.now() / 1000)
+      , later       = now + expiresIn;
+
+    var jwt_payload = {
+      iss: clientId,
+      sub: userId,
+      aud: oAuthBasePath,
+      iat: now,
+      exp: later,
+      scope: "signature"
+    };
+
+    var assertion = jwt.sign(jwt_payload, private_key, {algorithm: 'RS256'});
+
+    superagent('post', 'https://' + oAuthBasePath + '/oauth/token')
+      .timeout(this.timeout)
+      .set('Content-Type', 'application/x-www-form-urlencoded')
+      .send({
+        'assertion': assertion,
+        'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer'
+      })
+      .end(function(err, res) {
+        if (callback) {
+          if (!err && res.body && res.body.access_token) {
+            _this.addDefaultHeader('Authorization', 'Bearer ' + res.body.access_token);
+          }
+          callback(err, res);
+        }
+      });
+  };
+
   /**
    * The default API client implementation.
    * @type {module:ApiClient}

test-config.json

@@ -1,12 +1,11 @@
 {
-  "integratorKey": "SAND-7c8746af-XXXX-XXXX-XXXX-fc10861ef45b",
+  "integratorKey": "ae30ea4e-xxxx-xxxx-xxxx-fcb57d2dc4df",
   "apiEnv": "demo",
   "debug": false,
   "email": "[email protected]",
   "noSigEmail": "[email protected]",
   "userId": "fcc5726c-xxxx-xxxx-xxxx-40bbbe6ca126",
   "noSigUserId": "538241a0-xxxx-xxxx-xxxx-48aef23da8c4",
-  "password": "{PASSWORD}",
   "templateId": "cf2a46c2-xxxx-xxxx-xxxx-752547b1a419",
   "templateRole": "bob"
 }

test/SdkUnitTests.js

@@ -1,9 +1,9 @@
 var assert = require('assert');
 var docusign = require('../src/index');
 var config = require('../test-config.json');
+var path = require('path');
 
 var UserName = config.email;
-var Password = config.password;
 var IntegratorKey = config.integratorKey;
 var TemplateId = config.templateId;
 
@@ -12,13 +12,27 @@ var BaseUrl = 'https://demo.docusign.net/restapi';
 var SignTest1File = 'docs/SignTest1.pdf';
 var accountId = '';
 var envelopeId = '';
-var creds = '{"Username":"' + UserName + '","Password":"' + Password + '","IntegratorKey":"' + IntegratorKey + '"}';
-
-var apiClient = new docusign.ApiClient();
-apiClient.setBasePath(BaseUrl);
-apiClient.addDefaultHeader('X-DocuSign-Authentication', creds);
+var UserId = config.userId;
+var OAuthBaseUrl = 'account-d.docusign.com';
+var RedirectURI = 'https://www.docusign.com/api';
+var privateKeyFilename = 'keys/docusign_private_key.txt';
+
+describe('SDK Unit Tests:', function (done) {
+  var apiClient = new docusign.ApiClient();
+  before(function (done) {
+    apiClient.setBasePath(BaseUrl);
+    // IMPORTANT NOTE:
+    // the first time you ask for a JWT access token, you should grant access by making the following call
+    // get DocuSign OAuth authorization url:
+    var oauthLoginUrl = apiClient.getJWTUri(IntegratorKey, RedirectURI, OAuthBaseUrl);
+    // open DocuSign OAuth authorization url in the browser, login and grant access
+    console.log(oauthLoginUrl);
+    // END OF NOTE
+
+    // configure the ApiClient to asynchronously get an access to token and store it
+    apiClient.configureJWTAuthorizationFlow(path.resolve(__dirname, privateKeyFilename), OAuthBaseUrl, IntegratorKey, UserId, 3600, done);
+  });
 
-describe('SDK Unit Tests:', function () {
   it('login', function (done) {
     var authApi = new docusign.AuthenticationApi(apiClient);
     var loginOps = {};
@@ -53,7 +67,6 @@ describe('SDK Unit Tests:', function () {
     var fileBytes = null;
     try {
       var fs = require('fs');
-      var path = require('path');
       // read file from a local directory
       fileBytes = fs.readFileSync(path.resolve(__dirname, SignTest1File));
     } catch (ex) {
@@ -167,7 +180,6 @@ describe('SDK Unit Tests:', function () {
     var fileBytes = null;
     try {
       var fs = require('fs');
-      var path = require('path');
       // read file from a local directory
       fileBytes = fs.readFileSync(path.resolve(__dirname, SignTest1File));
     } catch (ex) {
@@ -260,7 +272,6 @@ describe('SDK Unit Tests:', function () {
     var fileBytes = null;
     try {
       var fs = require('fs');
-      var path = require('path');
       // read file from a local directory
       fileBytes = fs.readFileSync(path.resolve(__dirname, SignTest1File));
     } catch (ex) {
@@ -331,7 +342,6 @@ describe('SDK Unit Tests:', function () {
     var fileBytes = null;
     try {
       var fs = require('fs');
-      var path = require('path');
       // read file from a local directory
       fileBytes = fs.readFileSync(path.resolve(__dirname, SignTest1File));
     } catch (ex) {
@@ -407,7 +417,6 @@ describe('SDK Unit Tests:', function () {
           if (pdfBytes) {
             try {
               var fs = require('fs');
-              var path = require('path');
               // download the document pdf
               var filename = accountId + '_' + envelopeSummary.envelopeId + '_combined.pdf';
               var tempFile = path.resolve(__dirname, filename);
@@ -445,7 +454,6 @@ describe('SDK Unit Tests:', function () {
     var fileBytes = null;
     try {
       var fs = require('fs');
-      var path = require('path');
       // read file from a local directory
       fileBytes = fs.readFileSync(path.resolve(__dirname, SignTest1File));
     } catch (ex) {
@@ -533,7 +541,6 @@ describe('SDK Unit Tests:', function () {
               if (pdfBytes) {
                 try {
                   var fs = require('fs');
-                  var path = require('path');
                   // download the document pdf
                   var filename = accountId + '_' + envelopeSummary.envelopeId + '_combined.pdf';
                   var tempFile = path.resolve(__dirname, filename);
@@ -560,7 +567,6 @@ describe('SDK Unit Tests:', function () {
                       if (diagBytes) {
                         try {
                           var fs = require('fs');
-                          var path = require('path');
                           // download the document pdf
                           var filename = requestLogId + '.txt';
                           var tempFile = path.resolve(__dirname, filename);

test/keys/docusign_private_key.txt

@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEogIBAAKCAQEAh0VLAZe6m36tbthAom/IRzxvm/i66mEpow9AsrFP3EAybtVw
+2s13RJ1f0ZJA4sB7SbOtRymIxLlVUWkZLW4NqtECrObqOuke+G2ROWfOhcAyMuiB
+lW44mvl8Gil+n6Lwif2+OtUQ88iwPuE6I7jKnBV82lNGDx3H1hqHl7wpQZRyRPCd
+zPCrh6TRHj1D40mvrUwqAptj5m71QKA9tWVAQQ1DGKJZVZI4mdz3+I1XCinF8zrx
+IUJyEtaJfCHiS086XF3Sw7DkU2o/QIIYbpxlf9Zdjr1QT6/ow7pwJbX2/GSQW2mV
+GSY0KSiPFVjbpjKBpVpd4vgnQqn10BzLvLNySwIDAQABAoIBAA2opAm9oeSYlneW
+U3RzeBQlWJm1tF39QKCL5jsE52z0eIMzfylAzPW7NFUrgOzEhc5r26fPXFWM5z4I
+sDejoLKqVyxRRr57EpsAKUVUI4ji3s7AJnGJxyJy5aKYpQYGhGZSnlY/dG5BSfaX
+dHDt9FttWgWLmgvltGt8k0txfvL1nYEQxXxE5gMKNKKoBXE8QF05BmpajApd+hhL
+rGLicYpqsrliXr818HvFEKS8ODYfN856osLsvBJDANEW9+OiRQ9QQs5qdStrA5IX
+35DktfSs5Tvr8ZkJksQyfIO4WmEVSJIkm00BL1oSWHAM0Zqv23u6H7HtmCBnvbpw
+DY33t+ECgYEA4r9rjODMNhuGgrktDsBE+IQcvoWiYiV00OipZzx0l1q3HmRB51Jo
+C/pQ+X6YHT3qZN263VksmlbzpvRQTeL97narhpW8ZdW/L0e6g9sOBchewItftfAJ
+CdXmzaaPHEzVu56YGwtS1QC6IVdomxgmXNNuUYgyHt6KgDpVuHBi3usCgYEAmLi/
+cLSnIHPT42WFf2IgQWxT7vcBxe4pL0zjzC4NSi8m//g/F/MpQfgsSjreEx5hE6+4
+tAh6J2MZwcejbdCgV6eES84fEGDDYGT3GV9qwCTp6Z374hjP+0ZeGcFnzZLsrPPc
+T5K/uaIH7n2dPzNe3aLCslnpStVIUz60mnusoiECgYAUk2A0EXYWdtr248zV6NaZ
+YoulMkUw+Msn5eTxbEf8MAwr4tckIZM1ewp8CWPOS38IliJN0bi9bKSBguwClVWL
+nRMljFLjPskxhiXDr04PckY+3KbbwKNhVBq0kKet3r8KXnLZCWcD0yQQwHjKkh9x
+DvKUzXIW4QTaa/C5YuFl7wKBgHDF68fD/q1+GncOXnfj88GbxpbtGwgXh53//y6k
+yvd+viPCIoUC7/Jg2gOuWJJxmmm5FoEKyXkQOtLXIp1SszRG5PA9Mr8bVOp3Y+f+
+h4t/NqNmH7ujauE34wDNymMJHW/RW1v/F0hyl7zKUTV8L48mQvMEZbr2p8OgyChT
+LvVBAoGAFPjp50Q3vaZ1aghIjCfSoi0eU5tVbMCAXpwrjLkCGkw8r6U1ILQyMvqw
+E57cqoj2hsZ3P7qgQvZox1L7THnAKNYIdM/tj444QmsYudC5wp5hZBEzmmwbIeq8
+3h4V9F7T/1PamwfRhZC3t4wf327HEMu0pZlwARWpuxh4eaXumYM=
+-----END RSA PRIVATE KEY-----

test/keys/docusign_public_key.txt

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAh0VLAZe6m36tbthAom/I
+Rzxvm/i66mEpow9AsrFP3EAybtVw2s13RJ1f0ZJA4sB7SbOtRymIxLlVUWkZLW4N
+qtECrObqOuke+G2ROWfOhcAyMuiBlW44mvl8Gil+n6Lwif2+OtUQ88iwPuE6I7jK
+nBV82lNGDx3H1hqHl7wpQZRyRPCdzPCrh6TRHj1D40mvrUwqAptj5m71QKA9tWVA
+QQ1DGKJZVZI4mdz3+I1XCinF8zrxIUJyEtaJfCHiS086XF3Sw7DkU2o/QIIYbpxl
+f9Zdjr1QT6/ow7pwJbX2/GSQW2mVGSY0KSiPFVjbpjKBpVpd4vgnQqn10BzLvLNy
+SwIDAQAB
+-----END PUBLIC KEY-----