Covering J2EE Security and WebLogic Topics

The Mysterious CLIENT-CERT

Note: This post is about one of the web application authentication methods defined by the Java Servlet specification. You can also read a larger article I wrote describing how all of the authentication methods work. It includes the content below.


The CLIENT-CERT authentication method is typically used for identifying the user by his X.509 certificate. This is a special usage of the Secure Sockets Layer (SSL) where both the server and the user are identified by their own certificates. As a result, this is a very strong form of authentication. But there’s more to CLIENT-CERT than you might realize.

Encounters with SSL on the Internet are almost always one-way authentication where only the server presents a certificate to the client. Think of ordering on Amazon.com, for example. The protocol switches from http to https and the little lock symbol appears on your browser. This signifies that the link is encrypted and the certificate presented by Amazon was trusted since your browser trusts certificates issued by Verisign. (Note: Public Key Infrastructure (PKI) and trust are beyond the scope of this post.) Even so, the server still does not know the identity of the user. User authentication is left to another mechanism such as username/password.

On the other hand, two-way SSL retains the server authentication part but adds the requirement that the client present a certificate that the server trusts. Assuming that both sides agree, the encrypted link is established and both sides are mutually authenticated via SSL. This technique is rare on the Internet since most people don’t have personal certificates. However, there is traction for two-way SSL on corporate intranets and in B2B scenarios. Once a mutually authenticated link is established, there is no further need for user authentication since the certificate already positively identified the user.

Whew, that was a lot of backstory on two-way SSL. Hopefully, though, the purpose of the CLIENT-CERT auth-method is now clear. Using CLIENT-CERT typically means that your application wants to authenticate the user via two-way SSL.

But wait, there’s more… 😉

Configuring CLIENT-CERT

Specifying CLIENT-CERT in web.xml is not sufficient for actually having the whole process work. I won’t go into details, but here are the additional configuration items you need to handle:

  • Ensure that your server has a server certificate
  • Ensure that your users trust your server certificate’s issuer (the CA certificate)
  • Ensure that your server is listening on the SSL port
  • Ensure that your users have certificates
  • Ensure that your server trusts the user certificate issuer(s)
  • (WebLogic) Ensure that an Identity Asserter handles the X.509 certificate and can map the certificate to a known user

The list above describes in general terms what must be configured for mutual authentication to work. In WebLogic, it’s an identity assertion security provider that handles X.509 certificates. The identity asserter isn’t triggered unless CLIENT-CERT is present in web.xml.

Once all of this is properly configured, the stars line up just so, and you dispose of the hair you pulled out trying to get it right, you’re ready to enjoy authentication via two-way SSL.

But wait, there’s more…

Perimeter Authentication Tokens

According to the servlet specification, the intention of the CLIENT-CERT authentication method was for two-way SSL as described above. However, BEA WebLogic not only supports the spec but expands upon it to support any type of perimeter authentication token.

With WebLogic, X.509 certificates, SAML tokens, Kerberos tickets, etc., are all examples of perimeter authentication tokens. Of the examples presented, the WebLogic 8.1 security framework only supports X.509 out of the box, but you can write or buy custom identity asserters that handle any type of token that can be presented as string. That’s pretty nifty.

And it all starts with the mysterious CLIENT-CERT authentication method.