> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# How to configure mutual TLS for NGINX

> To enable the NGINX web server to request mutual TLS from Docusign Connect, follow the steps outlined in this guide.

The [NGINX](https://www.f5.com/go/product/welcome-to-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](/platform/webhooks/mutual-tls) to learn more about mutual TLS capabilities and requirements.
* See [Mutual TLS: Stuff you should know](https://www.docusign.com/blog/developers/dsdev-mutual-tls-stuff-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](https://www.docusign.com/trust/compliance/public-certificates) page includes a link to the [Connect root certificate](https://www.docusign.com/sites/default/files/DigiCert%20Global%20Root%20G2.cer). It has the common name DigiCert Global Root G2. The same certificate is available from the [DigiCert](https://www.digicert.com/kb/digicert-root-certificates.htm) 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:

```text
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.

```text
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.

```text
$ 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.

```text
# 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:

```text
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"
```