Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Configuring the DocuSign authentication

Updated on August 18, 2022

Securely call the DocuSign digital signature capabilities through the OAuth 2.0 authentication method that is based on the JSON Web Token (JWT) grant.

The following articles explain how to configure your Pega application to create a JWT with your application's authentication credentials and user details. Upon request, DocuSign validates the JWT and application permissions, and then issues an access token that allows use of DocuSign services.

Before you begin: Ensure that you obtained the following integration details from the DocuSign Developer portal:
  • Integration key
  • User ID
  • RSA private key as a .key extension file
  • Redirect URI for your integration key, for example https://<host:port>/prweb/PRRestService/DocuSignService/v1/redirect

The following example shows the DocuSign Developer portal with a sample app and the integration details that you must provide in your application:

Obtaining integration details from the DocuSign Developer portal
DocuSign Developer portal that displays the integration details that you must provide in your application.
For more information, see DocuSign documentation.

Creating a keystore by using OpenSSL

Create a container for the public key certificate that your application uses to authenticate calls to DocuSign.

Important: This section provides steps on how to generate the .csr certificate file by using the OpenSSL software. However, you can use other methods for generating certificates that are more suitable for your business needs, or that are more compatible with your security standards.
Before you begin: Install or access the preferred certificate generation tool. For example, for OpenSSL certificate generation, install the OpenSSL software, and then add OpenSSL to your path environment variables.
  1. In your preferred terminal tool, generate .csr, .crt, and .p12 files by entering the following commands:
    1. For .csr, enter:
      openssl req -out CSR.csr -key DS_PrivateKey.key -new
    2. For .crt, enter:
      openssl x509 -signkey DS_PrivateKey.key -in CSR.csr -req -days 365 -out mycustom.crt
    3. For .p12, enter:
      openssl pkcs12 -export -out certificate.pfx -inkey DS_PrivateKey.key -in mycustom.crt
  2. In your Pega application, create a keystore instance:
    1. In the Keystore location list, select Upload file.
    2. In the Keystore file name field, upload the .p12 file that you created in step 1.c.
    3. In the Keystore type field, enter PKCS12.
    The following figure shows a sample DocuSign keystore:
    Creating a keystore for the DocuSign integration
    A fully configured keystore rule instance for the DocuSign integration.

Creating a JWT generation profile

Specify how your application generates the JWTs that it uses to access DocuSign digital signature capabilities by creating a JWT generation profile.

  1. In your Pega application, create an instance of a generation JSON Web Token profile.
  2. In the Registered claims section, configure parameters for the following claims:
    NameMap fromMap from key
    Issuer (iss)ConstantEnter the integration key of your DocuSign app.
    Audience (aud)ConstantPerform one of the following actions:
    • For a developer account, enter account-d.docusign.com.
    • For a production account, enter account.docusign.com
    Subject (sub)ConstantEnter the DocuSign user ID that your application impersonates.
  3. In the Custom claims section, configure parameters for the following claim:
    NameMap fromMap from key
    scopeConstant

    Enter signature impersonation

    This authentication scope is required for applications that impersonate users to perform API calls.

  4. In the Security section, configure the token security settings:
    1. In the Security configuration list, select Signature.
    2. In the Signature type list, select Asymmetric.
    3. In the Signature algorithm field, enter RS256.
    4. In the Keystore field, enter or select the keystore instance that you created in Creating a keystore by using OpenSSL.
    5. In the Alias field, enter or select the alias name of the private key from the keystore that you provided in Creating a keystore by using OpenSSL.
    6. In the Password field, enter the keystore password that you provided in Creating a keystore by using OpenSSL.
    7. Select the Suppress generation of Key ID (kid) header check box.
    See the following figure for reference:
    Configuring the JWT security settings
    The Security section of the JWT generation token profile.
  5. Confirm your settings by clicking Save.

Creating an authentication profile

