Examples: Securing Web Applications

There are several ways in which you can secure web application. These include the following options:

The following examples use annotations, programmatic security, and/or declarative security to demonstrate adding security to existing web applications:

The following examples demonstrates adding basic authentication to an EJB endpoint or enterprise bean:

Example: Using Form-Based Authentication with a JSP page

This example discusses how to use form-based authentication with a basic JSP page. With form-based authentication, you can customize the login screen and error pages that are presented to the web client for authentication of their user name and password. When a user submits their name and password, the server determines if the user name and password are those of an authorized user and, if authorized, sends the requested web resource. If the topic of authentication is new to you, please refer to the section Specifying an Authentication Mechanism.

In general, the following steps are necessary for adding form-based authentication to an unsecured JSP page, such as the one described in Web Modules (page 40). In the example application included with this tutorial, many of these steps have been completed for you and are listed here simply to show what needs to be done should you wish to create a similar application. The completed version of this example application can be found in the directory <INSTALL>/javaeetutorial5/examples/web/hello1_formauth/.

The following steps describe how to set up your system for running the example applications, describe the sample application, and provide the steps for compiling, packaging, deploying, and testing the example application.

  1. If you have not already done so, set up your system so that the ant commands will run properly. To do this, follow the instructions in Building the Examples (page xxxi). This step is necessary to set the properties that are specific to your installation of the Application Server and Java EE 5 Tutorial.
  2. If you have not already done so, add an authorized user to the Application Server. For this example, add users to the file realm of the Application Server and assign the user to the group user. This topic is discussed more in Adding Authorized Roles and Users.
  3. Create a web module as described in Web Modules (page 40). The subsequent steps discuss adding security to this basic application. The resulting application is found in the directory <INSTALL>/javaeetutorial5/examples/web/hello1_formauth/.
  4. Create the login form and login error form pages. Files for the example application can be viewed at <INSTALL>/javaeetutorial5/examples/web/hello1_formauth/web. These pages are discussed in Creating the Login Form and the Error Page.
  5. Create a web.xml deployment descriptor and add the appropriate security elements (the application on which this section is based did not originally require a deployment descriptor.) The deployment descriptor for the example application can be viewed at <INSTALL>/javaeetutorial5/examples/web/WEB-INF/hello1_formauth/. The security elements for the web.xml deployment descriptor are described in Specifying A Security Constraint.
  6. Map the role name defined for this resource (loginUser) to a group of users defined on the Application Server. For more information on how to do this, read Mapping Application Roles to Application Server Groups.
  7. Build, package, deploy, and run the web application by following the steps in Building, Packaging, and Deploying the Form-Based Authentication Example. You will use the ant tool for these tasks.
  8. Test the web client, following the steps in Testing the Form-Based Authentication Web Client.

Creating a Web Client for Form-Based Authentication

The web client in this example is a standard JSP page, and annotations are not used in JSP pages because JSP pages are compiled as they are presented to the browser. Therefore, none of the code that adds form-based authentication to the example is included in the web client. The code for the JSP page used in this example, hello1_formauth/web/index.jsp, is exactly the same as the code used for the unsecured JSP page from the example application at <INSTALL>/javaeetutorial5/examples/web/hello1/web/index.jsp.

The information that adds form-based authentication to this example is specified in the deployment descriptor. This information is discussed in Specifying A Security Constraint.

Creating the Login Form and the Error Page

When using form-based login mechanisms, you must specify a page that contains the form you want to use to obtain the user name and password, as well as which page to display if login authentication fails. This section discusses the login form and the error page used in this example. The section Specifying A Security Constraint shows how you specify these pages in the deployment descriptor.

