ONJava.com -- The Independent Source for Enterprise Java
oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Web FORM-Based Authentication
Pages: 1, 2

FORM-based Authentication

  Related Reading:
Java Security, 2nd Edition

Java Security, 2nd Edition
By Scott Oaks
2nd Edition May 2001 (est.)
0-596-00157-6, Order Number: 1576
550 pages (est.), $39.95 (est.)

We will go through the simple steps required in setting up the standards-based FORM-based authentication.

  1. Configure the web.xml to use FORM-based authentication
  2. Build the login form

Step One: Configure the web.xml to use FORM-based authentication

Let's tell the container to use FORM-based authentication in our web.xml file.


First, we specify "FORM" as the auth-method (instead of BASIC, DIGEST, or CLIENT-CERT), and then we tell the system that the Web page LoginForm.html has the <FORM> which will authenticate a user. If we try to access a page under /secure we will first have to fill out the form in LoginForm.html and authenticate. If our authentication fails (we do not log in correctly as the system user), then we will be sent to LoginError.html.

Step Two: Build the login form

Now we build out login form. We have to follow a couple of conventions that are defined in the Servlet API specification:

  • Our <form>'s action field must be j_security_check
  • We must have form fields j_username, and j_password that hold the username and password to authenticate with

So, our LoginForm.html will simply look like:

<form method="POST" action="j_security_check">

  Username: <input type="text"     name="j_username"><br />
  Password: <input type="password" name="j_password"><br />
  <br />

  <input type="submit" value="Login">
  <input type="reset"  value="Reset">


Let's say a browser tries to access something under /secure in our deployed Web application. The container will do the following:

  1. Save away the resource that the user was trying to access.
  2. Send back the LoginForm.html.
  3. When the user fills out the username and password and submits it back, the container tries to authenticate the user. If the auth fails the LoginError.html is sent back to the browser.
  4. If the authenticated user is part of the admin role (e.g. system user), the original resource will be sent back to the user, otherwise the LoginError.html will.

And that is it! Using FORM-based authentication is easy. You configure the web.xml to point to the correct login form and error page, and then make sure that the form follows the conventions of using j_security_check, j_username, and j_password.

Enforcing SSL

Lastly, we can declaratively control the level of security in the transport mechanism using the following tag in web.xml:

  <description>SSL not required</description>

There are three possible values for the <transport-guarantee>:

Transport Description

No encryption is required (http is fine)


The data must be encrypted, so that other parties can not observe the contents (e.g. enforce SSL)


The data must be transported so that the data cannot be changed in transit. Most servers use SSL for this value too, although in theory you could use some hashing algorithm, as encryption is not required


We have shown that you can configure many security options for your Web-based applications, adding support for a standard way to do FORM-based authentication that the Web container takes care of for you. Please download the sample Web application and test it out by trying to access /logintest/secure/ (assuming that you deploy the Web application as "logintest").

Dion Almaer is a Principal Technologist for The Middleware Company, and Chief Architect of TheServerSide.Com J2EE Community.

Return to ONJava.com.