.net, Digital Signature

Digitally signing documents with Docusign and integrating with C#

I’ve recently been asked by a few people about “digital signatures” – specifically in the context of projects digitising a paper process where a person normally scrawls their John Hancock on a paper form to confirm they’ve read it or processed it in some way.

There’s a lot to digital signatures – it’s much more than just replicating an image of a person’s traditional wet signature made with a pen and paper. This is easy to forge – digital signatures attempt to solve this. Recipients of the signed document need to believe the document is three things:

  • Authentic – we are sure who sent it, and trust this person.
  • Unaltered in transit – we must trust that the document has not been modified between being sent by one party and received by another.
  • Non-repudiable – the sender cannot later claim to have not signed the document.

One of the first rules of security is “don’t hand roll your own implementation“, so I’ve been looking out for implementations which I can integrate with websites using C# on the server. One matching implementation is offered by DocuSign.

So let’s take a very simple case – I want to be able to enter in a person’s name and email on a website, and have a document sent to them automatically for them to “digitally sign”. So:

  • I open a page on a corporate intranet, enter in a person’s name and email, and then click Submit.
  • At this point I’d like a document to be sent to this person.
  • This person would receive a document with an invitation to sign it.
  • The person signs the document, and I receive a notification the document has been signed.

You can do this with the DocuSign site directly – but you might want to integrate these steps as part of a custom workflow in your own site without having to break the process to go to the DocuSign site. Fortunately DocuSign provide an open-source C# client which allows you to integrate the digital signature workflow into your website application.

I’ll run through the steps needed to do all of this. The first part of this post is going to spend a lot of time talking about how I set up things on the DocuSign site, and the later part is going to focus on C# integration a lot more.

I don’t work for DocuSign, nor am affiliated with them in any way – this is just a post on how to use this commercial product to digitally sign documents.

First, set up your DocuSign account

You can get a free developer account with DocuSign – you just need to give your name and email, and then select a password.

screenshot-1488732050

After you’ve done this, you’ll be sent an email with a link – click the link to activate your account.

screenshot-1488732302

Once you’ve set up your account, you’ll be able to see the account home page, like the image below.

screenshot-1488732955

Next, set up your documents and templates

Let’s say there’s a standard MS Word document that I want to use – it could be a contract, or almost anything that a standard paper based process would have for people to print off and sign with a pen. For the purposes of this example, I’ve created a simple dummy Word document (shown below).

screenshot.1488925379

I’ll continue to use that document for this example.

I’ll describe the next part in detail as there are some very specific steps to take- to follow the document generation process described in the paragraph above, you need to create a Template. You can start this process by clicking on the “Templates” item in the top navigation menu….

screenshot.1488925844

….and from the window that opens, click on the “Create One” button.

screenshot-1488736967

This will take you to the page where you can create your template.

  • I’ve given my template the name “Dummy Template”
  • I’ve also added a recipient role of “Test Email Recipient”. I haven’t specified a name or email, and I’ve left the default action as “needs to sign”.
  • There can be lots of recipient roles (for example, a document might need a number of people to sign it before a process can continue) – so remember that even though this unique template has a single role, it’s really a list with just one item in it. This bit is important to remember later when I write some C# code.

screenshot.1488925300

Next, in the Add Documents section of the page shown above, I clicked on the blue “Upload” button and a standard dialog opens which allows me to select a document. I browsed to the dummy MS Word document I created earlier, and selected to upload this.

screenshot.1488925803

The image above shows what this section looks like after I’ve uploaded the document. Following this, I click on the yellow “Next” button in the top right of the screen.

The next screen that appears shows a preview of the document I uploaded, with some standard fields listed on the left hand side.

screenshot.1488926257

I can drag the standard fields from the left hand menu onto the document preview. In the image below, you can see I’ve dragged three items:

  • One to indicate where I want the recipient to sign the document,
  • One which is automatically pre-populated with the recipient’s name, and
  • One which is automatically pre-populated with the date the document was digitally signed.

screenshot.1488926139

After I added these fields, I hit the “Save and Close” button in the top right of the screen.

I now have a template which contains a document that email recipients can digitally sign, and I’ve described the role of the recipient as “Test Email Recipient”.

This for a real business case, this role might be more usefully named as “Future Employee” or “Approver”.

Next, test your template and document through the DocuSign website

Now that we have uploaded a document, and configured it for digital signatures, we can test how this will appear to our end users through the DocuSign website.

From the DocuSign home page, click on the yellow “New” button and select “Use a template”.

screenshot.1488926790

This opens a dialog like the one below, which lists the templates I’ve created. I click on “Dummy Template” to use it.

screenshot.1488926826

When it opens, I enter in the name and email address of the person I want to send a document to for them to digitally sign it. I can also enter a custom email subject line and a customised email message. Then I click the blue “Send” button.

