Example: Form login

The following is an example of how the form should be coded into the HTML page: 
  <form method="POST" action="j_security_check">
    <input type="text" name="j_username">
    <input type="text" name="j_password"> 
  <\form>

The action of the login form must always be j_security_check. The j_username input field should be used to get the user name, and the j_password input field should be used to get the user's password.

On receiving a request from a Web client, the Web server sends the configured Form page to the client and preserves the original request. When Web server receives the completed Form page from the Web client, it extracts the username and password from the form and authenticates the user. On successful authentication, Web server redirects the call to original request. If authentication fails, the web server redirects the call to the configured error page.

Here is an example of an HTML login page:

  <!-- login.html -->
  <!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.0 Transitional//EN">
  <html>
  <head>
    <meta http-equiv="Pragma" content="no-cache">
    <title>Security FVT Login Page </title>
  </head>

  <body>

    <h2>Form Login</h2>

    <form method="post" action="j_security_check">
      <p>
        <strong>You may have entered an invalid user ID
          or password. To correct the problem, please enter
          your correct user ID and password. If you have
          forgotten your user ID or password, please contact
          the server administrator.</strong>
      </p>
      <p>
        <strong>Please enter user ID and password:</strong>
        <br>
        <strong>User ID</strong>
        <input type="text" size="20" name="j_username">
        <strong>Password</strong>
        <input type="password" size="20" name="j_password">
      </p>

      <p>
        <strong>And then click this button:</strong>
        <input type="submit" name="login" value="Login">
      </p>
    </form>

  </body>
  </html>

Here is an example error page in a JSP file:

  <!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.0 Transitional//EN">
  <html>
  <head><title>A Form login authentication failure occurred</head></title>
  <body>
  <H1><B>A Form login authentication failure occurred</H1></B>
  <P>Authentication may fail one of many reasons.  Some possibilities include:
  <OL>
  <LI>The user-id or password may be entered incorrectly; either misspelled or the
    wrong case was used.
  <LI>The user-id or password does not exist, has expired, or has been disabled.
  </OL>
  </P>

  </body>
  </html>

After you configure the Web application to use form-based authentication, the deployment descriptor contain the login configuration as shown below:

<login-config id="LoginConfig_1">
  <auth-method>FORMauth-method>FORM>
  <realm-name>Example Form-Based Authentication Area</realm-name>
  <form-login-config id="FormLoginConfig_1">
    <form-login-page>/login.html</form-login-page>
    <form-error-page>/error.jsp</form-error-page>
  </form-login-config>
</login-config>

Here is the directory structure for a sample Web application archive (WAR) file that shows the login and error pages for these examples:

  META-INF
  META-INF/MANIFEST.MF
  login.html
  error.jsp
  WEB-INF/
  WEB-INF/classes/
  WEB-INF/classes/aServlet.class

Form logout

Form logout is a mechanism that allows uses to logout from an application without having to close all Web browser sessions. After the user logs out, access to a protected Web resource requires reauthentication. This feature is not required by J2EE specifications but is provided as an additional feature in WebSphere security.

A form logout works in the following manner:

  1. The URI for the logout-form URI is specified in the Web browser.

  2. The browser loads the form.

  3. The user clicks the submit button of the form to logout.

  4. The WebSphere security code logs out the user.

  5. Upon logout, the user is redirected to a logout exit page.

Form logout does not require any attributes in any deployment descriptor. It is simply an HTML or JSP file that is included with the Web application. The form logout page is like most HTML forms. However, the form logout page, like the form login page, it has a special POST action that is recognized by the Web container. The Web container then dispatches it to a special internal WebSphere form logout servlet. The POST action in the form logout page must have a value of ibm_security_logout.

A logout exit page can be specified in the logout form. The exit page can be a HTML or JSP file to which users a redirected after they log out. The logout exit page must reside within the same Web application as the logout form. The logout exit page is simply specified as a parameter in the form logout page. If no logout exit page is specified, a default logout HTML message is returned to the user.

Here is a sample HTML logout form. This form configures the logout exit page to redirect the user back to the login page after logout.

<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.0 Transitional//EN">
<html>
<head>
  <meta http-equiv="Pragma" content="no-cache">
  <title>Logout Page </title>
<head>

<body>
  <h2>Sample Form Logout</h2>
  <form method="post" action="ibm_security_logout" name="logout">
    <p>
      <strong> Click this button to logout:</strong>
      <input type="submit" name="logout" value="Logout">
      <input type="hidden" name="logoutExitPage" value="/login.html">
    </p>
  </form>

</body>
</html>