Enable your application to securely exchange messages with DocuSign through OAuth 2.0 by creating an authentication profile.

  1. In your Pega application, create an instance of an OAuth 2.0 authentication profile.
    For more information, see Creating an authentication profile.

    2. Configuring the client profile

  2. In the Client configuration section, in the Grant type list, select JWT bearer.
  3. In the Client Identifier field, enter your DocuSign integration key.
  4. In the Client secret field enter any value, for example, 1234567890.
  5. In the Scope field, enter signature impersonation
  6. Ensure that the Use refresh token if available checkbox is cleared.

    7. Configuring the JWT assertion

  7. In the JWT Assertion section, select Use JWT generation profile.
  8. In the JWT generation template field, select the profile that you created in Creating a JWT generation profile.
  9. In the Endpoint configuration section, in the Access token endpoint field, enter one of the following values:
    • For a developer account, enter https://account-d.docusign.com/oauth/token.
    • For a production account, enter https://account.docusign.com/oauth/token.

    10. Configuring the client authentication

  10. Expand the Advanced configuration section.
  11. In the Client authentication section, in the Authentication scheme list, select Private Key JSON Web Token (JWT).
  12. Select the JWT generation profile checkbox.
  13. In the JWT generation profile field, select the profile that you created in Creating a JWT generation profile.
  14. In the Send access token as section, select Authorization header.
  15. Confirm your settings by clicking Save.

Updating the DocuSign connection details

Configure your application with the DocuSign connection parameters to successfully authenticate requests to DocuSign during case processing.

Before you begin: In your Pega application, save the following application settings as part of your application ruleset:
  • pyDocusignBaseURL
  • pyDocuSignAuthenticationBaseURL
  • pyDocuSignAuthProfile
  • pyDocuSignAccountID
Tip: You can use the search bar to quickly find and edit each setting, as shown in the following figure:
Searching for an application setting
Dev Studio search bar that you can use for searching for settings.

    Updating the sender authentication profile

  1. Find and open the pyDocuSignAuthProfile application setting.
  2. In the Value per production level section, for the intended production level, enter the name of the DocuSign OAuth 2.0 authentication profile.
    For more information, see Creating an authentication profile.Note: If you do not enter a value, the system invokes the connector by using basic credentials from the pySetEnvelopeCredentials data transform. For more information, see Configuring basic authentication details for DocuSign envelope requests.
    For example: The following figure shows an example configuration for the DocuSignAuthProfile application setting:
    Configuring DocuSign application settings
    Application setting rule form for the DocuSign connection details.
  3. Confirm your settings by clicking Save.

    4. Updating the DocuSign account ID

  4. Open the pyDocuSignAccountID application setting.
  5. In the Value per production level section, for the intended production level, enter your DocuSign Account ID.
  6. Confirm your settings by clicking Save.

    7. Updating the DocuSign base URL

  7. Open the pyDocusignBaseURL application setting.
  8. In the Value per production level section, update the production level settings:
    • If you use a development environment, in the Development field, enter https://demo.docusign.net
    • If you are a licensed DocuSign customer, in the Production field, enter https://www.docusign.net
  9. Confirm your settings by clicking Save.

    10. Updating the DocuSign authentication base URL

  10. Open the pyDocuSignAuthenticationBaseURL application setting.
  11. In the Value per production level section, update the production level settings:
    • If you use a development environment, in the Development field, enter https://account-d.docusign.com
    • If you are a licensed DocuSign customer, in the Production field, enter https://account.docusign.com
  12. Confirm your settings by clicking Save.
    For more information, see Defining values for an application setting and the DocuSign Developer documentation.
What to do next: Optionally, you can ensure that your application can access DocuSign services at all times by monitoring the connection status through the DocuSign connections landing page. For more information, see Monitoring the DocuSign connection status.

    Tags

    Pega Platform 8.7 Data Integration

    Have a question? Get answers now.

    Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

    Visit the Support Center

    Did you find this content helpful?

    Yes
    No

    Want to help us improve this content?
    Suggest an edit

    We'd prefer it if you saw us at our best.

    Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

    Close Deprecation Notice
    Contact us