Client Certificate based authentication is not the most common way to protect resources in JBoss, since the most common used model is Basic Auth over SSL, however, if for some reason you should need this, this guide will help you good on the way, since it has been proven to work on JBoss 6.1  ( This is subject to major changes in JBoss 7 and wildfly)

The following description is meant as an addition to the guide already available from JBoss here  ->  https://community.jboss.org/wiki/BaseCertLoginModule

In order to setup Client Certificate based authentication you should.

  1. Obtain the client certificate to use, with both it’s private and public key, for example as a pkcs12
    1. Strictly you down need the private part to setup jboss, but if you wan’t to test the connection you need the private parts as well
  2. Create a keystore on the jboss server. for example in the conf directory, take note of the password you use, you need this when configuring the BasicCertLoginModule.
    1. import the public certificate to the keystore
      1. For example if you have it in DER format : keytool -import -alias your-alias -keystore "yourstore" -file certificate.der
      2. NB. if the keystore doesn't exist it will create one and prompt your for password to use for it
    2. make sure it’s ALIAS is exactly the same as the DN of the certificate, else it will not work in jboss
  3. Set up af Security domain in jboss-service.xml  ( look at the guide linked to )
  4. Make a application Policy in login-config.xml  ( look at the guide linked to )
  5. Make a roles.properties containing the roles you need for your webapp, webservice. The roles should be an accept copy of the DN of the certificate pointing to a specific role. The description at JBoss says it should be the alias from keystore, however this is in lower case, so do not use this, but instead use the DN from the certificate preserving it’s case.  ( look at the guide linked to )
  6. Setup you web.xml and jboss.xml accordingly ( look at guide )
  7. Some clients may require SSL Renegotiation, and the BaseCertLoginModule from JBoss will only work if this is allowed. This is a setting in the Connector at jbossweb.sar/server.xml. You need to specify the following attribute : allowUnsafeLegacyRenegotiation=true  . As indicated this should be used with care, since it’s possible to make a man in the middle attack on SSL. See http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-3555  . This is something that is also determined by the client, or example SOAPUI up to 4.5.2 requires this to work.
  8. It can be a good idea to enable trace logging for org.jboss.security if you have problems getting this to work.

Testing from SOAPUI

If you use soapui to test this you can setup a keystore to be used for SSL in the preferences->ssl tab , this has to be a PKCS12 keystore. Simply add the keystore, put in the password, and tick the “Client Authentication” checkbox

Bear in mind that SOAPUI sometimes fail first time it loads the keystore, a known bug in soapui, just change keystore, say ok, and then change back to correct keystore, this will be fine.

It’s not possible to have “per project” ssl so it’s global for all requests

If you use a self signed certificate or just a certificate with a more exotic issuer, you should add the issuer’s certificate to you Java runtime’s cacerts , else jboss will not validate due to a broken certificate chain.