Here's a little Howto on making that JSP password-authenticated, even if you don't know much about Tomcat. I have tried to boil it down to these basics, after wrangling with it for awhile. Where possible, I've tried to avoid duplicating the tomcat howto, but there is overlap, and readers should trust the folks at jakarta above anything you read here.

Howto Set Up a Password-Authenticated JSP

by RandyNovick

Assumptions

I set up the authentication mechanism on tomcat 4.0.6. using cleartext passwords to start with, and then going to the MD5 digester. I assume that you have tomcat up and running, and that you've already picked (and are using) a port to show the JSP. I also assume that you know a little bit about how to start and shutdown tomcat.

Getting Ready

First, I recommend starting with the jakarta documentation for tomcat realms, located at the following URL:

http://jakarta.apache.org/tomcat/tomcat-4.0-doc/realm-howto.html

Start out with the memory realm, and look at the example login link they have down near the bottom – it's pretty neat, but it uses forms, and I didn't want to dip my toes in the complexity of forms. (If anyone wants to add a similar howto that addresses forms, go for it.)

Start Your Edits

The realm I used was the memory realm, and it's loaded by default in the server.xml file that ships with tomcat (look for the first instance of a "<Realm>" element). It looks like this:

<Realm className="org.apache.catalina.realm.?MemoryRealm" />

Now that you know where it is, you can leave it alone until you're ready to have it use encrypted passwords.
The first thing to do in terms of making changes is to add the following lines to the end of cruisecontrol's web.xml, after the servlet-mapping element:

<security-constraint>
  <!-- display-name>Example Security Constraint</display-name -->
  <web-resource-collection>
    <web-resource-name>Protected Area</web-resource-name>
    <!-- Define the context-relative URL(s) to be protected -->
    <url-pattern>/buildresults</url-pattern>
    <!-- If you list http methods, only those methods are protected -->
    <http-method>DELETE</http-method>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
    <http-method>PUT</http-method>
  </web-resource-collection>
  <auth-constraint>
    <!-- Anyone with one of the listed roles may access this area -->
    <role-name>tomcat</role-name>
    <!-- role-name>role1</role-name -->
  </auth-constraint>
</security-constraint>

<login-config>
  <auth-method>BASIC</auth-method>
  <realm-name>CruiseControl</realm-name>
</login-config>

Note that you're adding two distinct elements: the <login-config>, which is (by virtue of the BASIC method) going to allow you to enter the password once and keep an open session for as long as you want it. The closest option after that is the FORMS method, which is a little more restrictive. Let the tomcat documentation show you the way with these options. The other element (<security-constraint>) is the most key, because it defines where your jsp lives, and what methods will be protected there.
Then, I went to the tomcat-users.xml file in $CATALINA_HOME/conf and made an entry similar to one of the others given there. Honestly, I commented out the ones that were there and added just one user line:

<user name="rnovick" password="foobar" roles="tomcat"/>

If you have not stoppped and restarted tomcat after making all these edits, do so now, and try the link to the jsp. You should get a browser-generated login, and the JSP should show up as soon as you get past it.

Going from Cleartext to Encryption

It would be nice if we could all get by without having to worry about storing our passwords in cleartext in a pretty common place on our hardware, but we don't live in such a world. The next step is to make those cleartext passwords a little more inscrutable.

Once you have the cleartext password-authenication mechanism going, you can easily switch to MD5-digestible passwords by changing the follwing line (there are two - pick the one at the top, or do them both if you want the authentication to be prepared for Apache) in $CATALINA_HOME/conf/server.xml from:

<Realm className="org.apache.catalina.realm.?MemoryRealm" />

to:

<Realm className="org.apache.catalina.realm.?MemoryRealm" digest="MD5"/>

... and replacing the cleartext version of the password with the MD5 version you get from calling:

java org.apache.catalina.realm.RealmBase -a MD5 {cleartext-password}

Just like before, stop and restart tomcat to let the changes take effect.

Troubleshooting

The best information you'll get is from the tomcat logs in $CATALINA_HOME/logs. Take special note of the messages that tomcat gives you through the browser, as these will point you to problem areas.

One pitfall I noticed is that if you don't properly set the <url-pattern> element to the path to the buildresults JSP, you'll get 404s that seem pretty unexplainable at the outset.

That about covers it. I had success with SHA and MD5 encryption, but not MD2. Added pointers and refinements to this howto are appreciated.

– R