Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

Using Login Authentication

The <login-config> element in the application deployment descriptor specifies how the user is prompted to login in. If this element is present and contains a value other than NONE, the user must be authenticated before it can access any resource that is constrained by a <security-constraint>.

When you try to access a protected Web resource, the Web container activates the authentication mechanism that has been configured for that resource in the deployment descriptor (web.xml) between <login-config> elements within <auth-method> tags, like this:

<login-config>
  <auth-method>BASIC</auth-method>
</login-config> 

The following choices are valid options for the authentication methods for a Web resource.

When you configure the authentication mechanism that the Web resources in a WAR will use, you have the following options:

Example: Using Form-Based Authentication

In this section, we discuss how to add form-based authentication to a basic JSP page. With form-based authentication (<auth-method>FORM</auth-method>), you can customize the login screen and error pages that are presented to the Web client for authentication of their user name and password. If the topic of authentication is new to you, please refer to the section titled Using Login Authentication.

The example application discussed in this tutorial can be found in <INSTALL>/jwstutorial13/examples/security/login. In general, the following steps are necessary to add form-based authentication to a Web client. In the example application included with this tutorial, most of these steps have been completed for you and are listed here expressly for the purpose of listing what needs to be done should you wish to create a similar application outside of this tutorial.

Adding Authorized Roles and Users

This example application uses a role that is not already authorized for Tomcat. To add this role so that it is recognized by Tomcat, you add the information to the tomcat-users.xml file either by hand or using admintool. Information on adding users and roles using admintool is discussed in Administering Roles, Groups, and Users. This section describes adding the information directly into the tomcat-users.xml file.

When Tomcat is started, it reads the settings in the tomcat-users.xml file. When a constrained resource is accessed, Tomcat verifies that the user name and password are authorized to access that resource before granting access to the requestor. The roles that are authorized to access a resource are specified in the security constraint in the deployment descriptor for this application. Because these values are read when Tomcat is started, you must stop Tomcat, make the changes, then restart Tomcat for it to recognize the new information.

  1. Stop Tomcat. To do this,
    • On Unix, type the following command in a terminal window.
    • <JWSDP_HOME>/bin/shutdown.sh

      The startup script starts the task in the background and then returns the user to the command line prompt immediately. The startup script does not completely start Tomcat for several minutes.

    • On Microsoft Windows, select StartRight ArrowProgramsRight ArrowJava Web Services Developer PackRight ArrowStop Tomcat.
    • Documentation for Tomcat can be found at http://jakarta.apache.org/tomcat/tomcat-5.0-doc/index.html.

  2. Open the file <JWSDP_HOME>/conf/tomcat-users.xml in a text editor. The file should contain at the very least the user name for the installer of the Java WSDP, the password specified by that user during installation, and the roles of admin and manager. Add the new role of loginUser to this file, and authorize at least one of the users to assume this role. The completed file should look like this, with the information that needs to be added highlighted in bold type:
  3. <?xml version='1.0'?>
    <tomcat-users>
      <role rolename="manager"/>
      <role rolename="admin"/>
      <role rolename="loginUser"/>
      <user username="your_name" password="your_password"
        roles="admin,manager,loginUser"/>
    </tomcat-users>

Editing the Build Properties

Most of the example applications have been set up so that some properties are passed to the application from a build.properties file, which is located in the <INSTALL>/jwstutorial13/examples/common directory. The following example assumes you are running on Tomcat. In order to perform form-based authentication, the application will request your user name and password, and then verify that user name is assigned a role that is authorized access in the deployment descriptor. The following items need to be set to the real values for your user name, password, and installation. The username and password properties must correspond to a user assigned the loginUser role, which is the role that was added in the previous section, because that is the role to which we gave access in the deployment descriptor. If username and password variables already exist in the file, change them to the correct values, otherwise, add them.

tutorial.home=<abs_path_from_which_tutorial_was_installed>
username=<your_name>
password=<your_pwd> 

Creating a Web Client for Form-Based Authentication

The Web client is a standard JSP page. None of the code that adds form-based authentication to the example is included in the Web client. The information that adds the form-based authentication to this example is specified in the deployment descriptor. The code for the JSP page used in this example, web/index.jsp, is listed below. The running application is shown in Figure 24-2.

<html>
<head><title>Hello</title></head>
<body bgcolor="white">

<img src="duke.waving.gif">
<h2>My name is Duke.</h2>
<h2><font color="black">Hello,
   ${pageContext.request.userPrincipal.name}!</font></h2>
</body>
</html> 

Creating the Login Form and Error Page

The deployment descriptor specifies the JSP page that contains the form to be used to obtain the user name and password in order to verify that access to the client is authorized to that user. If login authentication fails, the error page is displayed in place of the requested page.

The login page can be an HTML page, a JSP page, or a servlet, and must return an HTML page containing a form that conforms to specific naming conventions (see the Servlet 2.4 specification for more information on these requirements). The content of the login form in an HTML page, JSP page, or servlet for a login page should be as follows:

<form method=post action="j_security_check" >
 <input type="text"  name= "j_username" >
 <input type="password"  name= "j_password" >
</form> 

