1.7. Enabling Form-based Authentication

Form-based authentication provides flexibility in defining a custom JSP/HTML page for login, and a separate page to which users are directed if an error occurs during login.

Form-based authentication is defined by including <auth-method>FORM</auth-method> in the <login-config> element of the deployment descriptor, web.xml. The login and error pages are also defined in <login-config>, as follows:

<login-config>
  <auth-method>FORM</auth-method>
  <form-login-config>
    <form-login-page>/login.html</form-login-page>
    <form-error-page>/error.html</form-error-page>
  </form-login-config>
</login-config>

<login-config>
  <auth-method>FORM</auth-method>
  <form-login-config>
    <form-login-page>/login.html</form-login-page>
    <form-error-page>/error.html</form-error-page>
  </form-login-config>
</login-config>

When a web application with form-based authentication is deployed, the web container uses FormAuthenticator to direct users to the appropriate page. JBoss Enterprise Application Platform maintains a session pool so that authentication information does not need to be present for each request. When FormAuthenticator receives a request, it queries org.apache.catalina.session.Manager for an existing session. If no session exists, a new session is created. FormAuthenticator then verifies the credentials of the session.

Once verified, the session ID is assigned as part of a cookie, and then returned to the client. This cookie is expected in subsequent client requests and is used to identify the user session.

The cookie passed to the client is a name value pair with several optional attributes. The identifier attribute is called JSESSIONID. Its value is a hex-string of the session ID. This cookie is configured to be non-persistent. This means that on the client side it will be deleted when the browser exits. On the server side, sessions expire after 60 seconds of inactivity, at which time session objects and their credential information are deleted.

Say a user attempts to access a web application that is protected with form-based authentication. FormAuthenticator caches the request, creates a new session if necessary, and redirects the user to the login page defined in login-config. (In the previous example code, the login page is login.html.) The user then enters their user name and password in the HTML form provided. User name and password are passed to FormAuthenticator via the j_security_check form action.

The FormAuthenticator then authenticates the user name and password against the realm attached to the web application context. In JBoss Enterprise Application Platform, the realm is JBossWebRealm. When authentication is successful, FormAuthenticator retrieves the saved request from the cache and redirects the user to their original request.