The login page can be an HTML page, a JSP page, or a servlet, and it must return an HTML page containing a form that conforms to specific naming conventions (see the Java Servlet 2.5 specification for more information on these requirements). To do this, include the elements that accept user name and password information between <form></form> tags in your login page. The content of an HTML page, JSP page, or servlet for a login page should be coded 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>/javaeetutorial5/examples/web/hello1_formauth/web/logon.jsp. An example of the running login form page is shown later in Figure 30-6. Here is the code for this page: 

<html>
<head>
  <title>Login Page</title>
</head>

<h2>Hello, please login:</h2>
<br><br>
<form action="j_security_check" method=post>
  <p><strong>Please Enter Your User Name: </strong>
  <input type="text" name="j_username" size="25">
  <p><p><strong>Please Enter Your Password: </strong>
  <input type="password" size="15" name="j_password">
  <p><p>
  <input type="submit" value="Submit">
  <input type="reset" value="Reset">
</form>
</html>

The login error page is displayed if the user enters a user name and password combination that is not authorized to access the protected URI. For this example, the login error page can be found at <INSTALL>/javaeetutorial5/examples/web/hello1_formauth/web/logonError.jsp. For this example, the login error page explains the reason for receiving the error page and provides a link that will allow the user to try again. Here is the code for this page: 

<html>
<head>
  <title>Login Error</title>
</head>
<body>
  <c:url var="url" value="/index.jsp"/>
  <h2>Invalid user name or password.</h2>

  <p>Please enter a user name or password that is authorized to access this application.  
  For this application, this means a user that has been created in the <code>file</code> realm 
  and has been assigned to the <em>group</em> of <code>user</code>.  Click here to 
  <a href="${url}">Try Again</a></h2>
</body>
</html>

Specifying A Security Constraint

In this example, we are taking a very simple JSP page-based web application and adding form-based security to this application. The JSP page is exactly the same as the JSP page used in the example described in Web Modules (page 40). All security for this example is declared in the deployment descriptor for the application. A security constraint is defined in the deployment descriptor that tells the server to send a login form to collect user data, verify that the user is authorized to access the application, and, if so, display the JSP page to the user.

If this client were a web service endpoint and not a JSP page, we could use annotations to declare security roles and to specify which roles were allowed access to which methods. However, there is no resource injection in JSP pages, so we cannot use annotations and must use the equivalent deployment descriptor elements.

Deployment descriptor elements are described in Declaring Security Requirements in a Deployment Descriptor.

The following sample code shows the deployment descriptor used in this example of form-based login authentication, which can be found in <INSTALL>/javaeetutorial5/examples/web/hello1_formauth/web/WEB-INF/web.xml. 

<!-- FORM-BASED LOGIN AUTHENTICATION EXAMPLE -->
<?xml version="1.0" encoding="UTF-8"?> 
<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="2.5"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
  http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

     <display-name>hello1_formauth</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>

More description of the elements that declare security in a deployment descriptor can be found in Specifying Security Constraints.

Protecting Passwords 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 an unprotected 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.

A <transport-guarantee> element indicates whether or not the protected resources should travel over protected transport. For simplicity, this example does not require protected transport, but in a real world application, you would want to set this value to CONFIDENTIAL to ensure that the username and password are not observed during transmission. When running on protected transport, you can run the application over the secure SSL protocol, https, and specify the secure port where your SSL connector is created (the default for the Application Server is 8181). If you do not specify the HTTPS protocol, the server will automatically redirects the application to the secure port.

Adding Authorized Roles and Users

An application or web server specify which users are authorized to access protected resources in different ways.

When an application is deployed, the application-specific security roles are mapped to security identities in the runtime environment, such as principals (identities assigned to users as a result of authentication) or groups. Based on this mapping, a user who has been assigned a certain security role has associated access rights to a web application deployed onto a server.

As shown in the deployment descriptor for this example application, the security constraint specifies that users assigned to the role of loginUser are authorized to access any of the files in the hello1_formauth application. In this example, when a resource that is constrained by this same security constraint, for example, hello1_formauth/web/index.jsp, is accessed, the Application Server sends the login form, receives the login information, and checks to see if the user is in a group that has been mapped to the role of loginUser. If the user name and password are those of an authorized user, access to the resource is granted to the requester.