screenshot.1488926871

Pretty soon afterwards, I receive an email in my inbox like the one below, inviting me to review a document and sign it.

screenshot.1488927016

If I click on the “Review Document” button, my browser opens showing the document associated with the template, and I just need to click on the button saying “Sign” to digitally sign the document.

screenshot-1488740652

When I click the button, there’s a dialog opens which shows you how the signature will be rendered. I’m not really sure of the point of this part – this might just be to help users feel a bit more comfortable with something that looks like a signature.

screenshot.1488740667

Once you’ve selected a signature to adopt, we’re returned to the document with a preview of what the document will look like, and I can click the yellow “Finish” button in the top right to finish the process, and send the document back to the originator.

screenshot-1488740689

So if I go back to my DocuSign home page, I can see that there’s now a number 1 beside the number of completed documents in the overview section.

screenshot-1488740779

And if I click on the Completed section, I can drill in to get a detailed list of these completed documents, as shown below.

screenshot-1488740794

I can click on this row to see the details of when the document was signed, and I can actually see a copy of the signed document.

Now I’ve tested my template and seen an email delivered to my address, I’ve digitally signed the document associated with that email, and in my DocuSign account I can see that the document was signed.

Next, integrate this process with C# and an application

Let’s say I want to trigger this process from my own website rather than having to trigger it from the DocuSign website. Fortunately this is pretty easy, because DocuSign have a C# SDK which is available on GitHub here. They provide some helpful sample code which I’ve used to get me started, but I’ve made some changes for this post which I think make the interactions a little clearer.

In this post I’ll go as far as create a C# class to generate a document for digital signature, and I’ll test it using a console application. It’ll be pretty easy to use and instantiate this class in a website.

Generate an Integrator Key

To integrate DocuSign with my web application, I need to generate an “Integrator Key”. To do this, I open up the admin screen – I can access this from my DocuSign home page using the menu shown below.

screenshot.1489089369

In the admin screen, click on the “API and Keys” item under the “Integrations” menu on the left hand side. This will open a screen called “API and Integrator Key Information”.

screenshot.1488738806

Click on the “Add Integrator Key” button to open up the dialog shown below. I added the app description of “Dummy Client Application”, and click on “Add”.

screenshot.1488739202

When you click “Add”, the integrator key is created, and is listed as shown in the screen below (again I’ve covered my API keys with a grey strip to keep them secret).

screenshot.1488739135

Create an object representing the DocuSign template

Our template above contained a single role – “Test Email Recipient”, but it actually could have contained a number of roles (e.g. “First Approver”, “Second Approver” etc.).

I’ve written a custom object which accepts a couple of parameters in the constructor:

  • The unique Id for the template (this is a string, but looks a lot like a GUID)
  • A list of role names belonging to that template – so in our example case, it would be a list of strings with a single item in the list of “Test Email Recipient”.
public class DocuSignTemplate
{
    public DocuSignTemplate(string templateId, IList<string> templateRoleNames)
    {
        this.TemplateId = templateId;
        this.TemplateRoleNames = templateRoleNames;
    }
 
    public IList<string> TemplateRoleNames { get; set; }
 
    public string TemplateId { get; set; }
}

If you want to obtain the Id for a template, you can copy it from the DocuSign site at the page below (I’ve blanked the actual template Id out and replaced it with a grey strip below).

screenshot.1488740170.png

So if I wanted to use this for a template with a GUID and a role of Test Email Recipient, my code might look like this:

var docuSignTemplate = new DocuSignTemplate("e6a4919d-3a05-41e1-8b83-313ea467093e", new List<string> { "Test Email Recipient" });

Create an object for the customised email message

Another thing which we can manage from our code is the content of the email message sent to the document recipient – I’ve created a simple object for this email, which allows me to pull the subject and message body from configuration (this might seem a bit unrelated to the nature of this post but it’ll be obvious why I’m doing this in a little while).

public class EmailTemplate
{
    public EmailTemplate(string subject, string messageBody)
    {
        this.Subject = subject;
        this.MessageBody = messageBody;
    }
 
    public string Subject { get; set; }
 
    public string MessageBody { get; set; }
}

So if I want to instantiate this with a custom subject line and message for my email, I could write the code below:

var emailTemplate = new EmailTemplate("[DocuSign C# SDK] - Sample Signature Request", "Hello this is the email message.");

Create a class to generate the document and send the email

After looking at the code on DocuSign’s GitHub account here, I tried to do a little refactoring to make the code a bit more object oriented and re-useable.

I created a simple object to take the credentials required to access my DocuSign account – username, password and integratorKey.

public class DocuSignCredentials
{
    public DocuSignCredentials(string username, string password, string integratorKey)
    {
        this.Username = username;
        this.Password = password;
        this.IntegratorKey = integratorKey;
    }
 
