This Tech Tip reprinted with permission by java.sun.com

This Tech Tip shows you how to access a secure Enterprise JavaBeans component (also called an "enterprise bean") from a standalone Java client and from a Java EE application client that uses Java Web Start technology. The tip presents examples that show these clients accessing a secure Management Enterprise JavaBean (MEJB) that conforms to the J2EE Management specification, JSR 77. The J2EE Management specification provides a standard management model for exposing and accessing management information, operations, and attributes for J2EE components. An MEJB provides interoperable remote access to the model from any standard J2EE application.

The tip assumes that you are using either the Sun Java System Application Server 8.x or a GlassFish build. You can download Sun Java Application Server 8.2 or 8.1 as part of the J2EE 1.4 SDK from the J2EE 1.4 Downloads page. GlassFish is an open source Java EE-based application server. You can download GlassFish from the GlassFish Community Downloads page.

Securing an Enterprise Bean

Security for J2EE application components such as enterprise beans is provided by their containers. A container provides two kinds of security: declarative and programmatic. Declarative security expresses an application's security structure, including security roles, access control, and authentication requirements, in a form external to the application (that is, in a deployment descriptor). Programmatic security is embedded in an application and is used to make security decisions. Programmatic security is useful when declarative security alone is not sufficient to express the security model of an application.

The mechanics of providing declarative security for these resources involve mapping in a deployment descriptor individual user identities or groups of user identities to a role, that is, an abstract name for the permission to access a particular set of resources in an application.

For example, the following elements in the Sun Java Application Server deployment descriptor, sun-application.xml, maps the group name "asadmin" to the security role "admin-role":

 <security-role-mapping>
 <role-name>admin-role</role-name>
 <group-name>asadmin</group-name>
 </security-role-mapping> 

In addition, application servers such as Sun Java System Application Server 8.x or GlassFish provide a way to associate groups while creating a principal (that is, an individual user identity that can be authenticated). This is done through the asadmin create-file-user command (whose syntax is as follows):

 asadmin create-file-user --port <port> --host <host> 
 --user <user-id> --passwordfile <passwordfile-location> 
 --authrealmname admin-realm --groups <admingrp> 
 <realm-user-id>

After the mapping is in place, the container can determine if a user has the needed permission to access a protected resource such as a secure enterprise bean.

For standalone clients, declarative security is insufficient to communicate with a secure enterprise bean. Instead you need to provide programmatic security.

Programmatic Security for a Secure Enterprise Bean

Programmatic security for a standalone client requires an API that provides programmatic login for the client. The Sun Java System Application Server 8.x and GlassFish provide this API through the class com.sun.appserv.security.ProgrammaticLogin. This class exposes relevant methods to perform programmatic login operations. The examples for this tip use the following ProgrammaticLogin method to access an MEJB:

 public Boolean login(String user, String password); 

The login() method supplies a username and password. This information is used to attempt to login to the default authentication realm (that is, the collection of users and groups that are controlled by the same authentication policy). If the authentication succeeds, that is, the identity of the user is verified, a security context is established representing the user. This allows applications to programmatically handle authentication.

Let's look at an example of programmatic security for a secure enterprise bean. Accompanying this tip is a package that contains the code for a standalone client that accesses a secure MEJB. Here's a code snippet taken from the standalone client code:

 ProgrammaticLogin pm = new ProgrammaticLogin(); 
 pm.login(userId, password);
 Context initial = new InitialContext();
 Object objref = initial.lookup("ejb/mgmt/MEJB");
 ManagementHome home =
 (ManagementHome)PortableRemoteObject.narrow(
 objref, ManagementHome.class);
 Management mejb = home.create();
 String domain = mejb.getDefaultDomain();

The code first instantiates ProgrammaticLogin and then accesses its login() method, providing the userId and password. The login() method caches this information on the client side until an enterprise bean method is called from the client. The code then does the processing for access to the MEJB. It instantiates the InitialContext, and then looks up the ManagementHome object by specifying the JNDI name of MEJB home object, ejb/mgmt/MEJB.

You might ask how are the user's credentials processed? The user credentials are passed to the server when the client calls the enterprise bean's method. The method call is intercepted by the IIOP/ORB infrastructure and the credentials are stored in the security context. If the method being invoked needs permission, the EJB container retrieves the user credentials from the security context and validates them. If the credentials are not valid, the method throws a security exception.

After the lookup and narrow methods succeed, a reference to the Management object is created. This is done by calling the ManagementHome's create() method -- this is part of the standard enterprise bean invocation process. This is further described in the section Developing Clients Without the ACC in the Sun Java Application Server Platform Edition 8.1 Developer's Guide.

Now it's time to try the sample applications. The samples require you to have access to ant or asant that is included in GlassFish and Sun Java Application Server 8.1 or 8.2.

Running the Standalone Client Example

The standalone client works directly with a predeployed system application. To install and run the standalone client example:

1. Ensure that either Sun Java System Application Server 8.2 or GlassFish is installed. These instructions use GlassFish, which you can download from the GlassFish Community Downloads page.
   
2. Download the sample package for the tip and extract its contents. You should now see the newly extracted directory as <sample_install_dir>/stand_alone_client, where <sample_install_dir> is the directory in which you installed the sample package. For example, if you extracted he contents to C:\ on a Windows machine, then your newly created directory should be at C:\stand_alone_client. The stand_alone_client directory contains the source code for the client, MEJBClient.java, a build file, build.xml, and an output file, output.txt.
   