To set up users for this example application, follow these steps:

  1. Using the Admin Console, create a user in the file realm of the Application Server and assign that user to the group user. Make sure to note the user name and password that you enter in this step so that you can use it for testing the application later. If you need help with the steps required to accomplish this task, read Managing Users and Groups on the Application Server (page 879) for more information.
  2. Map the application security role of loginUser to the group of user that has been configured on the Application Server. For more information on how to do this mapping, read Mapping Application Roles to Application Server Groups.

Mapping Application Roles to Application Server Groups

Map the role of loginUser defined in the application to the group of user defined on the Application Server by adding a security-role-mapping element to the sun-web.xml runtime deployment descriptor file. To deploy a WAR on the Application Server, the WAR file must contain a runtime deployment descriptor. The runtime deployment descriptor is an XML file that contains information such as the context root of the web application and the mapping of the portable names of an application's resources to the Application Server's resources.

The runtime deployment descriptor for this example, <INSTALL>/javaeetutorial5/examples/web/hello1_formauth/web/WEB-INF/sun-web.xml, looks like this: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 9.0 
Servlet 2.5//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_5-0.dtd">
<sun-web-app>
  <context-root>/hello1_formauth</context-root>
  <security-role-mapping>
    <role-name>loginUser</role-name>
    <group-name>user</group-name>
  </security-role-mapping>
</sun-web-app>

Building, Packaging, and Deploying the Form-Based Authentication Example

To build, package, deploy, and run the web/hello1_formauth example, which uses form-based authentication, follow these steps:

  1. Follow the instructions in Building the Examples (page xxxi) if you have not already done so. This step is necessary to provide the ant targets with the location of your tutorial and Application Server installations.
  2. Add users to the file realm of the Application Server as described in Adding Authorized Roles and Users if you have not already done so.
  3. From a terminal window or command prompt, change to the <INSTALL>/javaeetutorial5/examples/web/hello1_formauth/ directory.
  4. Enter the following command at the terminal window or command prompt:

    5.    ant

    This target will spawn any necessary compilations, copy files to the <INSTALL>/javaeetutorial5/examples/web/hello1_formauth/build/ directory, create the WAR file, and copy it to the <INSTALL>javaeetutorial5/examples/web/hello1_formauth/dist/ directory.

  5. Deploy the WAR named hello1_formauth.war onto the Application Server using ant by entering the following command at the terminal window or command prompt:

    6.   ant deploy

  6. Follow the steps in Testing the Form-Based Authentication Web Client.

Testing the Form-Based Authentication Web Client

To run the web client, follow these steps:

  1. Open a web browser.
  2. Enter the following URL in your web browser:

    3. http://localhost:8080/hello1_formauth

Note: If you set the transport guarantee to CONFIDENTIAL as discussed in Protecting Passwords with SSL, you must load the application in a web browser using https for the protocol, the HTTPS port that you specified during installation for the port (by default this port is 8181), and the context name for the application you wish to run. For the form-based authentication example, you could run the example using the following URL: https://localhost:8181/hello1_formauth

The login form displays in the browser, as shown in Figure 30-6.

Form-based Login Page

Figure 30-6 Form-Based Login Page

  1. Enter a user name and password combination that corresponds to a user that has already been created in the file realm of the Application Server and has been assigned to the group of user, as discussed in Adding Authorized Roles and Users.
  2. Click the Submit button. Form-based authentication is case-sensitive for both the user name and password, so enter the user name and password exactly as defined for the Application Server.

    3. If you entered My_Name as the name and My_Pwd for the password, the server returns the requested resource if all of the following conditions are met:

    • There is a user defined for the Application Server with the user name of My_Name.
    • The user with the user name of My_Name has a password of My_Pwd defined for the Application Server.
    • The user My_Name with the password My_Pwd is assigned to the group of user on the Application Server.
    • The role of loginUser, as defined for the application, is mapped to the group of user, as defined for the Application Server.

      • When these conditions are met, and the server has authenticated the user, the application will display as shown in Figure 30-7.


      Web browser displays the line "Hello, my name is Duke. What's yours?" followed by a text box in which to type your name and a Submit button to submit your name.

