How to configure mutual TLS for NGINX | Docusign

The NGINX web server (pronounced “engine-x”) is a popular open-source web server with a focus on speed and performance. To enable the NGINX web server to request mutual TLS from Docusign Connect, follow the steps outlined in this guide.

Note: This guide assumes that you have experience configuring an NGINX web server. Your web server configuration should always be reviewed and tested by your Networking and Information Security departments. Don’t rely on this guide to create a secure system.

Learn about mutual TLS

Mutual TLS authentication and authorization enables Docusign Connect to guarantee the identity of the server to the client and provide a two-way encrypted channel between the two.

See Mutual TLS to learn more about mutual TLS capabilities and requirements.
See Mutual TLS: Stuff you should know for context around mutual TLS and recommendations for implementing it.

Required data

You will need the following information to configure mutual TLS for NGINX:

Item	Description
NGINX web server	A web server running NGINX
Distinguished name	Identifies a root certificate that the server trusts.

Step 1. Obtain the root certificate for the client

During the mutual TLS part of the handshake, the server (your listener), sends the client (Docusign) the root Distinguished Name that the server trusts. The client then responds with a matching certificate/intermediate certificate bundle.

The Docusign Trust site’s Docusign public certificates page includes a link to the Connect root certificate. It has the common name DigiCert Global Root G2. The same certificate is available from the DigiCert web site. It is a 2048-bit certificate. Some older software versions may not be able to use a 2048-bit certificate and will need to be upgraded.

Copy the certificate, including the “BEGIN/END CERTIFICATE” lines, to a file on your webserver. Use the name docusign_root_cert.pem or similar for the certificate file.

Step 2. Configure your web server

After you’ve downloaded a Docusign Connect certificate, configure your web server using this procedure:

http {
    log_format ssl_client
    '$remote_addr - $remote_user [$time_local] '
    '"$request" $status $body_bytes_sent '
    '"Client fingerprint" $ssl_client_fingerprint '
    '"Client DN" $ssl_client_s_dn';
    {
        # SSL configuration
        listen 443 ssl;
        # Using the custom log format:
        access_log /var/log/NGINX/listener.log ssl_client;
        root /var/www/html;
        client_max_body_size 50M; # Needed due to large size of Docusign
        # notifications that include
        # source documents
        index index.php index.html index.htm index.NGINX-debian.html;
        server_name listener.worldwidecorp.us;
        ssl_certificate /etc/letsencrypt/live/listener.worldwidecorp.us/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/listener.worldwidecorp.us/privkey.pem;
        ssl_protocols TLSv1.2;
        ssl_client_certificate /home/ubuntu/connect_root.pem;
        ssl_verify_client on; # Require Mutual TLS
        ssl_verify_depth 10; # Enable verification of the client’s certificate
        # location settings are not shown…
    }
}

Step 3. Test your Docusign Connect configuration

After you follow the steps outlined earlier in this guide, you’re ready to test your Docusign Connect configuration.

162.248.184.11 - - [13/Feb/2017:11:44:29 +0000] "POST /info.php HTTP/1.1" 200 61 "Client fingerprint"
d2818c52xxxxxxxxxxxxxxxxxxxxxxxx6cc3a0ce "Client DN" /C=US/ST=Washington/L=Seattle/O=Docusign, Inc./
OU=Technical Operations/CN=demo.connect.docusign.net

The log shows that the listener (info.php) responded with a 200 status code. It also shows the client’s (Docusign) certificate fingerprint and distinguished name.

Step 4. Add access control

Authenticating a client via its certificate is a good start, but access control is vital. For this how-to, you’ll control access by checking the client’s certificate fingerprint. You can obtain the right fingerprint either from a known-good connection attempt (as logged above), or through an independent channel.

$ openssl x509 -in DEMO.connect.docusign.net.cer -noout -fingerprint`Output:
SHA1 Fingerprint=D2:81:8C:52:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:6C:C3:A0:CE

You can see that the d2818c52 at the start of the fingerprint in the log is the same as the openssl command’s output of D2:81:8C:52, only formatted differently.

# Add the following before the first location section
# Access control -- the if needs to be outside of the location sections
# Note https://www.NGINX.com/resources/wiki/start/topics/depth/ifisevil/
if ($ssl_client_fingerprint != "d2818c52xxxxxxxxxxxxxxxxxxxxxxxx6cc3a0ce") {
    return 403;
}

Troubleshooting

Notification messages are too large

If you choose to include envelopes’ documents in the Connect notifications, you may encounter maximum POST or payload size limitations. In the configuration script, you updated the web site’s maximum request size to 50 megabytes. Your software stack (Java, Node.js, PHP, etc.) may have additional maximum request size settings that will also need to be increased.

The Docusign client certificate was not sent or other TLS handshake issues

You can turn on debug level logging to see more information in the error_log about the TLS handshake process. To do so, change the error_log setting in the NGINX configuration file:

error_log /var/log/NGINX/error.log debug;

Here are the certificate verification lines from the error log when debug is on:

2017/02/13 14:57:27 [debug] 8169#8169: 1 verify:1, error:0, depth:2,
subject:"/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=(c) 2006 VeriSign, Inc. -
For authorized use only/CN=VeriSign Class 3 Public Primary Certification Authority - G5",
issuer:"/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=(c) 2006 VeriSign, Inc. -
For authorized use only/CN=VeriSign Class 3 Public Primary Certification Authority - G5"
2017/02/13 14:57:27 [debug] 8169#8169: 1 verify:1, error:0, depth:1,
subject:"/C=US/O=Symantec Corporation/OU=Symantec Trust Network/CN=Symantec Class 3 Secure Server CA - G4",
issuer:"/C=US/O=VeriSign, Inc./OU=VeriSign Trust Network/OU=(c) 2006 VeriSign, Inc. - For authorized use only/
CN=VeriSign Class 3 Public Primary Certification Authority - G5"
2017/02/13 14:57:27 [debug] 8169#8169: 1 verify:1, error:0, depth:0,
subject:"/C=US/ST=Washington/L=Seattle/O=Docusign, Inc./OU=Technical Operations/CN=demo.connect.docusign.net",
issuer:"/C=US/O=Symantec Corporation/OU=Symantec Trust Network/CN=Symantec Class 3 Secure Server CA - G4"