3. Start the GlassFish Application Server by entering the following command:
   
   

    <GF_install_dir>/bin/asadmin start-domain domain1

   where <GF_install_dir> is the directory in which you installed GlassFish.
   
4. Modify the <user defined properties> section of the build.xml file as appropriate for your application server installation. You don't have to edit any other part of build.xml.
   
5. Create a default realm user using the asadmin command line utility as follows (the command is shown on multiple lines for formatting purposes):
   
   

    <GF_install_dir>/bin/asadmin create-file-user 
    --host <host-name> --port <admin-port-number> 
    --user <admin-user> --passwordfile <admin-password-file-path> 
    --groups <security-role-mapping-group-name> <realm.user.id> 

   You will need to create a password file that includes the following lines:
   
   

    AS_ADMIN_PASSWORD=<admin-password>
    AS_ADMIN_USERPASSWORD=<realm.user.password>

   and pass this file with the --passwordfile option.
   
   Make sure that the values for realm.user.id and realm.user.password match the values given in build.xml, and the value for security-role-mapping-group-name matches the value given in sun-application.xml as described earlier in the tip. Substitute other values appropriately before running the command.
   
   Use the asadmin command 'list-file-users' to check that you successfully created the default realm user. For further information about the asadmin command, enter asadmin help on the command line.
   
6. Compile and run MEJBClient.java.

    > cd stand_alone_client
    > ant run

   You should see output similar to the following.
   
   

    run:
    [java] Jan 17, 2006 2:48:49 PM com.sun.corba.ee.spi.
    logging.LogWrapperBase doLog
    [java] INFO: "IOP00710299: (INTERNAL) Successfully 
    created IIOP listener on the specified host/port: 
    all interfaces/52185"
    [java] ***Got the MEJB!!
    [java] ***MEJB default domain = DefaultDomain
    ...
    BUILD SUCCESSFUL

   The content of the output.txt file contains the complete output.

Running the Java Web Start Technology Example

This example uses a Java EE application client that will be deployed to the application server. As is the case for the previous example, this example uses GlassFish. This example has been tested to work with JDK 5.0 or JRE 5.0 only.

To install and run the example:

1. Download the sample archive.
   
2. Deploy the application client using the deploy command:

    <GF_install_dir>/bin/asadmin deploy --host <host-name> 
    --port <admin-port-number> --user <admin-user> 
    --passwordfile <admin-password-file-path> 
    ttfeb2006acc-mejbClient.jar

3. Open your application server log (for example, <GF_install_dir>/domains/domain1/log/server.txt). Somewhere in the log you should see a line like the following:
   
   

    [#|2006-01-17T15:10:21.112-0800|... Java Web Start 
    services started for stand-alone app client ... 
    name=acc-mejbClient, context root=/acc-mejbClient, 
    module name=|#] 

   The URL for accessing the application client using Java Web Start is comprised of the default GlassFish instance URL and the context root (which is the "Name=" value in the line shown above). So, for a default instance Glassfish URL of http://8080 and a context root of acc-mejbClient, the URL for accessing the application client using Java Web Start is http://localhost:8080/acc-mejbClient.
   
4. This example displays output in the Java Console. To see the output, you need to configure Java Web Start to show the Java Console. To configure the Java Console option, first determine the location of Java Web Start (this is usually <jre-install-dir>/bin/javaws or <jre-install-dir>/bin/jws). Then invoke Java Web Start and turn on the 'show console' option. Here is how to determine the location of Java Web Start based on the browser type and the operating system:
   
   
   • Internet Explorer and FireFox on Windows:
     • Click on <start> <My Computer>.
     • In the 'My Computer' window, select the menu item <Tools> then <Folder Options>.
     • In the 'Folder Options' window, select the <File Types> tab.
     • Select the item with the extension 'JNLP'.
     • Click <Advanced> <Edit> and verify that the 'Application used to perform action' is correct, or change it to the correct one, and save the changes.
       
   • Netscape on Windows/Solaris:
     • Invoke the Netscape browser.
     • Select the menu item <Edit> then <Preferences>.
     • Expand <Navigator> node and select <Helper Applications>. You should see a list of File Types on the right.
     • Select application/x-java-jnlp-file.
     • Click <Edit>. Make the appropriate change and save it.

     Invoke Java Web Start in a command window using the Java Web Start location determined above. This brings up 'the 'Java Application Cache Viewer' window.

     Then:

     • In the 'Java Application Cache Viewer' window select the menu item <Edit>, then <Preferences>. This should display 'Java Control Panel'.
     • Select the <Advanced Tab>.
     • Expand <Java Console> and select <Show Console>. Click the <OK> button.
       
     You can exit Java Web Start by selecting the menu item <File>, then <Exit>.
     
     
5. Open a web browser and enter the URL determined in step 3. This should launch Java Web Start. You should see prompts for a userID and password. After you respond to the prompts, the application client should display output similar to the output in the standalone client example.

Sreenivas Munnangi is a senior member of the Sun Java Application Server Administration and Management team. He has worked in the J2EE group for the last three years. He was a key contributor to the Application Server Enterprise Edition design and implementation. His earlier experience was in the areas of eCommerce applications, web applications, and N-tier application architecture.

Copyright (c) 2004-2005 Sun Microsystems, Inc.
All Rights Reserved.

 Related Tips

• Accessing an EJB from an applet
• Accessing bean components from JSP
• Accessing EJB from a servlet within the same container
• An example of a simple JSP page
• Automated code generation
• Automated update of EJB deployment descriptor
• Bean with Indexed Properties and Accessing Indexed values through JSP Bean tags
• Behavior of Timer Services in Transactions