Figure 30-7 Running Web Application

  1. Enter your name and click the Submit button. Because you have already been authorized, the name you enter in this step does not have any limitations. You have unlimited access to the application now.

    2. The application responds by saying "Hello" to you, as shown in Figure 30-8.

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

Figure 30-8 The Running Form-Based Authentication Example

Note: For repetitive testing of this example, you may need to close and reopen your browser. You should also run the ant clean and ant undeploy commands to ensure a fresh build.

Example: Basic Authentication with a Servlet

This example discusses how to use basic authentication with a servlet. With basic authentication of a servlet, the web browser presents a standard login dialog that is not customizable. When a user submits their name and password, the server determines if the user name and password are those of an authorized user and sends the requested web resource if the user is authorized to view it. If the topic of authentication is new to you, please refer to the section Specifying an Authentication Mechanism.

In general, the following steps are necessary for adding basic authentication to an unsecured servlet, such as the one described in Web Modules (page 40). In the example application included with this tutorial, many of these steps have been completed for you and are listed here simply to show what needs to be done should you wish to create a similar application. The completed version of this example application can be found in the directory <INSTALL>/javaeetutorial5/examples/web/hello2_basicauth/.

The following steps describe how to set up your system for running the example applications, describe the sample application, and provide the steps for compiling, packaging, deploying, and testing the example application.

  1. If you have not already done so, set up your system so that the ant commands will run properly. To do this, follow the instructions in Building the Examples (page xxxi). This step is necessary to set the properties that are specific to your installation of the Application Server and Java EE 5 Tutorial.
  2. If you have not already done so, add an authorized user to the Application Server. For this example, add users to the file realm of the Application Server and assign the user to the group user. This topic is discussed more in Adding Authorized Roles and Users.
  3. Create a web module as described in Web Modules (page 40) for the servlet example, hello2. The subsequent steps discuss adding security to this basic application. The files for this example application are in <INSTALL>/javaeetutorial5/examples/web/hello2_basicauth/.
  4. Declare the roles that will be used in this application. For this example, this is done by adding the @DeclareRoles annotation to GreetingServlet.java. This code is shown in Declaring Security Roles.
  5. Add the appropriate security elements to the web.xml deployment descriptor using deploytool. The deployment descriptor for the example application can be viewed at <INSTALL>/javaeetutorial5/examples/web/hello2_basicauth/web/WEB-INF/web.xml. The security elements are described in Specifying the Security Constraint.
  6. Map the role name defined for this resource (helloUser) to a group of users defined on the Application Server. For more information on how to do this, read Mapping Application Roles to Application Server Groups.
  7. Build, package, deploy, and run the web application by following the steps in Building, Packaging, Deploying, and Running the Servlet Basic Authentication Example. You will use the ant tool for these tasks.
  8. If you have any problems running this example, refer to the troubleshooting tips in Troubleshooting the Basic Authentication Example.

Declaring Security Roles

There are two annotations that can be used with servlets: @DeclareRoles and @RunAs. In this example, the @DeclareRoles annotation is used to specify which roles are referenced in this example.

The following section of the <INSTALL>/javaeetutorial5/examples/web/hello2_basicauth/src/servlets/GreetingServlet.java file contains the code necessary to declare that the role of helloUser is used in this application: 

package servlets;

import java.io.*;
import java.util.*;
import java.sql.*;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.annotation.security.DeclareRoles;

