Implementing Docusign Recipient Authentication
Enhance the security of the emails Docusign sends by adding multi-factor authentication for your envelope recipients using the eSignature REST API.
When Docusign users request signatures from their recipients, they typically just send the recipient an email requesting that they select a link and sign the document. This is what we call remote signing. We all know that emails can be compromised, so if you are sending signature requests on sensitive documents, you may want to consider adding another layer of authentication to help ensure that the recipients are who they say they are.
Docusign's recipient authentication methods address this problem by providing an additional method of authentication to verify the identity of your recipient(s). This combination of the email itself and an additional recipient authentication method is called two-factor authentication or multi-factor authentication.
Adding multi-factor recipient authentication to envelopes can be done by the sender via our web application, or it can be done programmatically by developers building integrations using the eSignature API. For this blog post, I assume you chose our C# code examples, so my examples are in C# below. However, we also provide code examples for Node.js, Java, PHP, Python, and Ruby, as well as raw API calls using Curl in Bash shell scripts.
Note: The term Authorization Code Grant refers to a specific type of OAuth authentication your app uses to call the Docusign API itself. This should not be confused with the recipient authentication that is used to verify the identity of document signers (recipients).
The sample code is organized into separate use cases or scenarios, each being referenced by a unique number. Examples 19-23 are the ones that show you how to implement the different recipient authentication methods. Examples 19-22 only require the Docusign eSignature REST API v2, but example 23 requires Docusign eSignature REST API v2.1. We recommend you consider using Docusign eSignature REST API v2.1 for all your integrations.
In each of the examples I show in this post, most of the code required is the same for each recipient authentication method, except for the few lines of code highlighted in yellow. This makes it very easy for you to implement recipient authentication, or to even select the desired method(s) in your code based on business rules.
Example 19 - Access code authentication
Signer signer1 = new Signer()
{
Name = signerName,
Email = signerEmail,
RoutingOrder = "1",
Status = "Created",
DeliveryMethod = "Email",
RecipientId = "1", //represents your {RECIPIENT_ID}
Tabs = signer1Tabs, // variable with tabs for this signer
RequireIdLookup = "true", //will use recipient auth
AccessCode = "$3B453" //represents your {ACCESS_CODE}
};
With Access Code Authentication, the sender and the user share a secret code that is required for the recipient to gain access to the envelope. You specify Access Code authentication in the Signer object in your code like this:
One challenge with this authentication method is that the sender needs to provide the access code to recipients securely; Docusign will not send it. Sending the access code to the same email address as the envelope was sent is not recommended. If the recipient’s email is compromised, doing so would not provide additional security over not using recipient authentication at all. You should provide it separately if possible, or you can use a different method. (You can provide it verbally in a phone call or in person, you can send it in a text message, WhatsApp message, Slack message or any other means that is not tied to the same email address).
Example 20 - Phone (voice and SMS) authentication
This method of recipient authentication also requires the recipient to enter a code, but the code will be provided to the recipient via either a text message (SMS) or a voice call to their phone. When phone authentication is specified, a phone number has to be provided at the time the envelope is created. The recipient then has the option to chose if they want the code to be sent via text message or using a voice call, but they cannot change the phone number.
string workflowId = "c368e411-1592-4001-a3df-dca94ac539ae"; // default workflowID for phone auth, can be hardcoded
RecipientIdentityVerification workflow = new RecipientIdentityVerification()
{
WorkflowId = workflowId,
InputOptions = new List<RecipientIdentityInputOption> {
new RecipientIdentityInputOption
{
Name = "phone_number_list",
ValueType = "PhoneNumberList",
PhoneNumberList = new List<RecipientIdentityPhoneNumber>
{
new RecipientIdentityPhoneNumber
{
Number = phoneNumber,
CountryCode = countryAreaCode,
}
}
}
}
};
Signer signer1 = new Signer()
{
Name = signerName,
Email = signerEmail,
RoutingOrder = "1",
Status = "Created",
DeliveryMethod = "Email",
RecipientId = "1", //represents your {RECIPIENT_ID},
Tabs = signer1Tabs,
IdentityVerification = workflow,
};
Example 22 - Knowledge-based authentication (or KBA)
KBA authentication requires the recipient to answer detailed questions about themselves based on data available in public records (such as their current and former addresses). Docusign's eSignature KBA uses an identity verification service from LexisNexis Risk Solutions that validates user identities in real time. You specify KBA in the Recipient object in your code like this:
Signer signer1 = new Signer()
{
Name = signerName,
Email = signerEmail,
RoutingOrder = "1",
Status = "Created",
DeliveryMethod = "Email",
RecipientId = "1", //represents your {RECIPIENT_ID}
Tabs = signer1Tabs, // variable with tabs for this signer
RequireIdLookup = "true", //will use recipient auth
IdCheckConfigurationName = "ID Check" //indicates KBA Auth
};
When the recipient clicks the link in the email, he or she will first be asked to provide an address. This information, together with the recipient's name, will be used to generate the list of challenge questions that establishes identity.
Example 23 - Identity Verification (or IDV)
IDV is our newest recipient authentication technology that verifies the identity of recipients based on government photo IDs (such as a driver’s license or passport) and electronic IDs. IDV verifies authenticity via visible security features, watermarks, and machine-readable barcodes. To use IDV, you have to enable this feature on your Docusign account (either sandbox or production) by contacting your Docusign Account Manager or Partner Manager. If you’d like to get a better idea of what IDV is, see the link in the Additional Resources section at the end of this post.
Note: IDV is not yet fully functional in every country and region of the world.
You specify IDV authentication in the Recipient object in your code like this:
AccountsApi workflowDetails = new AccountsApi(config);
AccountIdentityVerificationResponse wfRes = workflowDetails.GetAccountIdentityVerification(accountId);
String workflowId = wfRes.IdentityVerification[0].WorkflowId;
RecipientIdentityVerification workflow = new RecipientIdentityVerification()
{
WorkflowId = workflowId
};
Signer signer1 = new Signer()
{
Name = signerName,
Email = signerEmail,
RoutingOrder = "1",
Status = "Created",
DeliveryMethod = "Email",
RecipientId = "1", // represents your {RECIPIENT_ID}
Tabs = signer1Tabs, // variable with tabs for this signer
RequireIdLookup = "true", // will use recipient auth
IdentityVerification = workflow //add the IDV workflow
};
Additional resources
Inbar Gazit has been with Docusign since 2013 in various engineering roles. Since 2019 he has focused on developer content. Inbar works on code examples including the launchers, available on GitHub in eight languages, and helps build sample apps showcasing the various Docusign APIs. He is also active on StackOverflow, answering your questions. Inbar can be reached at inbar.gazit@docusign.com.
Related posts
Discover what's new with Docusign IAM or start with eSignature for free
