Client Cert Auth using X.509 certificates

(Redirected from Gautam-Notes)

Client Cert Auth using X.509

   KB 21668        Last updated on 07/10/2015  




0.00
(0 votes)
Article-check.png  - This is certified documentation and is protected for editing by Zimbra Employees & Moderators only.

Introduction

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

Preparation

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 []:{user@domain.com}
  • [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.

Mailboxd Configuration

If you have to configure client cert auth on mailbox node, then use these steps. Steps for proxy node not required.

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 "http://wiki.zimbra.com/wiki/Zmtlsctl"

 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}

OR

 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 browser 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. Make sure zimbraMailSSLClientCertOCSPEnabled is disabled.

 zmprov gs {server} zimbraMailSSLClientCertOCSPEnabled

To disable it:

 zmprov ms  {server} zimbraMailSSLClientCertOCSPEnabled FALSE

6. Restart mailboxd.

 zmmailboxdctl restart

Skip to Testing section.

Proxy Configuration

If you have to configure client cert auth over a nginx proxy host, then use these steps. Steps for mailbox node should NOT to be done.

1. Make sure zimbraReverseProxyMailMode is set to "https" or "both".

To know current zimbraReverseProxyMailMode setting

 zmprov gs {Proxy_servername} zimbraReverseProxyMailMode

To change to a required a mode.

 zmprov ms {Proxy_servername} zimbraReverseProxyMailMode {Mode}

2. Set zimbraMailSSLProxyClientCertPort to a unique port. (e.g. 3443). It should not be set similar to zimbraReverseProxyMailSSLPort.

 zmprov ms {Proxy_servername} zimbraMailSSLProxyClientCertPort 3443

3. Set the value of "zimbraReverseProxyClientCertMode". There are 3 possible values, "off", "on", "optional". Default is "off". "on" is same as "NeedClientAuth" and "optional" means "WantClientAuth". Check above mailboxd section (step 3) to understand the meaning of these modes.

 zmprov ms {Proxy_servername} zimbraReverseProxyClientCertMode {NeedClientAuth}

OR

 zmprov ms {Proxy_servername} zimbraReverseProxyClientCertMode {WantClientAuth}

4. Import the CA.crt to zimbraReverseProxyClientCertCA using libexec/zmclientcertmgr command. For a client authenticating itself to the server, the server must trust the CA who signed the client's certificate. Therefore the server part (nginx) has to know the CA and the browser 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 cert.

 /opt/zimbra/libexec/zmclientcertmgr savecrt global 

Important Note: Due to Bug #98410, script zmclientcertmgr is not able to import the content of CA.crt to zimbraReverseProxyClientCertCA. Use the following command as workaround, until the bug is fixed.

  content=`cat /tmp/certs/CA.crt`
  zmprov -m -l -- mcf zimbraReverseProxyClientCertCA  "$content"

5. Add nginx server's IP address in zimbraReverseProxyAdminIPAddress. In this way, Nginx Lookup Handler will know the lookup request comes from a valid nginx. Otherwise, Nginx Lookup will always return "login failed", and nginx return "403 Forbidden error".

 zmprov mcf +zimbraReverseProxyAdminIPAddress <nginx_ip>
 

You need to enter all zimbra proxy hosts IP addresses using above command.

6. Flush cache in all mailbox nodes.

 zmprov fc -a config

7. Restart nginx service.

 zmnginxctl restart

Testing

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;
  https://{server}:{zimbraMailSSLClientCertPort}/certauth
  • Admin Console URL:
  https://{server}:{zimbraMailSSLClientCertPort}/certauth/admin

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.


SSL mutual authentication flow

 - In the handshake the server first proves to the client who it is by signing a
   random challenge sent by the client and returning the corresponding public
   certificate so that the client can check the signature.
 
   In dev/QA environment, the server certificate is a self-signed certificate, if 
   you have not accepted it before in your browser, just accept it (e.g. on Firefox,
   follow the usual "I understand the risks -> add exception, ...").
   If the server certificate is signed by a well known CA, and the CA that signed 
   the server certificate is already in the known Authorities in the browser, 
   you should not be prompted to accept the server certificate.
    
 - Then, client certification is requested by the server.  The server sends out 
   descriptions of all the client-issuing-authorities which it has in its key/trust store.
  
 - The client now inspects the client certificates which are in the browser and
   attempts to find a match.  A 'match' is a client certificate which was signed by
   one of the authorities which the server says it is already aware of.
 
 - At this point, Firefox should display a dialog for you to select a client cert.  
   Select the user1.p12 one imported in step II. 3. (B).
   Firefox now signs the server's random challenge, and returns it and the 
   client's public certificate. 
    
 - The server checks that the client certificate was indeed issued by an
   authority it trusts, and checks the signing of the random challenge, dates etc..  
 
 - Now the handshake and the "authentication" of user is complete.  
   ZCS will do the "authorization" by looking up the user in ZCS's directory.
   Currently ZCS uses the EMAILADDRESS field of the subject in the client certificate 
   as the only lookup key.  If the value of EMAILADDRESS matches a Zimbra user's 
   primary email address or one of the aliases and the account is in a state good for 
   logging in, the user will be let in.


Verified Against: Zimbra Collaboration Suite 8.6, 8.5 Date Created: 04/8/2015
Article ID: https://wiki.zimbra.com/index.php?title=Client_Cert_Auth_using_X.509_certificates Date Modified: 07/10/2015



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »


Jump to: navigation, search