Page History

...

If things go wrong, here's some places to look:TO BE CONTINUED TOMORROW!

• Is the client certificate properly installed? If not, your browser will not offer the certificate for you to choose on login.
• Is the client certificate authority properly imported in the truststore on the server? If not, the browser will not know to use your installed client certificate.
• Is the server certificate valid and properly installed?
• Is your client certificate's SubjectDN configured as a user in the Realm you are using? Depending on which realm you are using you will have to add the user in different ways (for example, to the file "tomcat-users.xml" if using Tomcat's MemoryUserDatabase).
  

Adding Fallback to Form Authentication

Make sure the class you downloaded, "SSLWithFormFallbackAuthenticator.java" is compiled and installed, for example in the server/classes folder of your Tomcat installation. Alternatively, you can pack the compiled class in a JAR file, and place the JAR in the server/lib folder of your Tomcat installation.

The class implements a Tomcat "Valve", and needs to live within the server directory of your Tomcat and cannot be part of your web application's WAR, since it is used by Tomcat for authentication, which happens before your web application is called, and hence outside your web application's classloader.

Configure your Web-Application to use this class for authentication. This is done in two steps:

1. Remove the <auth-method> element from your web application's deployment descriptor. The <login-config> element should still contain the <form-login-config> elements to configure the form, but NO <auth-method> tag.

<login-config>
	  <!-- auth-method is commented out for fallback authentication -->
	  <!-- <auth-method>FORM</auth-method> -->
	  <form-login-config>
	  	<form-login-page>/pub/login.jsp</form-login-page>
	  	<form-error-page>/pub/loginerror.jsp</form-error-page>
	  </form-login-config>
</login-config>

2. Configure the authentication valve. The authentication valve can be configured in two places. Either in your Tomcat server.xml file, or your application's context.xml file. The context.xml file lives in the directory "META-INF" within your WAR file. The following is a sample context.xml file for fallback authentication:

<?xml version="1.0" encoding="UTF-8"?>
<Context path="/mycontextpath" >
	<Valve className="at.telekom.tomcat.security.SSLWithFormFallbackAuthenticator" />
</Context>

If you have configured the <Context> element in your Tomcat server.xml file, you can also place the <Valve> element there.

You will need to restart tomcat to apply these changes.

Testing Fallback Authentication

This is best tested with two different browsers (eg Firefox and IE):

1. Install the client certificate in one of the Browsers (if it isn't already)

2. Fire up this browser and visit your protected page 3. You should be promted for the certificate as before, select it as before 4. You should be logged into the site, as before 5. Now fire up the other browser, the one without the certificate 6. Attempt to access your protected page 7. Depending on your Browser you may be promted about the certificate - click "cancel" if this is the case 8. You should be taken to the login form of your application 9. Log in using the form. You should be granted access, as before

How does it work?

The code is tested with Tomcat 5.5.17 and 5.5.20. It will probably work with only minor modifications for other Tomcat 5.5 versions. It has been tested using Java 1.5.

In short, this code works because:

• Tomcat uses the auth-config element of the deployment descriptor to create an Authentication Valve
• If this element is missing, Tomcat does not complain, and simply installs no Authenticator
• By manually adding our own Authentication Valve we add authentication back to the application
• Our authentication valve inherits from the FormAuthenticationValve, and adds functionality from the SSL authenticator
• It simply first tries SSL Auth, and failing that makes a second attempt using form auth
  
  

Comments, Feedback, Support

This code is supplied back to the apache foundation, without any support or warranty. Use at your own risk. The author and his employer assume no responsibility for damages resulting in the use of this code or these instructions.

Feel free to use the code in any way you want but do not expect support.

Should you have questions about the code, please feel free to contact me (the Author) at: runger -AT- aon.at