DocuSign JWT Authentication in webMethods CloudStreams

Knowledge base
, , ,
1

Summary:

This article describes the step-by-step process of generating JWT Authentication for the webMethods CloudStreams provider for DocuSign.

Prerequisites:

  • The User needs to have a working DocuSign account subscription.
  • License for the Integration server 10.5 or above.

Contents:

  • Generation of DocuSign JWT Authentication.

Note:
Any coding or configuration examples provided in this document are only examples and are not intended for use in a productive system without verification. The example is only done to better explain and visualize the possibilities.

Steps:

  1. Log in to the DocuSign developer account & choose the option “My Apps & Keys” option.
    image

  2. Choose the “Apps & Keys” option, then click on the “ADD APP AND INTEGRATION KEY” option to create the apps. If apps are already created then click on the “Edit” option under the “ACTION” tab.
    image

  3. User needs to visit the “Service Integration” section to “GENERATE RSA” or “UPLOAD RSA”.
    image

  4. In case the user wanted to generate the public/private key pair, then he needs to click the “Generate RSA” button. A new dialog will open the generated keys - you must copy these values and store them somewhere as this will be your only chance to do so:
    image

    Now, the user needs to set a throwaway Redirect URI, https://www.google.com/ (this isn’t really used - the goal here is to first authorize the app you created but JWT will take over from that point). Click “Save” to create the Integration App.

  5. Now user needs to “Grant Consent” from a DocuSign user (it could be you) for this App to impersonate them (that’s what a Service account does). It follows this URI syntax: DocuSign

  6. Opened the following URL in my browser (substitute your client ID/integration key, state, scopes, and redirect URI that you wish to use): You’ll be asked to consent to the application:
    image

    and then redirected to that throwaway localhost redirect URI (you don’t need to save anything from this response).

Generating the JWT

Now that consent has been granted, it’s time to move to JWT. in short it is a token value that encodes header and payload/body data that is signed with keys. The DocuSign Developer docs take you through how it’s constructed.

User needs to generate the JWT Payload/Body that matches what DocuSign wants:
image

and there are few ways to do that. You could build the above JSON object manually then use it directly in the “Custom Metadata” section, but I’ll show how to leverage the various fields in the JWT Generate Snap and the JWT Account.

“aud” and “sub” stand for Audience and Subject respectively and can be set directly on the JWT

“sub” is the most difficult value to get - in fact, you have to look it up by using the API to call the /userinfo endpoint and that means using the OAuth 2.0 flow.

The “iat” value will be generated automatically (it defaults to “now” in Unix Epoch timestamp format).
“iss” is the issuer, and this will be the Client ID/Integration Key created when you registered your App in the DocuSign Developer portal.

“scopes” (which will always include impersonation and most DocuSign APIs want the signature scope too, so I’ve included them both, space-separated), and that can be directly configured on the “Custom Metadata” field in the JWT Generate.

We’ll want to create a protected Keystore for use by the account. There are a variety of ways to do this, but I’ll demonstrate with openssl.

Note: User must have installed the Open SSL tool & should have JVM.

  1. Combine the Public key & private key value into one file & save it as .key extension.
    image

  2. Now navigate to the OpenSSL bin folder & execute the below commands in the terminal.

    openssl req -new -x509 -key C:\licenses\docu-jwt-demo.pem -out .crt
    image

    openssl pkcs12 -export -inkey <Name>.pem -in .crt -out .p12 -name

    ex: openssl pkcs12 -export -inkey C:\licenses\docusign-jwt-demo.pem -in docusign-jwt-demo.crt -out docusign-jwt-demo.p12 -name docusign123
    image

    Now copy this .p12 file & save it to the java jvm bin folder location. Then use the below command.

    keytool -importkeystore -srckeystore docusign-jwt-demo.p12 -srcstoretype PKCS12 -destkeystore docusign-jwt- demo.jks -deststoretype JKS

image
9. Now add this newly generated .jks file to the CloudStreams admin page in order to use this file in the connector.

image
image601×507 51.5 KB

Then add the details on the below page.

image

  1. Now create the DocuSign Connection. Fill in the credentials details & click the submit button.
    image

    Once successful, the connection will get successfully created.