5
Quick Start JAAS Provider Demo

This chapter describes how to quickly configure and run a sample Java2 Platform, Enterprise Edition (J2EE) application that uses the JAAS Provider, the Oracle9iAS Containers for J2EE (OC4J) user authentication, authorization, and delegation service.

This chapter contains these topics:

• Quick Start JAAS Provider Demo Overview

• Setting Up the Demo

• Running the Demo

• Testing the JAZN Admintool

  Notes: For the purpose of this Quick Start demonstration, many terms and concepts in this chapter are described at a high level. Where appropriate, references are provided to other sections in this and other guides for specific information on these terms and concepts. This example provides instructions for use with the standalone version of OC4J. Please refer to the OC4J User's Guide for instructions on using the example with the complete Oracle9iAS installation.

Quick Start JAAS Provider Demo Overview

This Quick Start demo is designed to get you up and running with JAAS provider using the sample demo application, callerInfo. It also demonstrates the use of the JAZN Admintool.

The callerInfo demo indicates whether or not the user attempting to log into the application has succeeded and with which roles and permissions.

The callerInfo demo application demonstrates use of the following features:

• OC4J as the HTTP listener that listens for user login requests and functions as the Web container that stores the callerInfo application

• Basic authentication for validating the login credentials of the user attempting to access the callerInfo demo application (authentication)

• The JAAS provider for enforcing the roles and permissions assigned to the authenticated user (authorization)

• The XML-based provider type as the JAAS provider repository provider for storing users, roles, and permissions

• The J2EE environment to run the application

  See Also: The following sections for more detailed information on the concepts covered in this Quick Start demo: Oracle9iAS Containers for J2EE User's Guide for further information on OC4J configuration Oracle9i Application Server Security Guide for further information on JAAS Provider configuration "Integrating the JAAS Provider with Basic Authentication" for further information on Basic authentication "Realm Management in XML-Based Environments" for further information on using XML files as the JAAS Provider environment type "JAAS Provider Integration in J2SE Application Environments" for further information on the J2EE environment http://jazn.us.oracle.com for additional JAAS provider information

Setting Up the Demo

These are the basic tasks you must perform to set up the Quick Start demo:

• Task 1: Modify OC4J Configuration Files

• Task 2: Change Default Configurations (Optional)

Task 1: Modify OC4J Configuration Files

In order to use the callerInfo demo, you must modify two OC4J files in $ORACLE_HOME/j2ee/home/config/.

1. Modify the server.xml file by removing the comments around :

   <application name="callerInfo" path="../jazn/demo/callerInfo/callerInfo.ear" />
   
   

2. Modify the default-web-site.xml file by removing the comments around :

   <web-app application="callerInfo" name="callerInfo-web" root="/jazn" />
   
   

   See Also: Oracle9iAS Containers for J2EE User's Guide for further information on OC4J configuration Oracle9i Application Server Security Guide for further information on JAAS Provider configuration

Task 2: Change Default Configurations (Optional)

The sample callerInfo application is installed with several default configuration settings that enable you to immediately run the JAAS provider. If you want to run the JAAS provider using these default settings, you can skip this section and go to "Running the Demo".

If you make any changes to the default configurations, rebuild the directory with jar or Ant.

For the purpose of this demo, two different realms are available for experimentation. Realms provide access to users and roles. The two realms are contained in jazn-data.xml files located in the directory j2ee/home/jazn/config/:

• A sample realm, sample_subrealm, is defined in the jazn-data.xml file. sample_subrealm and the jazn-data.xml file are the current defaults.

• A more complex sample realm, jazn.com, is defined in the jazn-data1.xml file.

To use a realm other than the default sample_subrealm, you must modify the jazn element of the OC4J orion-application.xml (in the directory jazn/demo/callerinfo/etc/) as follows:

• Change the realm, default-realm, from the default value, sample_subrealm, to jazn.com or any realm that you have created.

• Change location from the default value, jazn-data.xml, to jazn-data1.xml or any properly configured data file that you have created.

  See Also: "Managing XML-Based Provider Data with the XML Schema" for further information on the jazn-data.xml file

Running the Demo

To start OC4J and connect to the demo application:

1. Start OC4J with the JAAS provider as follows:

   java -jar oc4j.jar
   
   

   For the purposes of this Quick Start demo, an insecure and simple manner for starting OC4J is presented. For more information about starting OC4J in secure mode, see "Starting an Application".

2. Run the callerInfo application from a Web browser:

   http://hostname:8888/jazn
   
   

3. Follow instructions on the Web page.

4. Log in with either of the following usernames and passwords:
   • admin/welcome

     Username admin is assigned the role manager, which is mapped to sr_manager.

   • user/456

     Username user is assigned the role developer, which is mapped to sr_developer.

     See Also: Oracle9iAS Containers for J2EE User's Guide "Testing and Executing the J2EE Application" for further information on starting OC4J with the JAAS provider Chapter 9, "Developing Secure J2EE Applications" to view the code for the callerInfo demo used in this Quick Start demo

Viewing the Results of the callerInfo Demo

When the call to the callerInfo demo application is successful, with the username user, for example, the browser displays a message similar to the following:

Time stamp: Fri Aug 24 19:11:37 PDT 2001 request.getRemoteUser =
sample_subrealm/user
request.isUserInRole('FOO') = false
request.isUserInRole('ar_manager') = false
request.isUserInRole('ar_developer') = true
request.getUserPrincipal = ([JAZNUserAdaptor: user=[XMLRealmUser:
sample_subrealm/user])

In summary, this Quick Start demo performed the following:

• The login request from username user used basic authentication to access the callerInfo demo application.

• The OC4J listener listened for the login request from username user.

• The JAAS provider enforced the roles and permissions assigned to the authenticated user user.

• The users, roles, and permissions were retrieved from the XML-based JAAS provider type.

Testing the JAZN Admintool

The JAZN Admintool is a Java console application that manages provider data from the command prompt.

You can invoke the JAZN Admintool from the UNIX command line interface as follows:

java -jar jazn.jar -listusers sample_subrealm

These are a few of the command options that you can experiment with from a command-line interface.

-listusers [realm [-role role|-perm permission]] 
-listroles [realm [user|-role role]|-perm permission] 
-listrealms 
-listperms {realm user |-role role|-realm realm} 
-help

The JAZN Admintool also includes a shell. The following screen listing shows how to access the JAZN Admintool shell and some basic shell commands that you can run, with results.

> java -jar jazn.jar -shell
JAZN:> ls
realms       policy
JAZN:> cd realms
JAZN:> ls
sample_subrealm

JAZN:> cd sample_subrealm
JAZN:sample_subrealm> ls
users        roles
JAZN:sample_subrealm> cd users
JAZN:sample_subrealm> ls
admin
rachel
naresh
ray
stella
anonymous

JAZN:sample_subrealm> add scott tiger
JAZN:sample_subrealm> ls
anonymous
rachel
ray
scott
stella
admin
naresh

JAZN:sample_subrealm> rm scott
JAZN:sample_subrealm> ls
admin
rachel
naresh
ray
stella
anonymous

JAZN:sample_subrealm> exit
JAZN:sample_subrealm>