Setting up SSL (TLS) client certificate authentication in a Liberty JVM server

SSL client certificate authentication allows the client and server to provide certificates to the opposite party for mutual verification. It is often used in situations where an extra level of authentication is required because of security concerns.

1. Create a personal certificate using a signing certificate and associate the personal certificate with a RACF user ID.
   Then, export the personal certificate to a data set in CER format and then FTP in binary to your work station. Import the personal certificate to the web browser as a personal certificate. When the certificate is imported into the web browser, it can supply an SSL client certificate and connect to the HTTPS port in the Liberty server. Use the following RACF command, where <clientuserid> is the RACF user ID and <hostname> is the host name of the client computer.

   RACDCERT ID(<clientuserid>) GENCERT                                                                     
     SUBJECTSDN(CN('<hostname>') 
      O('IBM')  
      OU('CICS'))
      SIZE(1024)
      SIGNWITH (CERTAUTH LABEL('CICS-Sample-Certification'))
     WITHLABEL('<clientuserid>-certificate')

   Export the personal certificate as you have done earlier in this step.

   RACDCERT ID(<clientuserid>) 
     EXPORT(LABEL('<clientuserid>-certificate'))               
      DSN('USERID.CERT.CLICERT')  
      FORMAT(PKCS12DER)  
      PASSWORD('password')

   Update the server.xml SSL element to support SSL client certificate authentication:

     <ssl id="defaultSSLConfig" keyStoreRef="racfKeyStore" 
        sslProtocol="SSL_TLS" 
        serverKeyAlias="<userid>-Liberty-Server"
        clientAuthenticationSupported="true"/>

   Additionally, if you want to ensure all clients must supply a valid SSL client certificate, add the clientAuthentication attribute to the SSL element as follows:

     <ssl id="defaultSSLConfig" keyStoreRef="racfKeyStore" 
        sslProtocol="SSL_TLS" 
        serverKeyAlias="<userid>-Liberty-Server"
        clientAuthenticationSupported="true"
        clientAuthentication="true"/>

2. You can authenticate a web request in CICS under the identity of the client user ID in step 2. Then, deploy the web application with a login-config element for CLIENT-CERT in the web.xml. The web.xml file can be found inside the source files for the web application that you are deploying.

     <login-config> 
   		 	<auth-method>CLIENT-CERT</auth-method> 
     </login-config

   Instead, if you want to allow failover to HTTP basic authentication if SSL client certificate authentication is not configured, add the webAppSecurity element to server.xml.

     <webAppSecurity allowFailOverToBasicAuth="true" /> 

3. Finally, set up CICS transaction security to authorize access to the CICS transaction based on the authenticated client user ID.
   For further information, the topic Authorizing users to run applications in a Liberty JVM server.