/**
 * This is a simple example of an HTTP Servlet that can only be accessed
 * by an authenticated user.  It responds to the GET
 * method of the HTTP protocol.
*/

@DeclareRoles("helloUser")
public class GreetingServlet extends HttpServlet {

    public void doGet (HttpServletRequest request,
                       HttpServletResponse response)
                        throws ServletException, IOException

You could also declare security roles using the <security-role-ref> element in the deployment descriptor. If you prefer to declare security roles this way, read Declaring Roles Using Deployment Descriptor Elements.

Specifying the Security Constraint

In this example, we are taking a very simple servlet-based web application and adding basic authentication to this application. The servlet is basically the same as the servlet used in the example described in Web Modules (page 40), with the exception of the annotations added and discussed in Declaring Security Roles.

The security constraint for this example is declared in the application deployment descriptor. The security constraint tells the server or browser to perform the following tasks:

Deployment descriptors elements are described in Declaring Security Requirements in a Deployment Descriptor.

The following sample code shows the security elements for the deployment descriptor used in this example of basic authentication, which can be found in <INSTALL>/javaeetutorial5/examples/web/hello2_basicauth/web/WEB-INF/web.xml. 

  <security-constraint>
    <display-name>SecurityConstraint</display-name>
    <web-resource-collection>
       <web-resource-name>WRCollection</web-resource-name>
      <url-pattern>/greeting</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>helloUser</role-name>
    </auth-constraint>
    <user-data-constraint>
       <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>file</realm-name>
  </login-config>

More description of the elements that declare security in a deployment descriptor can be found in Specifying Security Constraints.

Protecting Passwords 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 an unprotected 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.

A <transport-guarantee> element indicates whether or not the protected resources should travel over protected transport. For simplicity, this example does not require protected transport, but in a real world application, you would want to set this value to CONFIDENTIAL to ensure that the username and password are not observed during transmission. When running on protected transport, you need to using the secure SSL protocol, https, and specify the secure port where your SSL connector is created (the default for the Application Server is 8181).

Adding Authorized Roles and Users

An application and an application or web server specify which users are authorized to access protected resources in different ways.

When an application is deployed, the application-specific security roles are mapped to security identities in the runtime environment, such as principals (identities assigned to users as a result of authentication) or groups. Based on this mapping, a user who has been assigned a certain security role has associated access rights to a web application deployed onto a server.

As shown in the deployment descriptor for this example application, the security constraint specifies that users assigned to the role of helloUser are authorized to access the URL pattern /greeting. In this example, when this resource (because it is constrained by a security constraint) is accessed, the Application Server sends a default login dialog, receives the login information, and checks to see if the user is in a group that has been mapped to the role of helloUser. If the user name and password are those of an authorized user, access to the resource is granted to the requester.

To set up users for this example application, follow these steps:

  1. If you have not already done so, create a user in the file realm of the Application Server and assign that user to the group user. Make sure to note the user name and password that you enter in this step so that you can use it for testing the application later. If you need help with the steps required to accomplish this task, read Managing Users and Groups on the Application Server (page 879) for more information.
  2. Map the application security role of helloUser to the group of user that has been configured on the Application Server. For more information on how to do this mapping, read Mapping Application Roles to Application Server Groups.

Mapping Application Roles to Application Server Groups

Map the role of helloUser defined in the application to the group of user defined on the Application Server by adding a security-role-mapping element to the sun-web.xml runtime deployment descriptor file. The runtime deployment descriptor is an XML file that contains information such as the context root of the web application and the mapping of the portable names of an application's resources to the Application Server's resources.

The runtime deployment descriptor for this example, <INSTALL>/javaeetutorial5/examples/web/hello2_basicauth/web/WEB-INF/sun-web.xml, looks like this: 

<sun-web-app>
  <context-root>/hello2_basicauth</context-root>
  <security-role-mapping>
    <role-name>helloUser</role-name>
    <group-name>user</group-name>
  </security-role-mapping>
</sun-web-app>

Building, Packaging, Deploying, and Running the Servlet Basic Authentication Example

To build, package, deploy, and run the web/hello2_basicauth example, which uses basic authentication, follow these steps:

