A Tutorial on Applying Web-Service Security to EJB Applications, Part 2 of 3: Exercises 1-3

Print-friendly Version

[Part 1] [Part 2] [Part 3]

Part 1 of this tutorial describes the concepts of applying Web-service security to EJB applications and the security profiles supported by Access Manager. Part 2 describes the process flow and the procedure for setting up the environment and explains the steps in Exercises 1 through 3.

This tutorial demonstrates how to secure communications between the client and server of a sample stock-quote service with Access Manager (open-sourced as OpenSSO) and the Java EE 5 SDK.

In the tutorial, in response to a user request that specifies a stock symbol, a Web-service client (WSC) requests a quote from a Web-service provider (WSP). The WSP then returns one of the following:

• A delayed quote that is 20 minutes old if the request is not authenticated, that is, if it's an anonymous request. The stock's market cap, the day's trade volume, and the stock's 52-week price range are not displayed.
  
  
• A delayed stock quote that is 10 minutes old if the WSC request is authenticated and the authenticated identity is that of a Guest Member. The stock's 52-week price range is displayed, but not the day's trade volume and the market cap.
  
  
• A delayed stock quote that is 5 minutes old if the WSC request is authenticated and the authenticated identity is that of a Silver Member. The stock's 52-week price range and the day's trade volume are displayed, but not the market cap.
  
  
• A real-time quote if the WSC request is authenticated and the authenticated identity is that of a Gold Member. Additionally, the stock's 52-week price range, the day's trade volume, and the market cap are all displayed.

A project is a group of Java source files along with associated information that includes the classpath components and the procedure for building the source. The tutorial download contains two projects:

• StockQuoteService — This is an enterprise application that serves as the WSP and that contains two components:
  
  
  • StockQuoteService-ejb, which represents the EJB module.
    
    
  • StockQuoteService-war, which represents the Web module. When it receives a request from the WSC, it calls the EJB project (StockQuoteService-ejb).
  
  The following files define the various aspects of the WSP:
  
  
  • LAB_ROOT/samples/wsdl/stock.xsd — A description of the parameters that must be passed to the WSP and included in the responses that are returned to the WSC. This file defines the QuoteRequest and QuoteReponse elements in the SOAP body of the request and response, respectively.
    
    
  • LAB_ROOT/samples/wsdl/StockService.wsdl — The Web Services Description Language (WSDL) file that describes the WSP.
    
    
  • LAB_ROOT/samples/StockQuoteService/StockQuoteService-war/src/java/
com/samples/StockService.java — The implementation of the stock-quote service provider. The main method that implements the capability is getStockQuote(...), which parses the stock symbol from the WSC request, calls the EJB component for the stock quote, and returns the result.
    
    
  • LAB_ROOT/samples/StockQuoteService/StockQuoteService-ejb/src/java/
