How to configure mutual TLS for the Apache 2 web server | Docusign

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

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 for more information.

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.

<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:

<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):

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:

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.