Transition DocuSign to JWT Authentication

PLEASE NOTE: If you haven’t set up DocuSign yet, and you want to do so for the first time, see DocuSign Setup in our Help documentation instead. The following instructions apply to customers who currently use DocuSign and need to transition their authentication to JWT.

DocuSign is discontinuing support for basic authentication, starting at the end of August 2023. If you have an existing DocuSign integration that uses a username and password for authentication, you must complete the steps on this page to transition to JWT authentication, or your integration will stop working. 
 
To transition to JWT authentication, you will (1) create a second DocuSign integration using the new authentication method; (2) test and validate that integration; and then (3) activate it and disconnect the original integration. While the preparation time may take several hours, the actual cutover period should be minimal. However, please refer to your company’s change policy and notify users in-line with it.
 

Note: If you need help while performing this transition, reach out to Support with the error message or issue you encountered, and the steps you had just completed when the issue occurred.

Prerequisites

To set up your integration with the new JWT authentication method, you will need: 
  • Admin account access to the production DocuSign environment
  • DocuSign Developer account access
  • An Agiloft admin account to access DocuSign Integration setup
  • A new Agiloft user in the employees table that serves as the DocuSign admin; assign this user to both the Admin and DocuSign User groups
  • A list of users who need to create DocuSign envelopes; typically this is simply an export of your current DocuSign Users, which is detailed later in this guide
  • To configure consent, you need one or both of the following:
    • For admin consent: access to add a new TXT record to your domain’s DNS settings
    • For individual consent: individual accounts must grant consent by URL


Setting Up JWT Authentication

Before you proceed any further: Follow the steps in DocuSign Setup to create a new, separate configuration record for DocuSign integration, using JWT authentication. 

After you cut over to the new integration, envelopes sent using your prior integration will continue to receive status updates over the new connection. DocuSign continues to retry publishing envelopes for 15 days; for envelopes from more than 15 days prior, sign in to the DocuSign portal and go to Settings > Connect > Publish to manually handle failed envelopes.

When you have the new DocuSign integration configured with JWT authorization, you can transition your existing users. The steps depend on how your users were configured previously:

  • Users were configured to authenticate “As another user”
  •  Users were configured to authenticate “With username” 

They also depend on how many users you need to handle. If you have 20 or fewer users, we recommend modifying them individually. If you have more than 20 users, we recommend editing them all at once.

Authenticate “As another user”

If you have 20 or fewer DocuSign users:
  1. Go to the DocuSign User table in Agiloft and edit the user record.
  2. Under the Authenticate options, select JWT.
  3.  Add the User ID from DocuSign for the DocuSign Admin user. Because you’re setting everyone to authenticate as this Admin user, you will enter the same User ID for every user you edit. To get this ID, go to the User tab in DocuSign, open the Admin user’s profile, and copy the User ID. Then, enter it into the User ID field.
  4.  Click Grant Access to DocuSign, then Save, and then Close.
  5.  Repeat steps 1-4 for all the users in the table.
If you have more than 20 DocuSign users:
  1. Go to the DocuSign User table and open Setup DocuSign Users from the drop-down in the left menu (old interface) or top Navigation menu (new interface).
  2. On the Action Bar tab, edit the currently defaulted action bar and add the Revoke Access & Grant Access to DocuSign buttons, then click Finish twice to return to the table view.
  3. Select all the records and click Revoke Access. This sets Access Granted to No.
  4. Select all the records in the table and use Export or Actions > Export to export them. Select an Excel file format and include the following fields, then make the changes described in the Value column:
  5. Go back to the DocuSign Users table and click Import or Actions > Import.
    1. Select the location and file path for the Excel file you updated. Make sure the DocuSign Users table is selected.
    2. On the Records tab, select “Update imported fields only in matching records,” make sure matching is set to use ID, and leave the other settings as they are.
    3. On the Fields tab, confirm the values in the Sample Data and Column rows match.
    4. Click Test. Make sure there are no errors, and all the rows in the spreadsheet are processed.
    5. Click Finish.
  6. Return to the DocuSign Users table view and click Search.
  7. Search for “Access Granted” equals (=) No and “DocuSign User ID” equals (=) the ID of your DocuSign Admin user.
  8. Click the checkbox in the header and select all found records.
  9. Click Grant Access to DocuSign in the action bar.

Authenticate “With username”

Before you can configure your users, you need to make sure consent has been granted for them. If you’re using admin consent, and you’ve already granted it, you can set up any user whose account uses the correct domain. However, for individual consent, each user must follow the provided URL and grant consent before their DocuSign accounts will be usable. For more information about consent, see DocuSign Setup.

If you have 20 or fewer DocuSign users:
  1. Go to the DocuSign User table and edit the user record.
  2. Under the Authenticate options, select JWT.
  3. Add the User ID for the correct DocuSign account. To find your users’ IDs, log in to DocuSign and click Users on the sidebar. To download all user IDs, click Download Users at the top of the Users page. To find a single user’s ID, locate that user, click Actions > Edit in the row, and find the User ID at the top of the screen.
  4. Click Grant Access to DocuSign, then Save, and then Close.
  5. Repeat steps 1-4 for all the users in the table.
If you have more than 20 DocuSign users:
  1. Go to the DocuSign User table and open Setup DocuSign Users.
  2. On the Action Bar tab, add the Revoke Access and Grant Access to DocuSign buttons to the action bar, then click Finish twice to return to the table view.
  3. Select all the records and click Revoke Access. This sets Access Granted to No.
  4. Select all the records in the table and use Export or Actions > Export to export them. Select an Excel file format and include the following fields, then make the changes described in the Value column:
  5. Go back to the DocuSign Users table and click Import or Actions > Import.
    1. Select the location and file path for the Excel file you updated. Make sure the DocuSign Users table is selected.
    2. On the Records tab, select “Update imported fields only in matching records,” make sure matching is set to use ID, and leave the other settings as they are.
    3. On the Fields tab, confirm the values in the Sample Data and Column rows match.
    4. Click Test. Make sure there are no errors, and all the rows in the spreadsheet are processed.
    5. Click Finish.
  6. Return to the DocuSign Users table view and click Search.
  7. Search for “Access Granted” equals (=) No
  8. Click the checkbox in the header and select all found records.
  9. Click Grant Access to DocuSign in the action bar.

If you encounter issues while following these instructions, please open a ticket with our Support team by logging into the Support Portal. Ensure that you include the error message encountered and a description of the steps at which the issue occurred.


Common Error Messages 


(401/null) Docusign Message: null

If this message appears when attempting to create a DocuSign envelope, something went wrong with consent. To fix it, revisit DocuSign Setup and repeat the steps in Access and User Consent to grant admin consent, individual consent, or both.

Can’t setup DocuSign Connect for URL … - please set a correct Hotlink Server Root URL (use https:// and non-localhost).

This might appear when attempting to enable DocuSign Connect. To fix it, go to Setup > System > Manage Global Variables and locate the Hotlink Server Root URL global variable. If it isn’t listed with the customized variables, check the Variables with Default Values tab. Edit the variable and add https:// at the beginning, or, if it already has http://, replace that with https:// and then click Finish.


This Account lacks sufficient permissions. :: Connect not enabled for account

See the DocuSign resolution for this issue.


There is no DocuSign User ID field when setting up a new DocuSign User record in Agiloft.

Go to setup for the DocuSign User table, go to the Layout tab, and add the DocuSign User ID field to the layout.