Oracle9 i AS Containers for J2EE - Release 2

Date: 07/02/01

How-To: Configure Oracle's JAAS Provider with OC4J


  • Configure Oracle's JAAS Provider for use with your Oracle9 i AS Release 2 application server.
  • Use the jazn.jar command line administration tool.
  • Test Oracle's JAAS Provider is working correctly with the sample application.

Software Requirements

  • Oracle9iAS Containers for J2EE (9.0.3) Developer Preview is installed, available from OTN
  • Jakarta Ant, to build the application example, available here
  • Sun's JDK 1.3_01 or above

Notation

  • %OC4J_HOME% - The directory in which you installed OC4J.
  • %J2EE_HOME% - The directory where the oc4j.jar file exists within OC4J. This is typically 2 directories under %OC4J_HOME%. For example, if you installed OC4J to c:\ then %J2EE_HOME% would be c:\j2ee\home
  • %JAVA_HOME% - The directory where your JDK is installed
  • %HOWTO_HOME% - The directory how-to-Oracle-JAAS under the directory the ZIP file was unzipped to
  • JAZN - The old (and shorter) name for Oracle's JAAS Provider.

Introduction



JAZN Web Plug-inJAZNUserManagerJAZNUserManagerUserManagerJAZNUserManager
  • Integration with Oracle Internet Directory (OID) and Single Sign-On (SSO) - [JAZN-LDAP].
  • Secure, light weight, file-based user and group management - [JAZN-XML].
principals.xmljazn-data.xmlconfigjazn-data.xml

Configuring JAZN with OC4J

<jazn> <user-manager> orion-application.xml %J2EE_HOME%/config/application.xml

For use with LDAP


<jazn provider="LDAP"
      default-realm="my_realm"
      location="ldap://myhost:389" />

Alternatively, you can use the <user-manager> element like this.

<user-manager class="oracle.security.jazn.oc4j.JAZNUserManager">
    <property name="provider.type" value="LDAP" />
    <property name="realm.default" value="my_realm" />
    <property name="ldap.service" value="ldap://myhost:389" />
</user-manager>

Oracle recommends that you use the first method with the <jazn> element.  The second method only exists for backwards compatability.

For use with jazn-data.xml

NOTE:principles.xmladminjava -jar oc4j.jar -install

<jazn provider="XML"
      location="./jazn-data.xml" />



<user-manager class="oracle.security.jazn.oc4j.JAZNUserManager">
    <property name="provider.type" value="XML" />
    <property name="xml.store.fs.jazn" value="./jazn-data.xml" />
</user-manager>

jazn.com



Using jazn.jar

%J2EE_HOME%
java -jar jazn.jar
java -jar jazn.jar -help
Admintool usage:

 java -jar jazn.jar


-listusers [<realm> [-role <role>|-perm <permission>]] |
-listroles [<realm> [<user>|-role <role>]] |
-listrealms |
-listperms [<realm> { <user> |-role <role>}] |
-listperm <permission_name> |
-listprncpls |
-listprncpl <principal_name> |
-adduser <realm> <username> <password> |
-addrole <realm> <role> |
-addrealm <realm> <admin> {<adminpwd> <adminrole> |
          <adminrole> <userbase> <rolebase> <realmtype>}
-addperm <perm_name> <perm_class> <action> <target> [<description>] |
-addprncpl <prncpl_name> <prncpl_class> <params> [<description>] |
-remuser <realm> <user> |
-remrole <realm> <role> |
-remrealm <realm> |
-remperm <permission_name> |
-remprncpl <principal_name> |
-grantperm <realm> {user|-role <role>} <permission_class> <permission_params> |
-grantrole <role> <realm> {user|-role <to_role>} |
-revokeperm <realm> {user|-role <role>} <permission_class> <permission_params> |
-revokerole <role> <realm> {user|-role <from_role>} |
-setpasswd <realm> <user> <old_pwd> <new_pwd> |
-checkpasswd <realm> <user> [-pw <password>] |
-getconfig <default_realm> <admin> <password> |
-convert <filename> <realm> |
-shell
-help


java -jar jazn.jar -adduser <realm> <myuser> <password>