  1. If you have not already done so, follow the instructions in Building the Examples (page xxxi). This step is necessary to provide the ant targets with the location of your tutorial and Application Server installations.
  2. If you have not already done so, add authorized users to the file realm of the Application Server as described in Adding Authorized Roles and Users.
  3. From a terminal window or command prompt, change to the <INSTALL>/javaeetutorial5/examples/web/hello2_basicauth/ directory.
  4. Build and package the web application by entering the following command at the terminal window or command prompt:

    5.    ant

    This command uses web.xml and sun-web.xml files, located in the <INSTALL>/javaeetutorial5/examples/web/hello2_basicauth/web/WEB-INF/ directory. Deploying the Web Application

  5. To deploy the example using ant, enter the following command at the terminal window or command prompt:

    6.   ant deploy

    The deploy target in this case gives you an incorrect URL to run the application. To run the application, please use the URL shown in Running the Basic Authentication Servlet.

  6. Run the web application as described in Running the Basic Authentication Servlet.
Running the Basic Authentication Servlet

To run the web client, follow these steps:

  1. Open a web browser.
  2. Enter the following URL in your web browser:

    3. http://localhost:8080/hello2_basicauth/greeting

Note: If you set the transport guarantee to CONFIDENTIAL as discussed in Protecting Passwords with SSL, you must load the application in a web browser using https for the protocol, the HTTPS port that you specified during installation for the port (by default this port is 8181), and the context name for the application you wish to run. For the basic authentication example, you could run the example using the following URL: https://localhost:8181/hello2_basicauth/greeting.

  1. A default login form displays. Enter a user name and password combination that corresponds to a user that has already been created in the file realm of the Application Server and has been assigned to the group of user, as discussed in Adding Authorized Roles and Users.

    2. Basic authentication is case-sensitive for both the user name and password, so enter the user name and password exactly as defined for the Application Server.

    If you entered My_Name as the name and My_Pwd for the password, the server returns the requested resource if all of the following conditions are met:

    • There is a user defined for the Application Server with the user name of My_Name.
    • The user with the user name of My_Name has a password of My_Pwd defined for the Application Server.
    • The user My_Name with the password My_Pwd is assigned to the group of user on the Application Server.
    • The role of helloUser, as defined for the application, is mapped to the group of user, as defined for the Application Server.

      • When these conditions are met, and the server has authenticated the user, the application will display as shown in Figure 30-9.


      The running hello2_basicauth application displays in a browser. The screen shows the text "Hello, my name is Duke. What's yours?" Enter text in the box and click Submit.

Figure 30-9 Running Web Application

  1. Enter your name and click the Submit button. Because you have already been authorized, the name you enter in this step does not have any limitations. You have unlimited access to the application now.

    2. The application responds by saying "Hello" to you, as shown in Figure 30-10.

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

Figure 30-10 The Running Basic Authentication Example

Note: For repetitive testing of this example, you may need to close and reopen your browser. You should also run the ant clean and ant undeploy targets to get a fresh start.

Troubleshooting the Basic Authentication Example

When doing iterative development with this web application, follow these steps:

  1. Close your web browser.
  2. Undeploy the web application. To undeploy the application, use the following command in the directory:

    3.   ant undeploy

  3. Clean out files from the previous build, using the following command:

    4.   ant clean

  4. Recompile, repackage, and redeploy the application, using the following commands:

    5.   ant
      ant deploy

  5. Open your web browser and reload the following URL:

    6. http://localhost:8080/hello2_basicauth/greeting

Example: Basic Authentication with JAX-WS

In this section, we discuss how to configure a JAX-WS-based web service for HTTP basic authentication. When a service that is constrained by HTTP basic authenticationis requested, the server requests a user name and password from the client and verifies that the user name and password are valid by comparing them against a database of authorized users.

If the topic of authentication is new to you, please refer to the section titled Specifying an Authentication Mechanism. For an explanation of how basic authentication works, see Figure 30-2.

For this tutorial, we will add the security elements to the JAX-WS service; build, package, and deploy the service; and then build and run the client application.

This example service was developed by starting with an unsecured service, helloservice, which can be found in the directory <INSTALL>/javaeetutorial5/examples/jaxws/helloservice and is discussed in Creating a Simple Web Service and Client with JAX-WS (page 498). We build on this simple application by adding the necessary elements to secure the application using basic authentication. The example client used in this application can be found at <INSTALL>/javaeetutorial5/examples/jaxws/simpleclient-basicauth, which only varies from the original simpleclient application in that it uses the helloservice-basicauth endpoint instead of the helloservice endpoint. The completed version of this example service can be found at <INSTALL>/javaeetutorial5/examples/jaxws/helloservice-basicauth.

In general, the following steps are necessary to add basic authentication to a JAX-WS web service. In the example application included with this tutorial, many of these steps have been completed for you and are listed here to show what needs to be done should you wish to create a similar application.

  1. Create an application like the one in Creating a Simple Web Service and Client with JAX-WS (page 498). The example in this tutorial starts with this example and demonstrates adding basic authentication of the client to this application. The completed version of this application is located in the directory <INSTALL>/javaeetutorial5/examples/jaxws/helloservice-basicauth.
  2. If the default port value was set to a value other than the default (8080), follow the instructions in Setting the Port (page 498) to update the example files to reflect this change.
  3. If you have not already done so, specify properties specific to your installation in the <INSTALL>/javaeetutorial5/examples/bp-project/build.properties file and the <INSTALL>/javaeetutorial5/examples/common/admin-password.txt file. See Building the Examples (page xxxi) for information on which properties need to be set in which files.
  4. If you have not already done so, add a user to the file realm and specify user for the group of this new user. Write down the user name and password so that you can use them for testing this application in a later step. If you have not already completed this step, refer to the section Managing Users and Groups on the Application Server (page 879) for instructions.
  5. Modify the source code for the service, Hello.java, to specify which roles are authorized to access the sayHello (String name) method. This step is discussed in Annotating the Service.
  6. Modify the application deployment descriptor, web.xml, to add security elements that specify that basic authentication is to be performed. For this example, these have been added. This step is discussed in Adding Security Elements to the Deployment Descriptor.
  7. Modify the runtime deployment descriptor, sun-web.xml, to map the role used in this application (basicUser) to a group defined on the Application Server (user). This step is discussed in Linking Roles to Groups.
  8. Build, package, and deploy the web service, then build and run the client application.See Building and Running the HelloService with Basic Authentication.

Annotating the Service

The source code for the original /helloservice application was modified as shown in the following code snippet (modifications in bold). This file can be found in <INSTALL>/javaeetutorial5/examples/jaxws/helloservice-basicauth/src/java/helloservice/basicauth/endpoint/Hello.java. 

package helloservice.basicauth.endpoint;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.annotation.security.RolesAllowed;

@WebService()
public class Hello {
    private String message = new String("Hello, ");