The full code for the login page used in this example can be found at <INSTALL>/jwstutorial13/examples/security/login/web/logon.jsp. An example of the running login form page is shown in Figure 24-1.

The login error page is displayed if a user name and password combination that is not authorized to access the protected URI is entered on the login page. For this example, the login error page can be found at <INSTALL>/jwstutorial13/examples/security/login/web/logonError.jsp. The code for this page is displayed below:

<html>
<head>
<title>
 Login Error
</title>
</head>
<c:url var="url" value="/logon.jsp"/>
<p><a href="${url}">Try again.</a></p>
</html> 

Specifying Security Elements for Form-Based Authentication

The following sample code shows the deployment descriptor used in this example of form-based login authentication. For this example application, the deployment descriptor can be found in <INSTALL>/jwstutorial13/examples/security/login/web/WEB-INF/web.xml. This example contains the following elements that are necessary for this application to run properly.

The following code is the deployment descriptor for the form-based authentication example:

<!-- FORM-BASED LOGIN AUTHENTICATION EXAMPLE -->
<?xml version="1.0" encoding="UTF-8"?> 
<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://
java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">  
  <display-name>hello</display-name>   
  <servlet>     
    <display-name>index</display-name>    
    <servlet-name>index</servlet-name>    
    <jsp-file>/index.jsp</jsp-file>  
  </servlet>   
  <security-constraint>     
    <display-name>SecurityConstraint</display-name>    
    <web-resource-collection>      
      <web-resource-name>WRCollection</web-resource-name>     
      <url-pattern>/</url-pattern> 
    </web-resource-collection>    
    <auth-constraint>      
      <role-name>loginUser</role-name>    
    </auth-constraint>    
    <user-data-constraint>    
      <transport-guarantee>NONE</transport-guarantee>    
    </user-data-constraint>   
  </security-constraint>  
  <login-config>    
    <auth-method>FORM</auth-method> 
    <form-login-config>      
      <form-login-page>/logon.jsp</form-login-page>     
      <form-error-page>/logonError.jsp</form-error-page>  
    </form-login-config> 
  </login-config>  
  <security-role>    
    <role-name>loginUser</role-name> 
  </security-role> 
</web-app> 

Building, Installing, and Running the Form-Based Authentication Example

To build, install, and run the security/login example using form-based authentication, follow these steps:

  1. Follow the instructions in Editing the Build Properties.
  2. Follow the instructions in Adding Authorized Roles and Users.
  3. Go to the <INSTALL>/jwstutorial13/examples/security/login/ directory.
  4. Build the Web application by entering the following at the terminal window or command prompt in the /login directory (this and the following steps that use Ant assume that you have the executable for Ant in your path: if not, you will need to provide the fully-qualified path to the Ant executable). This command runs the Ant target named build in the build.xml file. The build target compiles any Java files in the application and copies Web components to the appropriate directories for deployment.
  5.    ant build

  6. Start Tomcat. To do this,
    • On Unix, type the following command in a terminal window.
    •   <JWSDP_HOME>/bin/startup.sh

      The startup script starts the task in the background and then returns the user to the command line prompt immediately. The startup script does not completely start Tomcat for several minutes.

    • On Microsoft Windows, select StartRight ArrowProgramsRight ArrowJava Web Services Developer PackRight ArrowStart Tomcat.

Note: The startup script for Tomcat can take several minutes to complete. To verify that Tomcat is running, point your browser to http://localhost:8080. When the Java WSDP index page displays, you may continue. If the index page does not load immediately, wait up to several minutes and then retry. If, after several minutes, the index page does not display, refer to the troubleshooting tips in "Unable to Locate the Server localhost:8080" Error.

Documentation for Tomcat can be found at http://jakarta.apache.org/tomcat/tomcat-5.0-doc/index.html. Errors commonly encountered when starting Tomcat are discussed in Errors Starting Tomcat.


  1. Install the Web application by entering the following at the terminal window or command prompt in the /login directory:
  2.   ant install

  3. Run the Web client by entering the following URL in your Web browser:
  4.    http://localhost:8080/login

The login form displays in the browser, as shown in Figure 24-1. Enter a user name and password combination that corresponds to the role of loginUser, then click the Submit button.

Form-based Login Page

Figure 24-1 Form-Based Login Page

If you entered Debbie as the name, and there is an entry in tomcat-users.xml with the user name of Debbie that also matches the password you entered and which is assigned the role of loginUser, the display will appear as in Figure 24-2 after you click the Submit button.

Image of running form-based login authentication example, shows Duke waving, and the text "My name is Duke, Hello your name!"

Figure 24-2 The Running Form-Based Authentication Example

Using Authentication with SSL

Passwords are not protected for confidentiality with HTTP basic or form-based authentication, meaning that passwords sent between a client and a server on a non-protected session can be viewed and intercepted by third parties. To overcome this limitation, you can run these authentication protocols over an SSL-protected session and ensure that all message content is protected for confidentiality. To configure HTTP basic or form-based authentication over SSL, specify CONFIDENTIAL or INTEGRAL within the <transport-guarantee> elements. Read the section Specifying a Secure Connection for more information.

Divider
Download
FAQ
History
PrevHomeNext API
Search
Feedback
Divider

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.