test

The Java EE 5 Tutorial

Example: Basic Authentication with JAX-WS

This section discusses 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, refer to the section titled Specifying an Authentication Mechanism. For an explanation of how basic authentication works, see Figure 30–2.

For this tutorial, you will add the security elements to the JAX-WS service and client; 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 tut-install/javaeetutorial5/examples/jaxws/helloservice and is discussed in Creating a Simple Web Service and Client with JAX-WS. You 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 tut-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 the secured service can be found at tut-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 simply 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. The example in this tutorial starts with that example and demonstrates adding basic authentication of the client to this application. The completed version of this application is located in the directories tut-install/javaeetutorial5/examples/jaxws/helloservice-basicauth and tut-install/javaeetutorial5/examples/jaxws/simpleclient-basicauth.

  2. If the port value was set to a value other than the default (8080), follow the instructions in Setting the Port to update the example files to reflect this change.

  3. If you have not already done so, follow the steps in Building the Examples for information on setting up your system to run the example.

  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 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. Add security elements that specify that basic authentication is to be performed to the application deployment descriptor, web.xml. 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. See Building and Deploying helloservice with Basic Authentication Using NetBeans IDE or Building and Deploying helloservice with Basic Authentication Using Ant for the steps to accomplish this.

  9. Build and run the client application. See Building and Running the helloservice Client Application with Basic Authentication Using NetBeans IDE or Building and Running the helloservice Client Application with Basic Authentication Using Ant for the steps to accomplish this.

Annotating the Service

In this example, annotations are used to specify which users are authorized to access which methods of this service. In this simple example, the @RolesAllowed annotation is used to specify that users in the application role of basicUser are authorized access to the sayHello(String name) method. This application role must be linked to a group of users on the Application Server. Linking the roles to groups is discussed in Linking Roles to Groups.

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 the following location:


tut-install/javaeetutorial5/examples/jaxws/helloservice-basicauth/src/java/helloservice/
basicauth/endpoint/Hello.java

The code snippet is as follows:

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 tut-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 tut-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 Deploying helloservice with Basic Authentication Using NetBeans IDE

    To build, package, and deploy the jaxws/helloservice-basicauth example using NetBeans IDE, follow these steps, or the steps described in Building, Packaging, and Deploying the Service.

  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.

  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.

  3. In NetBeans IDE, select File->Open Project.

  4. In the Open Project dialog, navigate to tut-install/javaeetutorial5/examples/jaxws/.

  5. Select the helloservice-basicauth folder.

  6. Check the Open as Main Project and Open Required Projects check boxes.

  7. Click Open Project.

  8. In the Projects tab, right-click the helloservice-basicauth project and select Clean and Build.

  9. In the Projects tab, right-click the helloservice-basicauth project and select Undeploy and Deploy.

    This step builds and packages the application into helloservice-basicauth.war, located in tut-install/javaeetutorial5/examples/jaxws/helloservice-basicauth/dist, and deploys this war file to your Application Server instance.

Building and Deploying helloservice with Basic Authentication Using Ant

    To build, package, and deploy the jaxws/helloservice-basicauth example using the Ant tool, follow these steps, or the steps described in Building, Packaging, and Deploying the Service.

  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.

  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.

  3. From a terminal window or command prompt, go to the tut-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:


    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.

Building and Running the helloservice Client Application with Basic Authentication Using NetBeans IDE

    To build and run the client application, simpleclient-basicauth, using NetBeans IDE, follow these steps. The helloservice-basicauth service must be deployed onto the Application Server before compiling the client files. For information on deploying the service, read Building and Deploying helloservice with Basic Authentication Using NetBeans IDE.

  1. In NetBeans IDE, select File->Open Project.

  2. In the Open Project dialog, navigate to tut-install/javaeetutorial5/examples/jaxws/.

  3. Select the simpleclient-basicauth folder.

  4. Check the Open as Main Project and Open Required Projects check boxes.

  5. Click Open Project.

  6. In the Projects tab, right-click the simpleclient-basicauth project and select Clean and Build.

  7. In the Projects tab, right-click the simpleclient-basicauth project and select Run.

    You will be prompted for your user name and password.

  8. Enter the user name and password of a user that has been entered into the database of users for the file realm and has been assigned to the group of user.

    If the username and password you enter are authorized, you will see the output of the application client in the Output pane.

The client displays the following output:


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

Building and Running the helloservice Client Application with Basic Authentication Using Ant

    To build and run the client application, simpleclient-basicauth, using the Ant tool, follow these steps. The secured service must be deployed onto the Application Server before you can successfully compile the client application. For more information on deploying the service, read Building and Deploying helloservice with Basic Authentication Using Ant.

  1. Build the client by changing to the directory tut-install/examples/jaxws/simpleclient-basicauth/ and entering the following at the terminal window or command prompt:


    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.

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


    ant run

    A Login for User dialog displays.

  3. 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.basicauth.endpoint.HelloService@c8769b
[exec] Invoking the sayHello operation on the port.
[exec] Hello, No Name.