Thursday, January 28, 2016

Java client authentication for JBoss EAP over SSL

In order for a Java client to authenticate with JBoss EAP over SSL the following steps will need to be performed:


  • Create keystores for the server and client 
  • Configure a HTTPS connector in JBoss EAP 
  • Include the SSL configuration in your client application

Create keystores for the server and client 

The following steps describe how to create keystores for the server and the client and how to import these keystores into the truststores. In order for this exercise the keys generated are self-signed.

In order to complete the below you will need Java installed and the Java bin directory added to your systems Path variable.

Server keystore


Create the server's keystore 


  • Open a terminal / command prompt
  • Run the following command:
 
 keytool -genkeypair -alias jbossweb -keyalg RSA -keysize 1024 -keystore jbossweb.keystore -validity 3650 -keypass jbosswebpass -storepass jbosswebpass
  • -genkeypair (previously named genkey)
    • Generates a key pair
  • -alias
    • alias name of the entry to process
  • -keyalg                
    • key algorithm name
  • -keysize              
    • key bit size
  • -keystore            
    • keystore name
  • -keypass                  
    • key password
  • -storepass                
    • keystore password

Export the server's public key


  • Run the following command:
 
 keytool -exportcert -alias jbossweb -keystore jbossweb.keystore -file jbossweb.cer -keypass jbosswebpass -storepass jbosswebpass
  • -exportcert (previously named export) 
    • Exports certificate
  • -alias
    • alias name of the entry to process
  • -keystore            
    • keystore name
  • -file                  
    • output file name
  • -keypass                  
    • key password
  • -storepass                
    • keystore password

Client keystore


Create the client's keystore private/public key


  • Run the following command:
 
 keytool -genkeypair -alias client -keyalg RSA -keysize 1024 -keystore client.keystore -keypass clientpass -storepass clientpass -validity 3650
  • -genkeypair (previously named genkey)
    • Generates a key pair
  • -alias
    • alias name of the entry to process
  • -keyalg                
    • key algorithm name
  • -keysize              
    • key bit size
  • -keystore            
    • keystore name
  • -keypass                  
    • key password
  • -storepass                
    • keystore password
  • -validity
    • validity number of days

Export the client's public key


  • Run the following command:
 
 keytool -exportcert -alias client -file client.cer -keystore client.keystore -keypass clientpass -storepass clientpass
  • -exportcert (previously named export) 
    • Exports certificate
  • -alias
    • alias name of the entry to process
  • -file                  
    • output file name
  • -keystore            
    • keystore name
  • -keypass                  
    • key password
  • -storepass                
    • keystore password

Server truststore


  • Add the client's public key to the truststore of the server

 
 keytool -importcert -trustcacerts -alias client -file client.cer -keystore jbossweb.keystore -keypass jbosswebpass -storepass jbosswebpass
  • importcert (previously named import)
    • Imports a certificate or a certificate chain
  • -trustcacerts                   
    • trust certificates from cacerts
  • -alias
    • alias name of the entry to process
  • -file                  
    • input file name
  • -keystore
    • keystore name
  • -keypass
    • key password
  • -storepass
    • keystore password

Client truststore


  • Add the server's public key to the truststore of the client
 
 keytool -importcert -trustcacerts -alias jbossweb -file jbossweb.cer -keystore client.keystore -keypass clientpass -storepass clientpass
  • importcert (previously named import)
    • Imports a certificate or a certificate chain
  • -trustcacerts                   
    • trust certificates from cacerts
  • -alias
    • alias name of the entry to process
  • -file                  
    • input file name
  • -keystore
    • keystore name
  • -keypass
    • key password
  • -storepass
    • keystore password

More information on how to use the keytool command can be found here.

Configure a HTTPS connector in JBoss EAP 6


  • Open the JBoss EAP configuration file for your server, for example if you are using default standalone configuration then open the standalone.xml within the JBOSS_HOME/bin directory. 
  • Add a HTTPS connector to the org.jboss.as.web subsystem. You can add it after the HTTP connector that should already be there, example:
 
 <subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
   <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
   <connector name="HTTPS" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true">
     <ssl name="https"
       key-alias="jbossweb"
       password="jbosswebpass"
       certificate-key-file="${jboss.server.config.dir}/server.keystore"
       verify-client="true"
       ca-certificate-file="${jboss.server.config.dir}/server.keystore"/>
   </connector>

   <virtual-server name="default-host" enable-welcome-root="true">
     <alias name="localhost"/>
     <alias name="example.com"/>
   </virtual-server>
 </subsystem>
  • In the above example the keystore (certificate-key-file) is also used as the truststore ( ca-certificate-file).
  • The verify-client attribute is equivalent to Tomcats clientAuth attribute. 
  • When using keytool to create keystores, JBoss will compare the value you enter in the name against the hostname and will complain if it does not match You can set the following JVM argument to have JBoss ignore the hostname:
  • -Dorg.jboss.security.ignoreHttpsHost=true

Include the SSL configuration in your client application

  • Within your standalone client application the following properties will need to be set to point to the client's keystore/truststore. 
  • Adding these system properties will set the keystore/truststore for the whole JVM.
 
 System.setProperty("javax.net.ssl.keyStore", "/path/to/client.keystore");
 System.setProperty("javax.net.ssl.keyStorePassword", "clientpass");
 System.setProperty("javax.net.ssl.trustStore", "/path/to/client.keystore");
 System.setProperty("javax.net.ssl.trustStorePassword", "clientpass");
  • Once those properties are set you should be able to make the necessary HTTPS call (an example would be a webservice request over SSL).