DocuSign integration using OAuth 2.0 authentication and JWT

DocuSign is a widely used service for signing PDF documents electronically using eSignatures. To interact with DocuSign's API, authentication is required via OAuth 2.0 tokens. These tokens are obtained by calling DocuSign's authentication endpoint with a JWT token containing your DocuSign credentials, signed with a DocuSign-issued private key.

Follow these steps to complete the integration:

1. Obtain the Private Key for Your DocuSign Application

To generate an RSA key pair:

Navigate to the Apps and Keys section in your DocuSign admin account.
Generate an RSA key pair and securely store the private key.
Note down your User ID and the Integration Key (Client ID) of your application.
Ensure that your application has been granted consent. This step requires user authorization. Refer to the DocuSign documentation for details.

2. Store the Private Key in the RunMyProcess Certificate Store

Request Details:

You must store the private key in RunMyProcess using a POST request via an API tool like Postman.

POST https://{RUNMYPROCESS_LIVE_URL}/config/{YOUR_RUNMYPROCESS_CUSTOMER_ID}/certificate
Content-Type: application/atom+xml
Authentication: Basic Auth (admin credentials required)

Request Payload:

You must store the private key in RunMyProcess using a POST request via an API tool like Postman.

<?xml version="1.0" encoding="UTF-8"?>
<feed xml:base="https://{RUNMYPROCESS_LIVE_URL}/" xmlns:xml="http://www.w3.org/XML/1998/namespace" 
xmlns="http://www.w3.org/2005/Atom" xmlns:p="http://www.runmyprocess.com/library/">
<title>Certificate</title>
<generator uri="http://www.runmyprocess.com">(c) RunMyProcess</generator>
<author>
  <uri>config/{YOUR_CUSTOMER_ID}/certificate</uri>
</author>
<entry>
  <title>DocuSign</title>
  <category term="hash" label="SHA256" />
  <category term="encryption" label="RSA" />
  <category term="operation" label="DOCUSIGN" /> // Choose any identifier here
  <category term="type" label="JWT" />
  <category term="format" label="PEM" />
  <category term="mode" label="TEST" />   // also ACCEPTANCE and LIVE
  <content>
-----BEGIN PRIVATE KEY-----
.... YOUR PRIVATE KEY HERE ....
-----END PRIVATE KEY-----
  </content>
</entry>
</feed>

3. Create the DocuSign Provider

In RunMyProcess, create a new provider for DocuSign.
Use NONE as the authentication scheme.

Note: The URL should point to the DocuSign Demo Auth server for testing. Use the production URL for live workflows.

docuSignConector

4. Create the OAuth Connector

Create an OAuth connector based on the provider.
The request payload should include a ${jwt} variable, which will hold the JWT token (see next step for details).
Add the following in the Content section: grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=${jwt}

docuSignConector

5. Generate and Use a JWT Token in a Composite API

To obtain an OAuth token, create a connector call within a Composite API (CAPI):

In the settings, select the connector created in Step 3.
Create an INPUT variable named jwt with the following script to generate the JWT token:

<#assign iss = "{docuSignIntegrationId}">
<#assign sub = "{docuSignUserId}">
<#assign aud = "account-d.docusign.com">   <!-- Use production URL if needed -->
<#assign scope = "impersonation signature">
<#assign claims>
{ "iss": "${iss}", "sub": "${sub}", "aud": "${aud}", "scope": "${scope}" }
</#assign>
<#assign headers = {}>
${jwt(headers, claims, 3600, "{THE_OPERATION_ID}", "RS256")}

Note: {THE_OPERATION_ID} is the ID that you chose when uploading the Private Key to the RMP certificate store

Create an OUTPUT variable (e.g., setToken) with:

${P_save_oauth2_token('docuSign', P_result)}

This function will store the OAuth token for later use.

6. Create a New DocuSign Provider for API Calls

Set OAuth2 as the authentication method.
In the Access Token field, retrieve the stored token using:

${P_get_oauth2_token("docuSign").access_token}

docuSignConector

7. Create DocuSign Connectors for API Requests

Define connectors for specific DocuSign API endpoints.
Use the OpenAPI definitions provided by DocuSign to streamline connector creation.

References

By following these steps, you will successfully integrate DocuSign OAuth2 authentication with RunMyProcess, enabling secure and automated interactions with the DocuSign API.