Gautam-Notes

 - This article is a Work in Progress, and may be unfinished or missing sections.

- This article is NOT official Zimbra documentation.

Single Sign On

SPNEGO The SPNEGO SSO feature allows AD domain users to enter their Zimbra mailbox without having to re-authenticate themselves to Zimbra by entering their Zimbra credentials.

• SPNEGO Configuration
• For ZCO, ensure that the Store Password HKEY is diabled

 HKEY_LOCAL_MACHINE\SOFTWARE\Zimbra\StorePassword = 0

Certificates

2-way SSL (mutual authentication) using X.509 certificates

Two-way SSL authentication, also commonly referred to as SSL mutual authentication, is the combination of server and client authentication. The authentication that is occurring is mutual, or two-way, because the server is authenticating itself to the client, and the client is authenticating itself to the server.

For a server authenticating itself to the client, the client must trust the CA who signed the server's certificate.

For a client authenticating itself to the server, the server must trust the CA who signed the client's certificate.

Note: Steps and examples used below are mainly for QA and dev environment.

1. Create a Certificate Authority (CA) Certificate

(A). First, we create a 1024-bit private key to use when creating our CA.

 mkdir /tmp/cert; cd /tmp/cert
 /opt/zimbra/openssl/bin/openssl genrsa -des3 -out ca.key 2048

The pass phrase will be requested whenever you use this certificate for anything, so make sure you remember it. This will create a file called /tmp/cert/ca.key, containing our certificate authority private key.

(B). Next, we create a master certificate based on this key, to use when signing other certificates:

 /opt/zimbra/openssl/bin/openssl req -config /opt/zimbra/openssl/ssl/openssl.cnf -new -x509 -days 1001 -key ca.key -out ca.cer

This will create our CA certificate and store it as /tmp/cert/ca.cer

(C). Create and sign(self-sign) a certificate from the certificate request

 /opt/zimbra/openssl/bin/openssl x509 -req -days 365 -in ca.csr -out ca.crt -signkey ca.key

2. Create a Client Certificate

(A). Create a private key

  /opt/zimbra/openssl/bin/openssl genrsa -out user1.key 2048

(B). Create a certificate request

Note: the most important information is the Email Address. It must be the email address of the Zimbra user.

  /opt/zimbra/openssl/bin/openssl req -new -key user1.key -out user1.csr

(C). Sign the user certificate request using the CA created in 1 and create the user certificate

  /opt/zimbra/openssl/bin/openssl ca -in user1.csr -cert ca.crt -keyfile ca.key -out user1.crt -policy policy_anything

3. Import the Client Certificate into Web Browsers

Web browsers like Firefox and IE can't use the certificates in the PEM format that is generated by OpenSSL. Consequently, we'll need to export the user certificate to file formats that can be imported by web browsers.

(A). Import the client certificate in PKCS#12 format Firefox and Internet Explorer 6.0 support the PKCS#12 certificate format. Use the following command to convert the user certificate to this format.

  /opt/zimbra/openssl/bin/openssl pkcs12 -export -clcerts -in user1.crt -inkey user1.key -out user1.p12

Copy the user1.p12 file to a location where you can access it from your web browser via the file system.

(B). To import a certificate in Firefox (Firefox 3.6 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 3. (A).

4. Import the CA certificate that signed the client certificate in ZCS's keystore or truststore.

Preferred way: - 'addcacert' appends an otherwise untrusted ssl certificate to the cacerts file.

(A) /opt/zimbra/bin/zmcertmgr addcacert <certfile>

5. Configure Zimbra server to request client certificate

(A). Make sure zimbraMailMode on server is *not* http

  zmprov gs {server} zimbraMailMode

It is OK as long as zimbraMailMode is not "http".

(B). Configure SSL port for client certificate

Client certificate 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.

SSL mutual authentication must be configured on its own port (e.g. 9443).

To configure the SSL mutual authentication port:

  $ zmprov ms {server} zimbraMailSSLClientCertPort {port}

(C). Two modes are supported for client certificate:

WantClientAuth and NeedClientAuth.

Do a "zmprov desc -a zimbraMailSSLClientCertMode" for description of this attribute and difference between the two modes.

To configure the client certification mode:

  $ zmprov ms {server} zimbraMailSSLClientCertMode WantClientAuth

or

  $ zmprov ms {server} zimbraMailSSLClientCertMode NeedClientAuth
  

6. Restart mailbox server

  $ zmmailboxdctl restart