com/samples/StockQuoteSessionBean.java — The implementation of the business logic to obtain the stock quote. The main method that implements the capability is getQuote(...), which obtains the stock quote from either Yahoo! Financial Service or from a statically created local cache. In addition, the main security function executed by the EJB component determines the role of the caller and sets the appropriate delay for the stock quote and the fields that are not displayed.
    
    Following is the business logic code that sets the delay and marks the fields in StockService.java that are not displayed:
    
    

    // Check user's privilege // i.e., roles and set the delay for stock quote accordingly if (ctx.isCallerInRole("Gold")) { data.put("delay", "0"); } else if (ctx.isCallerInRole("Silver")) { data.put("delay", "5"); data.put("marketCap", "N/A"); } else if (ctx.isCallerInRole("Guest")) { data.put("delay", "10"); data.put("marketCap", "N/A"); data.put("volume", "N/A"); } else { data.put("delay", "20"); data.put("marketCap", "N/A"); data.put("volume", "N/A"); data.put("yearRange", "N/A"); }

     
    
  • sun-application.xml — The definitions of the J2EE declarative security role mappings for Guest, Silver, and Gold memberships, as follows:
    
    

    <security-role-mapping> <role-name>Gold</role-name> <principal-name class-name="com.sun.identity.wss.security.SecurityPrincipal"> id=Gold,ou=group,dc=sun,dc=com </principal-name> </security-role-mapping> <security-role-mapping> <role-name>Silver</role-name> <principal-name class-name="com.sun.identity.wss.security.SecurityPrincipal"> id=Silver,ou=group,dc=sun,dc=com </principal-name> </security-role-mapping> <security-role-mapping> <role-name>Guest</role-name> <principal-name class-name="com.sun.identity.wss.security.SecurityPrincipal"> StockService </principal-name> <principal-name class-name="com.sun.identity.wss.security.SecurityPrincipal"> wsc </principal-name> <principal-name class-name="com.sun.identity.wss.security.SecurityPrincipal"> CN=SJSAMClient, OU=Access Manager, O=Sun, L=Santa Clara, ST=California, C=US </principal-name> </security-role-mapping>

     
    In this code fragment, the J2EE role Gold is mapped to the physical group defined in Access Manager, identified by id=Gold,ou=group,dc=sun,dc=com. Similarly, the other J2EE roles are mapped to the other physical groups or identities defined in Access Manager.
  
  
• EJB Project — This project contains the business logic that generates the appropriate response and routes it back to the WSC through the Web module.

Exercise 1, which takes approximately 15 minutes to complete, shows you how to configure the environment and how to compile and deploy the StockQuoteService and StockQuoteClient projects.

Setting Up the Environment
In this tutorial, you compile, build, and deploy the projects with Apache Ant, a Java technology-based build tool. Ant is part of Application Server and resides, by default, in the SDK_BUNDLE_HOME/lib/ant/bin directory. You can also download Ant separately.

For the projects to be compiled and deployed, the Ant build scripts must know Application Server's installation directory, in which the Java archive (JAR) files reside. Also, you execute in that directory the asadmin commands to deploy and undeploy applications.

To set up the environment:

1. Add the directory that contains Ant to the PATH environment variable.
   
   
2. Update the LAB_ROOT/samples/javaee.properties file and point the javaee.home variable to Application Server's installation directory.
   
   Figure 1 shows the content of the file. Here, javaee.home points to c:\Sun\SDK, the default installation location for Application Server on Windows.
   
   

   Figure 1: Content of the javaee.properties File

    
   

Compiling and Deploying the WSP
Next, deploy the WSP, StockQuoteService:

1. Go to the directory LAB_ROOT/samples/StockQuoteService.
   
   
2. Type ant to compile the WSDL file with wsimport, generate the stubs, and build the EJB JAR and Web application enterprise archive (EAR) files.
   
   The EAR file, StockQuoteService.ear, is placed in the dist directory.
   
   
3. Type ant deploy to deploy the Web application EAR file to Application Server.

Figure 2 shows the commands and output on Windows.

Figure 2: Commands and Output for Compiling and Deploying the WSP

Compiling and Deploying the WSC
The StockQuoteClient project serves as a WSC—a GUI within a browser that configures user requests and sends them to the WSP. StockQuoteClient contains two files:

• LAB_ROOT/samples/StockQuoteClient/web/index.jsp, the initial page that accepts stock quote requests.
  
  
• LAB_ROOT/StockQuoteClient/src/java/com/samples/GetQuote.java, which implements the WSC through the following two methods:
  
  
  • getStockQuote(...), which makes the Web-service call to the WSP for the stock symbol.
    
    
  • processRequest(...), which obtains the stock symbol, calls getStockQuote(...), processes the response from the WSP, and displays the stock quote on the browser.

To deploy the WSC, StockQuoteClient:

1. Go to the directory LAB_ROOT/samples/StockQuoteClient.
   
   
2. Type ant to compile the WSDL file with wsimport, generate the stubs, and build the Web archive (WAR) file.
   
   The WAR file, StockQuoteClient.war, is placed in the dist directory.
   
   
