To begin, I installed Java (say version 6.0 or better), and then Eclipse (or MyEclipse, if you like). Then I updated Eclipse with the Subversive plug-in, to access my subversion repository to persist and pull my code onto different machines as I travel.
(e.g. https://failship.company.com/repo).

Upon checkout, I created a Dynamic Web Project or whatever name Eclipse provides for a basic web application. Take your time here and step through each of the wizard screens, because some setting changes are subtle and have major pain-in-the-butt ripple effects.

You’ll have to create the basic LoginModule and Principal implementations to support your custom login code. That information was provided everywhere on the Web. My frustration was in putting it all together. Anyway, out of the scores of resources I used to investigate, I found this one to be pretty concise:

http://blog.frankel.ch/tech/dev/java/jee/custom-loginmodule-in-tomcat

If you are going to test with Tomcat 6.0, you must add the following tag to the conf/context.xml file.

<Loader delegate=”true”/>

Otherwise, you might get some

“java.lang.ClassCastException: org.apache.catalina.util.DefaultAnnotationProcessor cannot be cast to org.apache.AnnotationProcessor”

exception.

While you have context.xml open, you will have to add a ‘Realm’ for Container Security, to enable our LoginModule secure access. The 1st step is to enable the JaasRealm, typically by pasting in the existing entry as follows:

<!– Inserted to enable MyAccessLoginModule. You will have to launch tomcat
with -Djava.security.auth.login.config= pointing to the jaas.config file: –>
<Realm className=”org.apache.catalina.realm.JAASRealm”
appName=”MyAccess”
userClassNames=”com.company.myAccess.realm.MyAccessUserPrincipal”
roleClassNames=”com.company.myAccess.realm.MyAccessRolePrincipal”>
</Realm>

Next, I had to create a jaas.conf file to declare my LoginModule implementation. Notice that this has the same name as the “appName” provided in the <realm> definition above. Here’s the contents of jaas.conf:

/** Login Configuration for the JAAS Sample Application **/
MyAccess {
com.company.myAccess.realm.MyAccessLoginModule requisite debug=true;
};

The realm also needs to know how to find the jaas.config file and it does this through the Java system property, set as a JVM argument, for the variable “java.security.auth.login.config”. You can set this, in eclipse by configuring a “Server”, typically through the Window->Preference menu (or in MyEclipse under its preferences). The JVM takes a -D argument, to define the variable, as in:

-Djava.security.auth.login.config=C:”/Documents and Settings/sandrews/Workspaces/MyEclipse Blue/myAccess-20090902/jaas.config”

While you’re here, you may want to add any custom defined variables for your web application. My LoginModule read the tomcat-users.xml file as well, so I designated it with the follow arguments:

-DTomcatUsersXmlFile=C:”/Program Files/Apache Software Foundation/Tomcat 6.0/conf/tomcat-users.xml”

Again, this last argument was custom to my application, so it’s necessary for your web app.

Next, edit the data source for your user authentication, as in conf/tomcat-users.xml, to add the role, say ‘myAccess’, and the user, like ‘bsmith’ for example:

<tomcat-users>
<role rolename=”myAccess”/>
<user name=”bsmith” password=”123qwe” roles=”myRole”/>
</tomcat-users>

Your web application’s WEB-INF/web.xml should set the security restrictions,
as in:

<!– Define a Security Constraint on this Application –>
<security-constraint>
<web-resource-collection>
<web-resource-name>Secured resources</web-resource-name>
<url-pattern>/jsp/*</url-pattern>
<url-pattern>/html/*</url-pattern>
<url-pattern>/index.jsp</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>myRole</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>Unsecured resources</web-resource-name>
<url-pattern>/images/*</url-pattern>
<url-pattern>/css/*</url-pattern>
</web-resource-collection>
</security-constraint>
<security-role>
<description>Role required to see admin pages.</description>
<role-name>myRole</role-name>
</security-role>
<!– Define the Login Configuration for this Application –>
<login-config>
<auth-method>FORM</auth-method>
<realm-name>MyAccess</realm-name>
<form-login-config>
<form-login-page>/jsp/userLoginForm.jsp</form-login-page>
<form-error-page>/jsp/userLoginForm.jsp?action=error</form-error-page>
</form-login-config>
</login-config>

Notice that the ‘security-constraint’ wraps a ‘auth-constraint’ which references a ‘role-name’ which maps to a ‘security-role’.

Lastly, I had to ensure that when the application server loads (not my web application, but the server), it has access to load my LoginModule implementation and supporting classes. Hence I used an ANT script to jar up my *.class files and deploy them under tomcat’s lib directory, as in:

lib/myAccess.jar

This was key, and without it, I was left in the dark, not knowing that the WEB-INF/classes deployment (the default) was not enough. The realm is loaded before your web app, and needs to be ready with the data source connections open, etc. Once this was done, I was able to login using my custom LoginModule.

Again, some of my frustrations were eleviated through the information found at:

http://blog.frankel.ch/tech/dev/java/jee/custom-loginmodule-in-tomcat

So some major Thanks go out to that Nicolas Frankel guy, and Good Luck!