    public string Username { get; set; }
 
    public string Password { get; set; }
 
    public string IntegratorKey { get; set; }
}

So if I wanted to use this, I could instantiate this object with the code below.

var docuSignCredentials = new DocuSignCredentials("jeremylindsay@myemail.com", "[password]", "e84d056e-5644-4bc5-b880-b1668e1b7dcb");

Next, I’ve refactored the sample code presented by DocuSign to create a class named DocuSignDocumentGenerator This class’s constructor takes parameters of the credentials required to log in, the details of the email template and custom message, and the details of the DocuSign template we want to use.

You’ll need to search for the DocuSign.eSign package on NuGet and install this into your C# project as well.

public class DocuSignClient
        {
            public DocuSignClient(DocuSignCredentials credentials)
            {
                // initialize client for desired environment (for production change to www)
                var apiClient = new ApiClient("https://demo.docusign.net/restapi");
 
                // configure 'X-DocuSign-Authentication' header
                var authHeader = "{\"Username\":\"" + credentials.Username + "\", \"Password\":\"" + credentials.Password + "\", \"IntegratorKey\":\"" + credentials.IntegratorKey + "\"}";
 
                Configuration.Default.AddDefaultHeader("X-DocuSign-Authentication", authHeader);
 
                // login call is available in the authentication api 
                var authApi = new AuthenticationApi();
                var loginInfo = authApi.Login();
 
                // parse the first account ID that is returned (user might belong to multiple accounts)
                this.AccountId = loginInfo.LoginAccounts[0].AccountId;
            }
 
            public string AccountId { get; set; }
        }
 
        public class DocuSignDocumentGenerator
        {
            public DocuSignDocumentGenerator(DocuSignCredentials credentials, EmailTemplate emailTemplate, DocuSignTemplate docuSignTemplate)
            {
                this.DocuSignCredentials = credentials;
                this.EmailTemplate = emailTemplate;
                this.DocuSignTemplate = docuSignTemplate;
            }
 
            public DocuSignCredentials DocuSignCredentials { get; set; }
 
            public EmailTemplate EmailTemplate { get; set; }
 
            public DocuSignTemplate DocuSignTemplate { get; set; }
 
 
            public void GenerateDocument(string name, string email)
            {
                var docuSignClient = new DocuSignClient(this.DocuSignCredentials);
                var accountId = docuSignClient.AccountId;
 
                // assign recipient to template role by setting name, email, and role name.  Note that the
                // template role name must match the placeholder role name saved in your account template.  
                var templateRoles = this.DocuSignTemplate.TemplateRoleNames.Select(m => new TemplateRole
                {
                    Email = email,
                    Name = name,
                    RoleName = m
                }).ToList();
 
                // create a new envelope which we will use to send the signature request
                var envelope = new EnvelopeDefinition
                {
                    EmailSubject = this.EmailTemplate.Subject,
                    EmailBlurb = this.EmailTemplate.MessageBody,
                    TemplateId = this.DocuSignTemplate.TemplateId,
                    TemplateRoles = templateRoles,
                    Status = "sent"
                };
 
                // |EnvelopesApi| contains methods related to creating and sending Envelopes (aka signature requests)
                var envelopesApi = new EnvelopesApi();
                var envelopeSummary = envelopesApi.CreateEnvelope(accountId, envelope);
            }
        }

So to use this class, I’d call it like this:

var documentGenerator = new DocuSignDocumentGenerator(docuSignCredentials, emailTemplate, docuSignTemplate);

And to generate a document, I’d use code like the snippet below:

static void Main(string[] args)
{
    var emailTemplate = new EmailTemplate("[DocuSign C# SDK] - Sample Signature Request", "Hello this is the email message.");
 
    var docuSignTemplate = new DocuSignTemplate("4a48d276-8faa-45b7-9957-d73538a616cc", new List<string> { "Test Email Recipient" });
 
    var docuSignCredentials = new DocuSignCredentials("jeremylindsay@testemail.com", "[my password]", "e9e6caf1-b3d3-4294-b057-75fdf7367941");
 
    var documentGenerator = new DocuSignDocumentGenerator(docuSignCredentials, emailTemplate, docuSignTemplate);
 
    documentGenerator.GenerateDocument("J. Lindsay", "jeremy.lindsay@recipientdomain.com");
}

This is in the main method of a console application which is how I found to be the easiest way to test my code – but I could use this just as easily in my custom website.

Summary

In this post I’ve described a lot of things:

  • How to sign up for a developer account at DocuSign
  • How to create a template and configure a document to be digitally signed
  • How to test this template through the DocuSign website
  • How to create an Integrator Key for an application to directly integrate with the DocuSign REST API
  • How to use C# to integrate a console application with this DocuSign class

In another post I’ll describe how to integrate a C# MVC website with this class to generate documents.