Added service integration OAuth support

Author: Majid Mallis

CHANGELOG.md

@@ -7,13 +7,18 @@ See [DocuSign Support Center](https://support.docusign.com/en/releasenotes/) for
 ### Changed
 - Updated the package with the latest API monthly release.
 
+
+## [2.3.0] - 2017-07-27
+### Added
+- Support for DocuSign JWT OAuth for service integration (2-legged authentication)
+
 ## [2.2.1] - 2017-07-13
 ### Fixed
-- unit tests under Java8 cmplain about AccessTokenListener being a nested class.
+- Unit tests under Java8 complain about AccessTokenListener being a nested class.
 
 ## [2.2.0] - 2017-06-17
 ### Added
-- Added support for DocuSign OAuth
+- Support for DocuSign 3-legged OAuth
 
 ## [2.1.0] - 2017-03-09
 ### Added

README.md

@@ -21,7 +21,7 @@ Add this dependency to your project's POM:
 <dependency>
    <groupId>com.docusign</groupId>
    <artifactId>docusign-esign-java</artifactId>
-   <version>2.2.1</version>
+   <version>2.3.0</version>
 </dependency>
 ```
 
@@ -30,7 +30,7 @@ Add this dependency to your project's POM:
 Add this dependency to your project's build file:
 
 ```groovy
-compile "com.docusign:docusign-esign-java:2.2.1"
+compile "com.docusign:docusign-esign-java:2.3.0"
 ```
 
 #### Dependencies
@@ -72,14 +72,14 @@ android {
 
 This client is available through the following Java package managers:
 
-- [Nexus Repository Manager](https://oss.sonatype.org/#nexus-search;quick~docusign-esign-java) (oss.sonatype.org). You can search for com.docusign or docusign-esign-java. The current version is 2.2.1.
-- [JFrog Bintray](https://bintray.com/dsdevcenter/maven/docusign-esign-java) (bintray.com). You can search for com.docusign or docusign-esign-java. The current version is 2.2.1.
+- [Nexus Repository Manager](https://oss.sonatype.org/#nexus-search;quick~docusign-esign-java) (oss.sonatype.org). You can search for com.docusign or docusign-esign-java. The current version is 2.3.0.
+- [JFrog Bintray](https://bintray.com/dsdevcenter/maven/docusign-esign-java) (bintray.com). You can search for com.docusign or docusign-esign-java. The current version is 2.3.0.
 
 ### Others
 
 Or you can manually download and add the following JARs to your project:
 
-* The [docusign-esign-java-2.2.1](https://github.com/docusign/docusign-java-client/releases/latest) JAR.
+* The [docusign-esign-java-2.3.0](https://github.com/docusign/docusign-java-client/releases/latest) JAR.
 * The [Dependency JARs](/target/lib) in /lib folder.
 
 
@@ -192,32 +192,40 @@ public class DocuSignExample {
 } 
 ```
 
-To send a signature request from a Template using username/password:
+To send a signature request from a Template using service integration:
 
 ```java
 import com.docusign.esign.api.*;
 import com.docusign.esign.client.*;
 import com.docusign.esign.model.*;
 
 import java.util.List;
+import java.io.IOException;
 
 public class DocuSignExample {
   public static void main(String[] args) {
-    String username = "[EMAIL]";
-    String password = "[PASSWORD]";
-    String integratorKey = "[INTEGRATOR_KEY]";
+    String OAuthBaseUrl = "account-d.docusign.com";
+    String BaseUrl = "https://demo.docusign.net/restapi";
+    String RedirectURI = "[OAUTH_REDIRECT_URI]";
+    String IntegratorKey = "[INTEGRATOR_KEY]";
+    String UserId = "[USER_ID_TO_SEND_ON_BEHALF]";
+    String publicKeyFilename = "[PATH_TO_RSA265_PUBLIC_KEY]";
+    String privateKeyFilename = "[PATH_TO_RSA265_PRIVATE_KEY]";
 
-    // initialize client for desired environment and add X-DocuSign-Authentication header
-    ApiClient apiClient = new ApiClient("https://demo.docusign.net/restapi");
+    ApiClient apiClient = new ApiClient(BaseUrl);
 
-    // configure 'X-DocuSign-Authentication' authentication header
-    String authHeader = "{\"Username\":\"" +  username + "\",\"Password\":\"" +  password + "\",\"IntegratorKey\":\"" +  integratorKey + "\"}";
-    // If you have an OAuth access token stored in a variable named 'access_token', let's say, then instead, you can set authHeader as following (notice the extra space after 'Bearer'):
-    // String authHeader = "{\"Bearer \":\"" +  access_token + "\"}";
-    apiClient.addDefaultHeader("X-DocuSign-Authentication", authHeader);
-    Configuration.setDefaultApiClient(apiClient);
-    try
-    {
+    try {
+      // 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:
+      //String oauthLoginUrl = apiClient.getJWTUri(IntegratorKey, RedirectURI, OAuthBaseUrl);
+      // open DocuSign OAuth authorization url in the browser, login and grant access
+      //Desktop.getDesktop().browse(URI.create(oauthLoginUrl));
+      // END OF NOTE
+      
+      apiClient.configureJWTAuthorizationFlow(publicKeyFilename, privateKeyFilename, OAuthBaseUrl, IntegratorKey, UserId, 3600); // request for a fresh JWT token valid for 1 hour
+      Configuration.setDefaultApiClient(apiClient);
+      
       /////////////////////////////////////////////////////////////////////////////////////////////////////////
       // STEP 1: AUTHENTICATE TO RETRIEVE ACCOUNTID & BASEURL         
       /////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -266,10 +274,10 @@ public class DocuSignExample {
 
       // call the createEnvelope() API
       EnvelopeSummary envelopeSummary = envelopesApi.createEnvelope(accountId, envDef);
-    }
-    catch (com.docusign.esign.client.ApiException ex)
-    {
+    } catch (ApiException ex) {
       System.out.println("Exception: " + ex);
+    } catch (Exception e) {
+      System.out.println("Exception: " + e.getLocalizedMessage());
     }
   }
 } 

build.gradle

@@ -2,7 +2,7 @@ apply plugin: 'idea'
 apply plugin: 'eclipse'
 
 group = 'com.docusign'
-version = '2.1.0'
+version = '2.3.0'
 
 buildscript {
     repositories {

pom.xml

@@ -5,7 +5,7 @@
   <artifactId>docusign-esign-java</artifactId>
   <packaging>jar</packaging>
   <name>docusign-esign-java</name>
-  <version>2.2.1</version>
+  <version>2.3.0</version>
   <description>The official DocuSign eSignature JAVA client is based on version 2 of the DocuSign REST API and provides libraries for JAVA application integration. It is recommended that you use this version of the library for new development.</description>
   <url>https://www.docusign.com/developer-center</url>
 
@@ -240,6 +240,13 @@
       <artifactId>org.apache.oltu.oauth2.client</artifactId>
       <version>${oltu-version}</version>
     </dependency>
+    
+    <!-- JWT signing and verifying -->
+    <dependency>
+	  <groupId>com.auth0</groupId>
+	  <artifactId>java-jwt</artifactId>
+	  <version>3.2.0</version>
+	</dependency>
 
     <!-- Base64 encoding that works in both JVM and Android -->
     <dependency>

src/main/java/com/docusign/esign/client/ApiClient.java

@@ -1,15 +1,18 @@
 package com.docusign.esign.client;
 
 import com.fasterxml.jackson.annotation.*;
+import com.fasterxml.jackson.core.JsonParseException;
 import com.fasterxml.jackson.databind.*;
 import com.fasterxml.jackson.datatype.joda.*;
 import com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider;
 
 import com.sun.jersey.api.client.Client;
 import com.sun.jersey.api.client.ClientResponse;
 import com.sun.jersey.api.client.GenericType;
+import com.sun.jersey.api.client.WebResource;
 import com.sun.jersey.api.client.config.DefaultClientConfig;
 import com.sun.jersey.api.client.filter.LoggingFilter;
+import com.sun.jersey.core.util.MultivaluedMapImpl;
 import com.sun.jersey.api.client.WebResource.Builder;
 
 import com.sun.jersey.multipart.FormDataMultiPart;
@@ -20,28 +23,29 @@
 import org.apache.oltu.oauth2.common.exception.OAuthSystemException;
 
 import javax.ws.rs.core.Response.Status.Family;
+import javax.ws.rs.core.UriBuilder;
 import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.MultivaluedMap;
 
 import java.util.Collection;
-import java.util.Collections;
 import java.util.Map;
 import java.util.Map.Entry;
 import java.util.HashMap;
 import java.util.List;
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.TimeZone;
-
 import java.net.URLEncoder;
-
 import java.io.File;
+import java.io.IOException;
 import java.io.UnsupportedEncodingException;
 
 import java.text.DateFormat;
 import java.text.SimpleDateFormat;
 
 import com.docusign.esign.client.auth.Authentication;
 import com.docusign.esign.client.auth.HttpBasicAuth;
+import com.docusign.esign.client.auth.JWTUtils;
 import com.docusign.esign.client.auth.ApiKeyAuth;
 import com.docusign.esign.client.auth.OAuth;
 import com.docusign.esign.client.auth.AccessTokenListener;
@@ -252,14 +256,20 @@ public void updateAccessToken() {
    * @param accessToken OAuth access token
    * @param expiresIn Validity period in seconds
    */
-  public void setAccessToken(String accessToken, Long expiresIn) {
+  public void setAccessToken(final String accessToken, Long expiresIn) {
     for (Authentication auth : authentications.values()) {
       if (auth instanceof OAuth) {
         ((OAuth) auth).setAccessToken(accessToken, expiresIn);
         return;
       }
     }
-    throw new RuntimeException("No OAuth2 authentication configured!");
+    addAuthorization("docusignAccessCode", new Authentication() {
+		@Override
+		public void applyToParams(List<Pair> queryParams, Map<String, String> headerParams) {
+			headerParams.put("Authorization", "Bearer " + accessToken);
+		}
+	});
+    //throw new RuntimeException("No OAuth2 authentication configured!");
   }
 
   /**
@@ -396,6 +406,65 @@ public void registerAccessTokenListener(AccessTokenListener accessTokenListener)
     }
   }
 
+  /**
+   * 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
+   * @return the OAuth JWT grant uri as a String
+   */
+  public String getJWTUri(String clientId, String redirectURI, String oAuthBasePath) {
+	  return UriBuilder.fromUri(oAuthBasePath)
+	  .scheme("https")
+	  .path("/oauth/auth")
+	  .queryParam("response_type", "code")
+	  .queryParam("scope", "signature%20impersonation")
+	  .queryParam("client_id", clientId)
+	  .queryParam("redirect_uri", redirectURI)
+	  .build().toString();
+  }
+  
+  /**
+   * Configures the current instance of ApiClient with a fresh OAuth JWT access token from DocuSign
+   * @param publicKeyFilename the filename of the RSA public key
+   * @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
+   * @throws IOException if there is an issue with either the public or private file 
+   * @throws ApiException if there is an error while exchanging the JWT with an access token
+   */
+  public void configureJWTAuthorizationFlow(String publicKeyFilename, String privateKeyFilename, String oAuthBasePath, String clientId, String userId, long expiresIn) throws IOException, ApiException {
+	  try {
+		  String assertion = JWTUtils.generateJWTAssertion(publicKeyFilename, privateKeyFilename, oAuthBasePath, clientId, userId, expiresIn);
+		  MultivaluedMap<String, String> form = new MultivaluedMapImpl();
+		  form.add("assertion", assertion);
+		  form.add("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer");
+	
+		  Client client = Client.create();
+		  WebResource webResource = client.resource("https://" + oAuthBasePath + "/oauth/token");
+		  ClientResponse response = webResource
+				    .type(MediaType.APPLICATION_FORM_URLENCODED_TYPE)
+				    .post(ClientResponse.class, form);
+	
+		  ObjectMapper mapper = new ObjectMapper();
+	      JsonNode responseJson = mapper.readValue(response.getEntityInputStream(), JsonNode.class);
+	      if (!responseJson.has("access_token") || !responseJson.has("expires_in")) {
+	    	  throw new ApiException("Error while requesting an access token: " + responseJson);
+	      }
+	      String accessToken = responseJson.get("access_token").asText();
+	      expiresIn = responseJson.get("expires_in").asLong();
+	      setAccessToken(accessToken, expiresIn);
+	  } catch (JsonParseException e) {
+		  throw new ApiException("Error while parsing the response for the access token.");
+	  } catch (JsonMappingException e) {
+		  throw e;
+	  } catch (IOException e) {
+		  throw e;
+	  }
+  }
+
   /**
    * Parse the given string into Date object.
    */