JAZN will use the RealmLoginModule to ask you for a username and password. Any administrator can be used, for example the default admin user.

NOTE: If you installed OC4J without JAZN enabled, to enable the admin user you will need to open a command prompt at the %J2EE_HOME% directory and type the command below. This will enable the admin user in the jazn-data.xml file (or the LDAP server).

java -jar oc4j.jar -install

Once you have created a user you will need to add the user to a specific role, this can be done with the following command

java -jar jazn.jar -grantrole <role> <realm> <myuser>

Pre-requisites for running the examples

  • Your JDK is configured to use the Oracle policy. If you are using the latest Oracle JDK this is the default. However if you are using Sun's JDK you will need to add the two lines below to the end of the %JAVA_HOME%/jre/lib/security/java.security file.
  • auth.policy.provider=oracle.security.jazn.spi.PolicyProvider
    login.configuration.provider=oracle.security.jazn.spi.LoginConfigProvider

     
  • The user test with a password of user exists in your JAZN configuration. To create this user, from %J2EE_HOME% execute the commands below. These will add a user called test with a password user to the default domain, and then add them to the group users.

    • java -jar jazn.jar -adduser jazn.com test user
    • java -jar jazn.jar -grantrole users jazn.com test

You do not need access to a database for the example application.

Download the example file (how-to-security-jaas.zip ) and unzip it into a directory of your choice ( < example_home > ).  There are 2 examples in the zip file, a simple servlet example, and a more complex EJB example. Both are packaged in one EAR file. The examples will be deployed via the admin utility.The zip file contains the following files and directories:

  • how-to-jazn/src/ - contains all Java source code for the example.
    • client/ 
      • IdentityClient.java - Test application client for the JAZN example.
      • jndi.properties - Properties file specifing JNDI environment.
    • ejb/
      • Identity.java - Identity EJB remote interface.
      • Identity Home.java - Identity EJB home interface.
      • Identity Bean.java - Identity EJB implementation.
      • META-INF/
        • ejb-jar.xml - J2EE ejb deployment descriptor.
        • orion-ejb-jar.xml - OC4J specific deployment descriptor.
    • web/
      • login.jsp - The page used by the container to display the login form. This could also be an HTML file
      • error.jsp - The page displayed when a login fails
      • jazn/
        • ResultServlet.java - The servlet that will display a message if you log in.
  • how-to-jazn/ lib/
    • identityApp.ear - Deployable J2EE application files.
  • how-to-jazn/ etc/
    • jndi.properties - For use with ant.
    • ejb-jar.xmlv
    • orion-ejb-jar.xml - For use with ant.
    • web.xml - For use with ant.
    • application.xml - For use with ant.
    • orion-application.xml - For use with ant.
  • how-to-jazn/doc/
    • Readme.html - This document.
  • how-to-jazn/build.xml - An Ant build file.
  • how-to-jazn/common.xml - Used by build.xml

General points

  • The how-to-jazn/etc/orion-application.xml file contains 2 security role mappings, one for the servlet module, and one for the ejb module. These could be split into the appropriate orion-ejb-jar.xml and orion-web.xml files.

The Servlet application

No compilation of the servlet is needed. However, to enable security, we need to add the security constraints to the web.xml deployment descriptor. Below is the portion of %HOWTO_HOME%/etc/web.xml that will enable form based authentication, with the role ' jazn_test' being alowed to access the url ' /result', i.e. our servlet.

 <login-config>
   <auth-method>FORM</auth-method>
   <form-login-config>
     <form-login-page>login.jsp</form-login-page>
     <form-error-page>error.jsp</form-error-page>
   </form-login-config>
 </login-config>
 <security-role>
   <role-name>jazn_test</role-name>
 </security-role>
 <security-constraint>
   <web-resource-collection>
     <web-resource-name>senderservlet</web-resource-name>
     <url-pattern>/*</url-pattern>
   </web-resource-collection>
   <auth-constraint>
       <role-name>jazn_test</role-name>
   </auth-constraint>
 </security-constraint>

Only users with the 'jazn_test' role granted can access the protected URL. Users trying to access the URL will be asked to log into the 'Jazn Test' realm. This has declared our security constraints to the container. As mentioned above this is in the orion-application.xml file.

  • To map the J2EE role 'jazn_test' declared in the web.xml file to an OC4J group, we have to provide the <security-role-mappins> tags, to read

    <security-role-mapping name="jazn_test">
         <group name="users" />
    </security-role-mapping>

Compiling and deploying the application


Using Ant and admin.jar
  1. Ensure Ant 1.4.x or above is installed on your machine and configured correctly.
  2. Set %JAVA_HOME% and %OC4J_HOME% environment variables.  Note: On some operating systems Ant does not currently support the use of environment variables,  if this is the case for your operating system,  please modify the common.xml file located in the root example directory.
  3. From the example application root directory [the directory where the build.xml file is located] execute the following command:
  4. ant

  5. You should now have a newly created identityApp.ear and  identityClient.jar file in your %HOWTO_HOME%/lib directory.
  6. Deploy this J2EE application to a running instance of OC4J Release 2 by executing the following commands from the %HOWTO_HOME% directory. Check the %HOWTO_HOME%/build.xml script to make sure that the correct username and password are used.

    ant deploy-usingadmin.jar

Running the application


  1. That the following does exist in the <OC4J_HOME> /application-deployments/identity/orion-application.xml file.
<jazn provider="XML" location="../../config/jazn-data.xml" />
  • That the following does not exist in the <OC4J_HOME> /application-deployments/identity/orion-application.xml file.
<principals path="./principals.xml" />
  • That the security-role and method-permissions identified in the ejb-jar.xml file (located in <example-home>/etc)
      ...
      <security-role>
         <role-name>beanUser</role-name>
      </security-role>
      <method-permission>
         <role-name>beanUser</role-name>
         <method>
            <ejb-name>Identity</ejb-name>
            <method-name>getPrincipalName</method-name>
         </method>
      </method-permission>
      ...
  • Map to the administrators group in the deployed orion-application.xml file.
    ...
    <security-role-mapping name="beanUser">
        <group name="administrators" />
    </security-role-mapping>
    ...
  • That the security-role and method-permissions identified in the web.xml file (located in <example-home>/etc)
      ...
      <security-role>
         <role-name>jazn_test</role-name>
      </security-role>
      ...
  • Map to the administrators group in the deployed orion-application.xml file.
    ...
    <security-role-mapping name="jazn_test">
        <group name="users" />
    </security-role-mapping>
    ...

To run the application choose either of the following.

  1. For the EJB module, test the application by running the client with the following command,  from the %HOWTO_HOME% directory
  2.          ant run

  3. For the servlet module, open the url http://localhost:8888/identity in a web browser. You should be able to log in using any user in the Administrators group, e.g the admin user.
administrators java.naming.security.principal java.naming.security.credentials jndi.properties

Summary


  • Learnt how to configure your application to use JAZNUserManager for authentication and authorization rather that the default OC4J UserManager and the principals.xml file.
  • Learnt how to use the JAZN command line tool administer user and role information in JAZN.
  • Run the example to see JAZN in action.

Appendix A: Changes from Previous Versions

OC4J 9.0.3 Developers Preview 2 to OC4J 9.0.3 Production

  1. OC4J now uses the Java security policies. Therefore to enable JAZN make sure that you have configured your JDK to use the Oracle policy. If you are using the latest Oracle JDK this is the default. However if you are using Sun's JDK you will need to add the two lines below to the end of the %JAVA_HOME%/jre/lib/security/java.security file.

    auth.policy.provider=oracle.security.jazn.spi.PolicyProvider
    login.configuration.provider=oracle.security.jazn.spi.LoginConfigProvider

  2. The jazn.jar utility now requires a username and password. Correct users are any user in the administrator group, for example the default admin user. However you need to enable the admin user if JAZN was not the default user manager on install (true of OC4J Standalone). To enable the admin user, once you have configured OC4J to use JAZN, type the command below from the %J2EE_HOME% directory

    java -jar oc4j.jar -install

Left Curve
Popular Downloads
Right Curve
Left Curve Right Curve