30.5 Creating a Login Page

The login page for a web application should use the J2EE security container login method j_security_check as a method that the form posts. Figure 30-7 shows a sample login page from the SRDemo application.

Figure 30-7 Sample Login Page from the SRDemo Application

CAUTION:

When you create the login page, you may use JSP elements and JSTL tags. Your page can be formatted as a JSFX document, but due to a limitation in relation to JSF and container security, JSF components cannot be used.

To create a web page for the login form:

With the user interface project selected, open the New Gallery and select JSP from the Web Tier - JSP category. Do NOT select the Web Tier - JSF category to create a JSPX document as a login form.
In the Create JSP wizard, choose JSPX Document type for the JSP file type. The wizard lets you create a JSPX document without using managed beans.
On the Tag Libraries page of the wizard, select All Libraries and add JSTL Format 1.1 and JSTL Core 1.1 to the Selected Libraries list.
Click Finish to complete the wizard and add the JSPX file to the user interface project.
In the Component Palette, select the JSTL 1.1 FMT page, and drag SetBundle into the Structure window for the JSPX document so it appears above the title element.
In the Insert SetBundle dialog, set BaseName to the package that contains the resource bundle for the page. For example, in the SRDemo application, it is oracle.srdemo.view.resources.UIResources.
Optionally, drag Message onto the title element displayed in the Structure window. Double-click the Message element and set the key property to the resource bundle's page title key. For example, in the SRDemo application, the key is srlogin.pageTitle. Delete the string title leftover from the page creation.
In the Component Palette, select the HTML Forms page and drag Form inside the page body. In the Insert Form dialog, set the action to j_security_check and set the method to post.
Drag Text Field for the user name into the form and set the name to j_username.
Drag Password Field into the form and name it j_password.
Drag Submit Button into the form with label set to Sign On.
In the Component Palette, again select the JSTL 1.1 FMT page, and drag two Message tags into the form so they appear beside the input fields. Set their key properties. For example, in the SRDemo application, the resource keys are srlogin.password and srlogin.username.

Example 30-3 shows the source code from the SRDemo application's login page. This JSPX document uses only HTML elements and JSTL tags to avoid conflicts with the security container when working with JSF components. The security check method appears on the <form> element and the form contains input fields to accept the user name and password. These fields assign the values to the container's login bean attributes j_username and j_password, respectively.

Example 30-3 Sample Source from SRLogin.jspx

<html>
    <head>
      <meta http-equiv="Content-Type"
            content="text/html; charset=windows-1252"/>
      <fmt:setBundle basename="oracle.srdemo.view.resources.UIResources"/>
      <title>
        <fmt:message key="srdemo.login"/>
      </title>
    </head>
    <body>
        ... omitting the "number of attempts" checking logic ... 
        <form action="j_security_check" method="post">
          <table cellspacing="3" cellpadding="2" border="0" width="100%">
            <tr>
              <td colspan="3">
                <img height="69" width="340"
                     src="/SRDemo/faces/images/SRBranding.gif"
                     alt="SRDemo Logo"/>
                <hr/>
              </td>
            </tr>
            <tr>
              <td colspan="3">
                <h1>
                  <fmt:message key="srlogin.pageTitle"/>
                </h1>
              </td>
            </tr>
            <tr>
              <td colspan="3">
                <c:if test="${sessionScope.loginAttempts >0}">
                  <h3><fmt:message key="srdemo.badLogin"/></h3>
                </c:if>
              </td>
            </tr>
            <tr>
              <td>&amp;nbsp;</td>
              <td> </td>
              <td rowspan="7">
                <table border="1" cellpadding="5">
                  <tr>
                    <td>
                      <fmt:message key="srlogin.info"/>
                    </td>
                  </tr>
                </table>
              </td>
            </tr>
            <tr>
              <td>&amp;nbsp;</td>
            </tr>
            <tr>
              <td width="120">
                <b><fmt:message key="srlogin.username"/></b>
              </td>
              <td>
                <input type="text" name="j_username"/>
              </td>
            </tr>
            <tr>
              <td width="120">
                <b><fmt:message key="srlogin.password"/></b>
              </td>
              <td>
                <input type="password" name="j_password"/
              </td>
            </tr>
            <tr>
              <td> </td>
              <td>
                <input type="submit" name="logon" value="Sign On"/>
              </td>
            </tr>
            <tr>
            </tr>
              <td>&amp;nbsp;</td>
            <tr>
              <td>&amp;nbsp;</td>
            </tr>
            <tr>
              <td>&amp;nbsp;</td>
            </tr>
            <tr>
              <td colspan="3">
                <hr/>
              </td>
            </tr>
          </table>
        </form>
      </c:if>
    </body>
</html>

30.5.1 Wiring the Login and Error Pages

To allow the web container to perform authentication, the web.xml file must contain the login configuration information that specifies the page to display for log in and another page to display when log in fails because the user could not be authenticated.

To configure how login is to be handled:

In the Application Navigator, locate web.xml in the WEB-INF folder.
Right-click web.xml and choose Properties.
In the Web Application Deployment Descriptor dialog, select Login Configuration.
Choose Form-Based Authentication and enter the path name for both the login and error page. The path specified for the login page and error page is relative to the document root that will be used to authenticate the user. For example, in the SRDemo application, the path infrastructure/SRLogin.jspx is used for both the login and error page.

Figure 30-8 shows the web.xml editor with the Login Configuration definition displayed.

Figure 30-8 Web Application Deployment Descriptor Dialog, Login Configuration Panel

Login configuration in the Deployment Descriptor editor.

30.5.2 What Happens When You Wire the Login and Error Pages

When you define the web.xml login configuration information, JDeveloper creates these definitions:

<login-config>
    <auth-method>FORM</auth-method>
    <form-login-config>
      <form-login-page>infrastructure/SRLogin.jspx</form-login-page>
      <form-error-page>infrastructure/SRLogin.jspx</form-error-page>
    </form-login-config>
  </login-config>

Because you selected Form-based authentication, to specify user-written HTML Form for authentication, the page servlet will look for the JSP page you specified to authenticate the user. The JSP page must return an HTML page containing a Form that conforms to a specific naming convention. Similarly, when authentication fails, the servlet will look for a page to display. In the SRDemo application, the same page appears for both cases, though you could have defined different pages.

Example 30-3 shows the conventions of that permit the HTML Form to invoke the authentication servlet. Specifically, the form must specify three pieces of information:

<form action="j_security_check" method="post"> to invoke the security check method j_security_check on the container's login bean.
<input type="text" name="j_username"/> to assign the username value to the container's login bean attribute j_username.
<input type="password" name="j_password"/> to assign the password value to the container's login bean attribute j_password.

Please note that the value of the login bean attributes must be retuned by the HTML Form with the exact names shown. In a JSF JSP page, a JSF form does not guarantee this. Therefore, Oracle recommends that you use a JSP document page in order to use the HTML Form to preserve the login bean attribute names.