Difference between revisions of "Gautam-Notes"

(2-way SSL (mutual authentication) using X.509 certificates)
 
Line 1: Line 1:
{{WIP}}
+
#REDIRECT [[Client_Cert_Auth_using_X.509_certificates]]
 
 
__TOC__
 
 
 
 
 
= 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.
 
 
 
'''Note1:''' The detailed document is available on the Zimbra server '''docs/certauth.txt'''
 
 
 
'''Note2:''' Steps and examples used below are mainly for QA or dev environment.
 
 
 
'''1. Create a Certificate Authority (CA) Certificate'''
 
 
 
'''(A).''' First, we create a 2048-bit private key to use when creating our CA.
 
  mkdir /tmp/cert; cd /tmp/cert
 
  /opt/zimbra/openssl/bin/openssl genrsa -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 -new -key ca.key -out ca.csr
 
 
 
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
 
<pre>
 
Country Name (2 letter code) [AU]:US
 
State or Province Name (full name) [Some-State]:California
 
Locality Name (eg, city) []:Saratoga
 
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example Company
 
Organizational Unit Name (eg, section) []:Engineering
 
Common Name (eg, YOUR name) []:user one
 
Email Address []:user1@domain.local
 
</pre>
 
 
 
'''(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):
 
<pre>
 
- 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).
 
</pre>
 
 
 
 
 
'''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.
 
 
  /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
 
 
 
 
 
'''Note: SSL mutual authentication flow'''
 
<pre>
 
- 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.
 
</pre>
 
 
 
== Testing ZWC for authentication ==
 
 
 
SSL mutual 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)
 
 
 
Request URL
 
    https://{server}:{zimbraMailSSLClientCertPort}/certauth
 
or
 
    https://{server}:{zimbraMailSSLClientCertPort}/certauth/admin
 
 
 
 
 
----
 
 
 
= 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.
 
* [http://www.zimbra.com/docs/ne/latest/administration_guide/wwhelp/wwhimpl/js/html/wwhelp.htm#href=NE_Admin_Guide_7_0.Appendix%20B%20Configuring%20SPNEGO%20Single%20Sign-On%20for%20ZCS.html SPNEGO Configuration]
 
* For ZCO, ensure that the Store Password HKEY is diabled
 
  HKEY_LOCAL_MACHINE\SOFTWARE\Zimbra\StorePassword = 0
 

Latest revision as of 12:12, 20 March 2015

Jump to: navigation, search