Enterprise Bean Example Applications

The following example applications demonstrate adding security to enterprise beans applications:

Example: Securing an Enterprise Bean demonstrates adding basic login authentication to an enterprise bean application.

Discussion: Securing the Duke's Bank Example provides a brief discussion of how the Duke's Bank example provides security in that application.

Example: Securing an Enterprise Bean

In this section, we discuss how to configure an enterprise bean for username-password authentication. When a bean that is constrained by username-password 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 on the Application Server.

For this tutorial, we will add the security elements to an enterprise bean; build, package, and deploy the application; and then build and run the client application.

The completed version of this example can be found at <INSTALL>/javaeetutorial5/examples/ejb/cart-secure. This example was developed by starting with the unsecured enterprise bean application, cart, which is found in the directory <INSTALL>/javaeetutorial5/examples/ejb/cart and is discussed in The cart Example (page 743). We build on this example by adding the necessary elements to secure the application using username-password authentication.

In general, the following steps are necessary to add username-password authentication to an enterprise bean. 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.

Create an application like the one in The cart Example (page 743). The example in this tutorial starts with this example and demonstrates adding basic authentication of the client to this application. The example application discussed in this section can be found at <INSTALL>/javaeetutorial5/examples/ejb/cart-secure/.

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.

Modify the source code for the enterprise bean, CartBean.java, to specify which roles are authorized to access protected methods. This step is discussed in Annotating the Bean.

Modify the runtime deployment descriptor, sun-application.xml, to map the role used in this application (CartUser) to a group defined on the Application Server (user). This step is discussed in Linking Roles to Groups.

Modify the runtime deployment descriptor, sun-ejb-jar.xml, to add security elements that specify that username-password authentication is to be performed. For this example, these have been added. This step is discussed in Specifying an Authentication Mechanism.

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.

Build, package, and deploy the enterprise bean, then build and run the client application. See Building and Running the Example.

Annotating the Bean

The source code for the original /cart application was modified as shown in the following code snippet (modifications in bold, method details removed to save paper). The resulting file can be found in <INSTALL>/javaeetutorial5/examples/ejb/cart-secure/cart-secure-ejb/src/java/cart/secure/ejb/CartBean.java.

package com.sun.tutorial.javaee.ejb;

import java.util.ArrayList;
import java.util.List;
import javax.ejb.Remove;
import javax.ejb.Stateful;
import javax.annotation.security.RolesAllowed;

@Stateful()
public class CartBean implements Cart {

    String customerName;
    String customerId;
    List<String> contents;

    public void initialize(String person) throws BookException {
        ...
    }

    public void initialize(String person, String id) throws BookException {
        ... }

    @RolesAllowed("CartUser")
    public void addBook(String title) {
        contents.add(title);
    }

    @RolesAllowed("CartUser")
    public void removeBook(String title) throws BookException {
       ... }
    }
@RolesAllowed("CartUser")
    public List<String> getContents() {
        return contents;
    }

    @Remove()
    public void remove() {
        contents = null;
    }
}

The @RolesAllowed annotation is specified on methods for which we want to restrict access. In this example, only users in the role of CartUser will be allowed to add and remove books from the cart, and to list the contents of the cart. An @RolesAllowed annotation implicitly declares a role that will be referenced in the application, therefore, no @DeclareRoles annotation is required.

Linking Roles to Groups

The role of CartUser has been defined for this application, but there is no group of CartUser defined for the Application Server. To map the role that is defined for the application (CartUser) to a group that is defined on the Application Server (user), add a <security-role-mapping> element to the runtime deployment descriptor, sun-ejb-jar.xml, as shown below. In the original example, there was no need for this deployment descriptor, so it has been added specifically to specify the security role mapping. The runtime deployment descriptor is located in <INSTALL>/javaeetutorial5/examples/ejb/cart-secure/cart-secure-ejb/src/conf/sun-ejb-jar.xml. The code is shown in the deployment descriptor described in the following section, Specifying an Authentication Mechanism

Specifying an Authentication Mechanism

To enable username-password authentication for the application, add security elements to the runtime deployment descriptor, sun-ejb-jar.xml. The security element that needs to be added to the deployment descriptor is the <ior-security-config> element. In the original example, there was no need for this deployment descriptor, so it has been added specifically to enable username-password authentication. The deployment descriptor is located in <INSTALL>/javaeetutorial5/examples/ejb/cart-secure/cart-secure-ejb/src/conf/sun-ejb-jar.xml.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 9.0 
EJB 3.0//EN" "http://www.sun.com/software/appserver/dtds/sun-ejb-jar_3_0-0.dtd">
<sun-ejb-jar>
  <security-role-mapping>
    <role-name>CartUser</role-name>
    <group-name>user</group-name>
  </security-role-mapping>
  <enterprise-beans>
    <unique-id>0</unique-id>
    <ejb>
      <ejb-name>CartBean</ejb-name>
      <jndi-name>jacc_mr_CartBean</jndi-name>
      <pass-by-reference>false</pass-by-reference>
      <ior-security-config>
        <transport-config>
                 <integrity>supported</integrity>
          <confidentiality>supported</confidentiality>
          <establish-trust-in-target>supported</establish-trust-in-target>
          <establish-trust-in-client>supported</establish-trust-in-client>
        </transport-config>
        <as-context>
          <auth-method>username_password</auth-method>
          <realm>default</realm>
          <required>true</required>
        </as-context>
        <sas-context>
          <caller-propagation>supported</caller-propagation>
        </sas-context>
      </ior-security-config>
      <is-read-only-bean>false</is-read-only-bean>
      <refresh-period-in-seconds>-1</refresh-period-in-seconds>
      <gen-classes/>
    </ejb>
  </enterprise-beans>
</sun-ejb-jar>

Building and Running the Example

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).

From a terminal window or command prompt, go to the <INSTALL>/javaeetutorial5/examples/ejb/cart-secure/ directory.

Build, package, and deploy the enterprise application, and run the client application, by entering the following at the terminal window or command prompt in the ejb/cart-secure/ directory:

ant all

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.

If the user name and password are authenticated, the client displays the following output:

If the username and password are not authenticated, the client displays the following error:

If you see this response, verify the user name and password of the user that you entered in the login dialog, make sure that user is assigned to the group user, and re-run the client application.

At a future time, for iterative testing, you can undeploy the example by running the following command:

Discussion: Securing the Duke's Bank Example

The Duke's Bank application is an online banking application. Duke's Bank has two clients: an application client used by administrators to manage customers and accounts, and a web client used by customers to access account histories and perform transactions. The clients access the customer, account, and transaction information maintained in a database through enterprise beans. The Duke's Bank application demonstrates the way that many of the component technologies presented in this tutorial--enterprise beans, application clients, and web components--are applied to provide a simple but functional application.