    @WebMethod()
    @RolesAllowed("basicUser")
    public String sayHello(String name) {
     return message + name + ".";

    }
}

The @RolesAllowed annotation specifies that only users in the role of basicUser will be allowed to access the sayHello (String name) method. An @RolesAllowed annotation implicitly declares a role that will be referenced in the application, therefore, no @DeclareRoles annotation is required.

Adding Security Elements to the Deployment Descriptor

To enable basic authentication for the service, add security elements to the application deployment descriptor, web.xml. The security elements that need to be added to the deployment descriptor include the <security-constraint> and <login-config> elements. These security elements are discussed in more detail in Declaring Security Requirements in a Deployment Descriptor and in the Java Servlet Specification. Code in bold is added to the original deployment descriptor to enable HTTP basic authentication. The resulting deployment descriptor is located in <INSTALL>/javaeetutorial5/examples/jaxws/helloservice-basicauth/web/WEB-INF/web.xml. 

<?xml version="1.0" encoding="UTF-8"?>
<web-app 
  xmlns="http://java.sun.com/xml/ns/javaee" version="2.5" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema" 
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
  http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    <display-name>HelloService</display-name>
    <listener>
        <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener
    </listener-class>
    </listener>
    <servlet>
        <display-name>HelloService</display-name>
        <servlet-name>HelloService</servlet-name>
        <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>HelloService</servlet-name>
        <url-pattern>/hello</url-pattern>
    </servlet-mapping>
    <session-config>
        <session-timeout>30</session-timeout>
    </session-config>
    <security-constraint>
    <display-name>SecurityConstraint</display-name>
    <web-resource-collection>
       <web-resource-name>WRCollection</web-resource-name>
      <url-pattern>/hello</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>basicUser</role-name>
    </auth-constraint>
    <user-data-constraint>
      <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
  <login-config>
    <auth-constraint>BASIC</auth-constraint>
    <realm-name>file</realm-name>
  </login-config>
</web-app>

Linking Roles to Groups

The role of basicUser has been defined for this application, but there is no group of basicUser defined for the Application Server. To map the role that is defined for the application (basicUser) to a group that is defined on the Application Server (user), add a <security-role-mapping> element to the runtime deployment descriptor, sun-web.xml, as shown below (modifications from the original file are in bold). The resulting runtime deployment descriptor is located in <INSTALL>/javaeetutorial5/examples/jaxws/helloservice-basicauth/web/WEB-INF/sun-web.xml. 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 9.0 
Servlet 2.5//EN" "http://www.sun.com/software/appserver/dtds/sun-web-app_2_5-0.dtd">
<sun-web-app error-url="">
  <context-root>/helloservice</context-root>
  <class-loader delegate="true"/>
  <security-role-mapping>
        <role-name>basicUser</role-name>
        <group-name>user</group-name>
  </security-role-mapping>
</sun-web-app>

Building and Running the HelloService with Basic Authentication

To build, package, and deploy the jaxws/helloservice-basicauth example, follow these steps, or the steps described in Building and Packaging the Service (page 501).

  1. If you have not already done so, set up your system for running the tutorial examples by following the instructions in Building the Examples (page xxxi).
  2. If you haven't already done so, set up an authorized user on the Application Server, assigned to the group user, as described in Managing Users and Groups on the Application Server (page 879).
  3. From a terminal window or command prompt, go to the <INSTALL>/javaeetutorial5/examples/jaxws/helloservice-basicauth/ directory.
  4. Build, package, and deploy the JAX-WS service by entering the following at the terminal window or command prompt in the helloservice-basicauth/ directory:

    5. ant all

    You can test the service by selecting it in the Admin Console and choosing Test. For more information on how to do this, read Testing the Service Without a Client (page 502).

  5. Build the client by changing to the directory <INSTALL>/examples/jaxws/simpleclient-basicauth/ and entering the following at the terminal window or command prompt:

    6.   ant

    This command calls the default target, which builds and packages the application into a JAR file, simpleclient-basicauth.jar, located in the /dist directory.

  6. Run the client by entering the following at the terminal window or command prompt:

    7.   ant run

    A Login for User dialog displays.

  7. Enter a user name and password that correspond to a user set up on the Application Server with a group of user. Click OK.

The client displays the following output: 

[echo] running application client container.
[exec] Retrieving the port from the following service: helloservice.endpoint.HelloSer 
vice@c8769b
[exec] Invoking the sayHello operation on the port.
[exec] Hello, No Name.