04 August 2016

Apache Fediz with Client Certificate Authentication (X.509)

In this blog post I will explain how to generate your own SSL key-pair to perform certificate based authentication for SSO purposes with Apache Fediz IDP.

Client Key Authentication

Generate Key-Pair

I like to use the keystore-explorer under windows, because it makes certificate management very easy. You don't have to lookup console commands but instead you get nice Wizards to get it all done. If you are running linux I can recommend this page to you, because it contains the most common Java Keytool commands you will need.

After starting keystore-explorer create a new keykeystore (PKCS #12). Next click generate keypair. RSA with 2.048 bit should be fine. Now you should enter your name and after that click on extensions to define an "Extended Key Usage" for "TLS Web Client Authentication":



Make sure that this extension flag is really set for your key-pair. I first tried without this extension and I could not get any of my browsers to even show me a certificate selection popup when authentication against the IDP.

Since you will have to import your personal certificate to the IDP truststore later on, I would recommend to you to export your public certificate at this step:



Import Key-Pair to your Browser

Once your key generation was successful, you need to add this key-pair to your browser:

In Chrome you need to open your settings -> extended settings ->  HTTPS/SSL -> Manage Certificates -> Import select your p12 certificate and make sure that all extensions from the certificate are included:


Since chrome and IE will use the same certificate store. So there is no need to do this twice if you have done this once for one of the two.

For Firefox you need to go to Options -> Advanced -> Certificates -> View Certificates -> Your Certificates -> Import


I had to restart my machine before my browsers would show me the option to select my certificates for client authentication. Some articles in the internet also recommended to add the IDP URL to your list of trusted sides in the Internet Explorer.

Setup Fediz IDP

You can find a full IDP / Web-App setup instruction in one of my previous articles. In this article I will only highlight steps that are related to SSL slient authentication.

Add SSL support to your tomcat conf/server.xml
<Connector port="9443" protocol="org.apache.coyote.http11.Http11Protocol"
     maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
     keystoreFile="idp-ssl-key.jks"
     keystorePass="tompass"
     truststoreFile="idp-ssl-trust.jks"
     truststorePass="ispass"
     truststoreType="JKS"
     clientAuth="want"
     sslProtocol="TLS" />
If you want all clients to authenticate with a client SSL Certificate against your IDP you must set the clientAuth attribute to "true" instead of "want". However if you want to support multiple authentication styles even without a client certificate you should set clientAuth to "want".

Open your idp-ssl-trust.jks with your keystore-explorer to import your personal certificate from your desktop (see previous export step above).

Validate Setup

Open your browser to the Fediz Hello World page: https://localhost:9443/fediz-idp/. Your browser should show you a selection popup for your client certificate:


If you imported this certificate correctly to your tomcat IDP truststore you should now see a "Hello World!" welcome page from Fediz.

Please also take a look at colms blog about this topic.

3 comments: