How-To: Integrate a Custom JAAS Login Module in OC4J.

Date: Feb 20, 2006
Author:  
Sirish V Vepa


Introduction

A JAAS login module is used to authenticate and authorize clients when a J2EE resource is accessed. This demo application consists of an EJB and a Servlet. The EJB is a simple session bean that has one business method, which returns the credentials of the caller. The servlet provides a mechanism to access the EJB by a web-based client.

The JAAS login module first authenticates the client and establishes the roles associated with the authenticated Principal. Using this information, the container is able to authorize the client before accessing the J2EE resource (the EJB in this example).

After going through this example, you will be able to

  • Develop a JAAS login module.
  • Deploy the JAAS login module in OC4J.
  • Configure OC4J to delegate the security checks to the custom login module for resources defined in an Application (EJBs, Servlets, etc).



Prerequisites

What you need to know

Software Requirements

This demo requires the following software components are installed and configured correctly.

  • OracleAS 10.1.3 is installed, available from OTN
  • Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape etc.

Notations

List the notation used throughout the document. Keep to the convention of %NAME% for environment like variables.

  • %ORACLE_HOME% - The directory where you installed the Oracle Application Server 10 g.
  • %JAVA_HOME% - The directory where your JDK is installed
  • %HOWTO_HOME% - The directory where this demo is unzipped.

Building the Application



Developing the JAAS Login Module.

The example JAAS login module authenticates the developer or the manager user. After successfully authenticating the user, a Principal corresponding to the roles associated with the user is added to the current authenticated Subject. The manager user is a member of the managers and developers role. The developer user is a member of the developers role only.


The following code snippet from the JAAS login module shows how this is accomplished.

 

        if(username.equals("developer") && password.equals("welcome")) 
        {
                _succeeded = true;
            _name = "developer";
           _password = password.toCharArray();
           _authPrincipals = new SamplePrincipal[2];
            //Adding username as principal to the subject
            _authPrincipals[0] = new SamplePrincipal("developer");
            //Adding role developers to the subject
            _authPrincipals[1] = new SamplePrincipal("developers");
        }





Packaging the JAAS Login Module

Alternatively, to facilitate automated deployment, additional deployment instructions can be placed in certain XML file packaged along with the application archive file. This example uses the orion-application.xml file to accomplish an automated deployment.

OC4J must be instructed to use a custom JAAS login module for performing the security checks. This is accomplished by the following XML snippet in the orion-application.xml file packaged as part of the ear file.

    <jazn provider="XML" > 
     <property name="role.mapping.dynamic" value="true"/> 
     <property name="custom.loginmodule.provider" value="true"/>
   </jazn>

The following snippet configures the application to use the custom login module.

   <!-- Configuring a Login Module in an Application EAR file.  --><
   <jazn-loginconfig>
 <application>
  <name>cutomjaas</name>
  <login-modules>
   <login-module>
    <class>oracle.security.jazn.samples.SampleLoginModule</class>
    <control-flag>required</control-flag>
    <options>
     <option>
      <name>debug</name>
      <value>true</value>
     </option>
    </options>
   </login-module>
  </login-modules>
 </application>
   </jazn-loginconfig>

Since the application contains an EJB, users should be given namespace access so that it can execute read and write operations on the EJB. The following snippet shows how the namespace access is granted to the managers and developers role.

 

<namespace-access>
 <read-access>
  <namespace-resource root="">
   <security-role-mapping name="sr_developer">
    <group name="developers"/>
   </security-role-mapping>
   <security-role-mapping name="sr_manager">
    <group name="managers"/>
   </security-role-mapping>
  </namespace-resource>
 </read-access>
</namespace-access>


And finally, the logical roles defined in the application are mapped to roles supported by the custom login module. The following snippet from the orion-application.xml file performs the mapping.

 

<!-- Mapping the logical role to the Container Role -->
<security-role-mapping name="sr_manager">
 <group name="managers" />
</security-role-mapping>
<security-role-mapping name="sr_developer">
  <group name="developers" />
</security-role-mapping>


Running the Application

This section describes how to run the sample application.

Examining the How to Distribution

The distribution contains the following files:

  • howtocustomjaas/src/ - contains all Java source code for the example.
    • ejb/
      • Hello.java- Remote Interface
      • HelloHome.java- Home Interface
      • HelloBean.java- Session Bean Implementation.
    • jaasmodule/
      • SampleLoginModule.java- Custom Login Module
      • SamplePrincipal.java- Custom Principal Class Implementation.
      web/
      • HelloServlet.java- Servlet accessing the HelloBean EJB.
    • client/
      • HelloClient.java- Application Client for the EJB
  • build- temporary directory created during the build.
  • log- temporary directory created holding build/deploy logs.
  • etc- all necessary deployment descriptors to package the application.
  • doc- the How-to document.

Configuring the Environment

ant-oracle.properties
  • oracle.home - the root directory of oracle installation.  Defaults to ORACLE_HOME environment variable.
  • java.home -  the root directory of JDK installation.  Defaults to JAVA_HOME environment variable.
  • oracleas.host - the hostname of the platform on which the OC4J instance is running.  Defaults to localhost.
  • oracleas.http.port - the port on which the OC4J HTTP listener is listening.  Defaults to 8888.
  • oracleas.admin.port  - the port on which the OC4J administration processor is listening.  Defaults to 23791.
  • oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
  • oracleas.admin.password - the password for the OC4J administrator.  Defaults to " welcome".
  • oracleas.binding.module - the name of the HTTP web site to which the deployed application is bound.  Defaults to " default-web-site".
%ORACLE_HOME%/ant/bin

Configuring the Environment for a Managed OracleAS Instance

g
  • oracleas.http.port - the port on which the Oracle HTTP Server (OHS) is listening.
  • oracleas.admin.port  - The OPMN request port, as specified in opmn.xml, the default value is 6003.  You can also check the OPMN request port using the following command: %ORACLE_HOME%/opmn/bin/opmnctl status -port
  • oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
  • oracleas.deployer.uri - the URI to use to do the different administration operation (deployment, undeployment). The file contains different URI depending of the topology of your application: stand alone OC4J, Managed Single Node or Managed Cluster. You just need to un-comment the URI that matches your toplogy.
  • oracleas.oc4j.instance - This is the managed OC4J instance where the application will be deployed or undeployed.
opmn:ormi://localhost:6003:home/customjaas

 


Deploying the JAAS Login Module

To build the JAAS Login module and the Principal class implementation used by the login module, type the following from the %HOWTO_HOME% directory:

  • ant build-sample-jaas-jar

You should now have the newly created customjaas_lm.jar in your %HOWTO_HOME%/lib directory.
Copy this JAR file under your %JAVA_HOME%/jre/lib/ext directory.

Granting RMI Permissions

To enable remote Java client access to EJBs using RMI, we must grant RMI permission to the "managers" and "developers" role. Type the following from the %HOWTO_HOME% directory:

  • ant assign-rmi-perms
  • java -jar jazn.jar -user oc4jadmin -password welcome \
     -grantperm managers oracle.security.jazn.samples.SamplePrincipal \
     com.evermind.server.rmi.RMIPermission login

    If you are using an Oracle Application Server install then you have to specify home directory for your OC4J instance so that the jazn-data.xml for the right OC4J instance is updated with RMI login Permission. Make sure to modify %oracleas.oc4j.instance% appropriately for your environment.

    •  

      java -jar -Doracle.j2ee.home=%ORACLE_HOME%\j2ee\ %oracleas.oc4j.instance% jazn.jar -user oc4jadmin -password welcome \
       -grantperm managers oracle.security.jazn.samples.SamplePrincipal \
       com.evermind.server.rmi.RMIPermission login

Starting the OC4J Instance

g
  • Stand Alone Installation: %ORACLE_HOME%/bin/oc4j start
    Note that the oc4j command expects the JAVA_HOME environment variable to point to a full JDK installation.

  • OracleAS Managed Installation: %ORACLE_HOME%/opmn/bin/opmnctl startall

Generating, Compiling and Deploying the Application

To build the application, type the following command from the %HOWTO_HOME% directory:

  • ant

You should now have the newly created customjaas..ear in your %HOWTO_HOME%/lib directory.

This command would also attempt to deploy the application if the build is successful. It will first test whether OC4J is running.

Note that you can also deploy the application separately . Ensure the %ORACLE_HOME% environment variable is defined, and from the %HOWTO_HOME% directory, type the command:

ant deploy

Running the Application Java Client

To run the sample Java client, type the following command

  • ant run

The client prints name of the user invoking the EJB client. The name is returned by OC4J. The below figure shows the output while running the client.

 

run:
     [echo] -----> Running JNDI client
     [java] client started...
     [java] Hello manager


Return to the console where you started OC4J and you will see debug output generated by the custom JAAS login module.

Running a Web-Based Client

The sample includes a web application that can be accessed by a HTML browser. Follow the instructions below to access the servlet.

  1. Start a HTML browser.
  2.  

  3. Point your browser at http://oracleas.host:oracleas.http.port/customjaas where oracleas.host and oracleas.http.port are defined in your ant-oracle.properties file.

     

     

  4. Click on the link here. The browser will prompt you for credentials to access the web application. Supply username ' developer' and password ' welcome' as shown the figure below.

     

     

  5. The servlet will invoke a method on the EJB and the name of the user who authenticated to the container is displayed in the browser.

     

Summary


  • Develop a JAAS Login Module
  • Configure the JAAS Login Module with an Application
  • Deploy the JAAS login module into OC4J and
  • Exercise the JAAS Login Module via an Application client and Browser based client.
Left Curve
Popular Downloads
Right Curve
Untitled Document