Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
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 thanNONE
, 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:The following choices are valid options for the authentication methods for a Web resource.
None
If you do not specify one of the following methods, the user will not be authenticated.
- HTTP
Basic
authenticationIf you specify HTTP basic authentication, (
<auth-method>BASIC</auth-method>
), the Web server will authenticate a user by using the user name and password obtained from the Web client. HTTP basic authentication is not particularly secure. Basic authentication sends user names and passwords over the Internet as text that is uu-encoded, but not encrypted. This form of authentication, which uses Base64 encoding, can expose your user names and passwords unless all connections are over SSL. If someone can intercept the transmission, the user name and password information can easily be decoded. An example application that uses HTTP Basic Authentication in a JAX-RPC service is described in Example: Basic Authentication with JAX-RPC.Form-based
authenticationIf you specify form-based authentication (
<auth-method>FORM</auth-method>
), you can customize the login screen and error pages that are presented to the end user by an HTTP browser.Form-based authentication is not particularly secure. In form-based authentication, the content of the user dialog is sent as plain text, and the target server is not authenticated. This form of authentication can expose your user names and passwords unless all connections are over SSL. If someone can intercept the transmission, the user name and password information can easily be decoded. An example application using form-based authentication is included in the tutorial and is discussed in Example: Using Form-Based Authentication.
Client-Certificate
authenticationClient-certificate authentication (
<auth-method>CLIENT-CERT</auth-method>
) is a more secure method of authentication than either basic or form-based authentication. It uses HTTP over SSL, in which the server and, optionally, the client authenticate one another with Public Key Certificates. Secure Sockets Layer (SSL) provides data encryption, server authentication, message integrity, and optional client authentication for a TCP/IP connection. You can think of a public key certificate as the digital equivalent of a passport. It is issued by a trusted organization, which is called a certificate authority (CA), and provides identification for the bearer. If you specify client-certificate authentication, the Web server will authenticate the client using the client's X.509 certificate, a public key certificate that conforms to a standard that is defined by X.509 Public Key Infrastructure (PKI). Prior to running an application that uses SSL, you must configure SSL support on the server (see Installing and Configuring SSL Support) and set up the public key certificate (see Setting Up Digital Certificates). An example application that usesCLIENT-CERT
authentication is discussed in Example: Client-Certificate Authentication over HTTP/SSL with JAX-RPC.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.
- Add the role name to the
tomcat-users.xml
file and authorize one of the users to assume this role. This example uses the previously unspecified role ofloginUser
, so you must add this role prior to starting Tomcat. See Adding Authorized Roles and Users for more information on needed modifications.- Edit the
build.properties
files. Thebuild.properties
file needs to be modified because the properties in this file are specific to your installation of the Java WSDP and Java WSDP Tutorial. See Editing the Build Properties for information on which properties need to be set.- Create the Web client. For this example, the Web client, a very simple JSP page, is already created. The client is discussed in Creating a Web Client for Form-Based Authentication.
- Create the login form and login error form pages. For this example, these files are already created. These pages are discussed in Creating the Login Form and Error Page.
- Add the appropriate security elements to the
web.xml
deployment descriptor. For this example, these have been added. Refer to Specifying Security Elements for Form-Based Authentication for further description of these elements.- Build, install, and run the Web application (see Building, Installing, and Running the Form-Based Authentication Example). You will use the
Ant
tool to compile and install the example application.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 usingadmintool
. Information on adding users and roles usingadmintool
is discussed in Administering Roles, Groups, and Users. This section describes adding the information directly into thetomcat-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.
- 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 Start
Programs
Java Web Services Developer Pack
Stop Tomcat.
Documentation for Tomcat can be found at
http://jakarta.apache.org/tomcat/tomcat-5.0-doc/index.html
.- 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 ofadmin
andmanager
. Add the new role ofloginUser
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:
<?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. Theusername
andpassword
properties must correspond to a user assigned theloginUser
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. Ifusername
andpassword
variables already exist in the file, change them to the correct values, otherwise, add them.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
<web-resource-collection>
element is used to identify a subset of the resources within a Web application to which a security constraint applies. In this example, by specifying<url-pattern>/</url-pattern>
, we are specifying that all resources in this application are protected.- The
<auth-constraint>
element indicates the user roles that should be permitted access to this resource collection. In this example, it is users assigned the role ofloginUser
. If no role name is provided, no user is allowed to access the portion of the Web application described by the security constraint.- The
<login-config>
element is used to configure the authentication method that should be used and the attributes needed by the form login mechanism. The<form-login-page>
element provides the URI of a Web resource relative to the document root that will be used to authenticate the user. The<form-error-page>
element requires a URI of a Web resource relative to the document root that send a response when authentication has failed.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:
- Follow the instructions in Editing the Build Properties.
- Follow the instructions in Adding Authorized Roles and Users.
- Go to the
<
INSTALL
>/jwstutorial13/examples/security/login/
directory.- 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 useAnt
assume that you have the executable forAnt
in your path: if not, you will need to provide the fully-qualified path to theAnt
executable). This command runs theAnt
target namedbuild
in thebuild.xml
file. The build target compiles any Java files in the application and copies Web components to the appropriate directories for deployment.
ant
build
- 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 Start
Programs
Java Web Services Developer Pack
Start 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.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.
![]()
Figure 24-1 Form-Based Login Page
If you entered
Debbie
as the name, and there is an entry intomcat-users.xml
with the user name ofDebbie
that also matches the password you entered and which is assigned the role ofloginUser
, the display will appear as in Figure 24-2 after you click the Submit button.
![]()
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
orINTEGRAL
within the<transport-guarantee>
elements. Read the section Specifying a Secure Connection for more information.
Download
FAQ History |
![]() ![]() ![]() |
API
Search Feedback |
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.