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: 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 authentication is 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 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 the 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 496). 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. 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 496). 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 496) 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. While you are looking at these files, note the value entered for admin.user and check the file admin-password.txt for the value of the admin password.
  4. 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.
  5. 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.
  6. 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.
  7. 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. Refer to the section Managing Users and Groups on the Application Server (page 875) for instructions on completing this step.
  8. Build, package, and deploy the web service, then build and run the client application.See Building and Running the Example for Basic Authentication.
  9. If you have errors when running this example, refer to the steps in .

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 Example for Basic Authentication

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

  1. Set up your system for running the tutorial examples if you haven't done so already by following the instructions in Building the Examples (page xxxi).
  2. From a terminal window or command prompt, go to the <INSTALL>/javaeetutorial5/examples/jaxws/helloservice-basicauth/ directory.
  3. Build, package, and deploy the JAX-WS service by entering the following at the terminal window or command prompt in the helloservice-basicauth/ directory:

    4. 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 Chapter 15.

  1. To build and run the client application, change to the directory <JAVA_EE_HOME>/examples/jaxws/simpleclient/ and do the following:

    2. ant run

A Login for User dialog displays. 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: 

run:
     [echo] To set the name, modify the client.arg property
     [echo] in build.properties. If client.arg is unset,
     [echo] the default name sent to the service is No Name.

appclient-command-common:
     [exec] Retrieving the port from the following service: 
helloservice.endpoint.HelloService@8a2006
     [exec] Invoking the sayHello operation on the port.
     [exec] Hello, No Name.