> 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 the Apache 2 web server

> This topic demonstrates how to enable an Apache 2 server to request mutual TLS from Docusign Connect.

The [Apache 2 web server](https://httpd.apache.org/) is a popular open-source web server with many capabilities. This topic demonstrates how to enable an Apache 2 server to request mutual TLS from Docusign Connect.

> **Note:** This guide is designed to help an expert configure mutual TLS on an Apache 2 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 the Apache 2 web server:

| Item                | Description                                           |
| ------------------- | ----------------------------------------------------- |
| Apache 2 Web server | A web server running Apache 2.                        |
| 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

Implement a set of Apache 2.4 directives, shown below, that require the client to support mutual TLS. They can be applied to specific directories or to all incoming connections. See the [Apache 2.4 SSL documentation](https://httpd.apache.org/docs/2.4/mod/mod_ssl.html) for more information.

```text
SSLVerifyClient require
SSLVerifyDepth 10
SSLCACertificateFile /etc/apache2/conf/docusign_root_cert.pem
```

## Step 3. Configure client access control

Your web server is now configured to use mutual TLS to require the client (Docusign) to provide its X.509 certificate to identify itself. The next step is to use the client’s identity for access control. This example for Apache 2.4 is applied to a specific directory.

```text
<Directory "/var/www">
    SSLOptions +StdEnvVars
    <RequireAny>
        Require expr %{SSL_CLIENT_S_DN_CN} == "demo.connect.docusign.net"
        Require expr %{SSL_CLIENT_S_DN_CN} == "connect.docusign.net"
        Require expr %{SSL_CLIENT_S_DN_CN} == "eu.connect.docusign.net"
    </RequireAny>
</Directory>
```

First, the above example sets the SSL library to create environment variables with information from the client’s certificate. Next, the client’s CN (common name) is checked to ensure that it’s either the demo Docusign system or one of the production systems.

> **Note:** A more robust check would compare the client certificate’s **serial number** or its **fingerprint** (best). The **serial number** is available as the Apache 2 SSL environment variable `SSL_CLIENT_M_SERIAL`. Your application would need to calculate the certificate’s fingerprint, because it is not available from the Apache 2 server.

Test your configuration:

* Disable mutual TLS from Connect. Check that notification messages fail.
* Enable mutual TLS from Connect and change the acceptable client certificate common names. Check that the notification messages fail.
* Reset your configuration and check that notification messages succeed.

## Troubleshooting

For Apache 2.4, add the following to your Apache configuration file to enable trace messages for the TLS connections:

```text
<IfModule mod_ssl.c>
    ErrorLog /var/log/apache2/ssl_engine.log
    LogLevel ssl:debug
    # LogLevel ssl:trace8
</IfModule>
```

The **debug** SSL log level provides helpful information in the specified error log. The debug messages tell you that the mutual TLS certificate request worked and the identity of the client (Docusign):

```text
ssl_engine_kernel.c(1560): [client 162.248.184.11:25063]
AH02275: Certificate Verification, depth 0, CRL checking mode: none
[subject: CN=connect.docusign.net,OU=Technical Operations,
O=Docusign, Inc.,L=Seattle,ST=Washington,C=US /
issuer: CN=Symantec …
```

This SSL debug message means that the mutual TLS certificate request didn’t work:

```text
SSL Library Error: error:140890C7:
SSL routines:ssl3_get_client_certificate:
peer did not return a certificate --
No CAs known to server for verification?
```

This problem can be caused by several things:

* Docusign was not configured to respond to the mutual TLS certificate request. Ensure that the **Enable Mutual TLS** option is checked.
* A common problem: the root distinguished name sent to the client in the **CertificateRequest** message during the handshake was either missing or wrong. Use **ssl:trace8** to log the contents of the message.
* An infrequent problem: the **CertificateRequest** message didn't include a Hash Algorithm/Signature Algorithm pair that the client supports.

To drill down further, you can request log level **ssl:trace8**. This will include the actual TLS handshake protocol contents in the Apache 2 error file.