3. Type ant deploy to deploy the WAR file to Application Server.

Figure 3 shows the commands and output on Windows.

Figure 3: Commands and Output for Compiling and Deploying the WSC

You can now view the StockQuoteService and StockQuoteClient under Enterprise Applications and Web Applications, respectively, in the Application Server Administration Console.

Exercise 2, which takes approximately 15 minutes to complete, shows you how to test unauthenticated communications between StockQuoteClient (the WSC) and StockQuoteService (the WSP). Recall that if the request is not authenticated, the WSP returns a stock quote that's 20 minutes old, but does not return its price range for the year, the trade volume, or the market cap.

To test the WSC with an unauthenticated request:

1. Go to http://localhost:8080/StockQuoteClient.
   
   
2. Type SUNW in the Stock Symbol text field and click GetQuote. See Figure 4.
   
   

   Figure 4: Stock Quote Request

    
   The WSP returns a quote that's 20 minutes old. See Figure 5.
   
   

   Figure 5: Return of Stock Quote From an Unauthenticated Request

    
   
3. Under View SOAP Messages, click the Request and Response links to view the SOAP messages exchanged between the WSC and the WSP, respectively.
   
   Figure 6 shows the SOAP request. Figure 7 shows the SOAP response.
   
   

   Figure 6: SOAP Request (Unauthenticated)

    
    
   

   Figure 7: SOAP Response for an Unauthenticated Request

    
   

Exercise 3, which takes approximately, 20 minutes to complete, shows you how to configure the WSC and the WSP for message-level security, whereby the WSP authenticates only the WSC—but not the end-user—through an X509 Token profile. If authentication is successful, the WSP returns a stock quote that's 10 minutes old. This tutorial treats this scenario as a request from a Guest Member.

To configure the WSC for message-level security:

1. Go back to the stock-quote request page at http://localhost:8080/StockQuoteClient.
   
   
2. Click AMConsole.
   
   The Access Manager login page is displayed.
   
   
3. Log in with the user name amadmin and the password adminadmin.
   
   The Access Manager Administration Console is displayed.
   
   
4. Click the Subjects tab, the Agents tab, and then the agent wscWSC.
   
   The Edit Agent page for wscWSC is displayed.
   
   
5. Select X509Token for Security Mechanism. Select Yes for Is Response Signed to ensure that the response from the WSP is signed. Click Save. See Figure 8.
   
   

   Figure 8: Configurations for wscWSC

    
   

Now configure the WSP for message-level security:

1. Click Back to Subject and then click wspWSP for its Edit Agent page.
   
   
2. Select X509Token for Security Mechanism. Select Yes for Is Response Signed to ensure that the response from the WSP is signed. Click Save. See Figure 9.
   
   

   Figure 9: Configurations for wspWSP

    
   
3. Log out of the Access Manager Administration Console.

Finally, test the WSC:

1. Go to http://localhost:8080/StockQuoteClient, type SUNW in the Stock Symbol text field, and click GetQuote.
   
   The WSP returns a quote that's 10 minutes old along with the stock's 52-week price range, but not the trade volume or the market cap. See Figure 10.
   
   

   Figure 10: Return of Stock Quote From a Guest Member Request

    
   
2. Under View SOAP Messages, click the Request and Response links to view the SOAP messages exchanged between the WSC and the WSP, respectively.
   
   Figure 11 shows the SOAP request, secured by the X509 Token. The identity specified by the X.509 Token is CN=SJSAMClient, OU=Access Manager, O=Sun, L=Santa Clara, ST=California, C=US, which maps to the Guest role at the WSP, hence the return of a stock quote that's 10 minutes old.
   
   

   Figure 11 SOAP Request (Guest Member)

    
    
   

   Figure 12 SOAP Response (Guest Member)

    
   

Now go to Part 3: Exercises 4 and 5, in which you configure a WSC and a WSP for identity-enabled Web-service security and how to configure a stand-alone WSC, respectively.