Client Cert Auth using X.509 certificates

Revision as of 11:55, 20 March 2015 by Irfan (talk | contribs) (Introduction)

Admin Article

Article Information

This article applies to the following ZCS versions.

ZCS 8.0 Article ZCS 8.0 ZCS 8.6 Article ZCS 8.6

This document covers the preparation and configuration part for MAILBOX servers only. If you want to configure client cert auth on a proxy host, use this wiki.


Client certificate authentication is one part of Two-way SSL authentication, also commonly referred to as SSL mutual authentication, is the combination of server and client authentication.

Commonly server certificate authentication is done by Browser in a SSL connection, and client cert authentication is optional. This document is concentrating on how to do the client cert authentication in Nginx-Zimbra. This feature is introduced in ZCS 7.1 (RFE 29625).


Generate Self signed CA and client certs

  • Note: For testing purpose only in absence of commercial certs

You need to create a CA cert/key pair and a client cert/key pair. Following steps can be used.

  • [A] Generate CA key and cert
 mkdir /tmp/certs/ ; cd /tmp/certs
 /opt/zimbra/openssl/bin/openssl genrsa -out CA.key 2048
 /opt/zimbra/openssl/bin/openssl req -new -key CA.key -x509 -days 3650 -out CA.crt
  • [B] Generate client key and csr
 /opt/zimbra/openssl/bin/openssl genrsa -out user1.key  2048
 /opt/zimbra/openssl/bin/openssl req -new -key user1.key -out user1.csr

Example output. At the "Email Address" section, enter the username who needs to be authenticated using the cert.

 Country Name (2 letter code) [XX]:US
 State or Province Name (full name) [Some-State]:CA  
 Locality Name (eg, city) [Default City]:San Mateo
 Organization Name (eg, company) [Default Company Ltd]:Zimbra
 Organizational Unit Name (eg, section) []:Support
 Common Name (eg, your name or your server's hostname) []:{username}
 Email Address []:{}
  • [C] Sign the user1.csr
 /opt/zimbra/openssl/bin/openssl x509 -req -in user1.csr -CA CA.crt -CAkey CA.key -out user1.crt -set_serial 3
  • [D] Some browser requires converting user1.crt to PCK12 format to be imported. Converting to PKC12 format.
 /opt/zimbra/openssl/bin/openssl pkcs12 -export -clcerts -in user1.crt -inkey user1.key -out user1.p12

Import Client Cert to Browser

Example steps to import user1.p12 file to Firefox 36.0.1 on Mac.

Firefox -> Preferences

- Click on the Advanced tab

- Under Certificates, select "Ask me every time" for "When a server requests my personal certificate".

- Click on "View Certificates"

- Click on the "Your Certificates" tab

- Click on "import"

- Use the browse button to select the user1.p12 file. You will be prompted for the password entered in step [D] above.

* The rest of the document assumes above steps are completed.

Main Configuration

If you have mailbox node only and need to configure client cert auth, use these steps.

1. Make sure zimbraMailMode is set to other than http. HTTPS is required for mailbox to offer client cert mode.

To know current zimbraMailMode setting

 zmprov gs {servername} zimbraMailMode

To change to a required a mode. Choose mode from, https, both, mixed, or redirectd. More info on ""

 zmtlsctl {Mode}

2. Configure zimbraMailSSLClientCertPort for client cert auth. Client cert authentication happens during SSL handshake and is a configuration on the SSL connector(port). The regular SSL(zimbraMailSSLPort) and admin(zimbraAdminPort) port should *not* be configured to request client certificate, because SSL mutual authentication will interfere with other authentication options on the same port. Therefore zimbraMailSSLClientCertPort must of configured on its own port (e.g. 9443).

 zmprov ms {server} zimbraMailSSLClientCertPort {port}

3. Set the zimbraMailSSLClientCertMode. Three modes supported are: Disabled, NeedClientAuth, WantClientAuth.

  • Disabled: client authentication is disabled.
  • NeedClientAuth: client authentication is required during SSL handshake on the SSL mutual authentication port(see zimbraMailSSLClientCertPort). The SSL handshake will fail if the client does not present a certificate to authenticate.
  • WantClientAuth: client authentication is requested during SSL handshake on the SSL mutual authentication port(see zimbraMailSSLClientCertPort). The SSL handshake will still proceed if the client does not present a certificate to authenticate. In the case when client does not send a certificate, user will be redirected to the usual entry page of the requested webapp, where username/password is prompted.
 zmprov ms {server} zimbraMailSSLClientCertMode {NeedClientAuth}


 zmprov ms {server} zimbraMailSSLClientCertMode {WantClientAuth}

4. Adding the CA cert to the mailbox cert store. For a client authenticating itself to the server, the server must trust the CA who signed the client's certificate. Therefore the server part (mailboxd) has to know the CA and the broswer has to send the client cert to server and let server check its validity.

  • If using self signed certs, import the CA.crt file that is generated in "Preperation" section 1A.
  • If using commercial certs, you need to import your CA's root and intermediate certs to complete the trust chain.

Run as root:

 /opt/zimbra/bin/zmcertmgr addcacert /tmp/certs/CA.crt

5. Restart mailboxd.

 zmmailboxdctl restart


Client cert authentication is supported for Zimbra WEB Client(ZWC) and admin console by browsing directly to the certauth servlet (without the virtual host and login/logout redirect settings).

  • Webclient URL;
  • Admin consoel URL:

You will be prompted to select the client certificate by the browser. Select the correct the cert and hit OK. You should be logged into the account directly.

  • Note: Make sure the user whose certificate imported in browser has admin rights.
Jump to: navigation, search