HappyPappy Blog

Oracle Components for Java (OC4J) is a top notch J2EE container based on the Orion J2EE Server.

OC4J provides a number of mechanisms for user authentication; the older less secure method which uses the principals.xml file and a newer method based on the Java Authentication and Authorization Service (JAAS) standard.

Oracle’s implementation of JAAS is known as JAZN (Java AuthoriZatioN).
The older principals.xml file method is easier to setup but not as secure since passwords are exposed in clear text within the principals.xml file.

JAZN is more secure and flexible (you can even set it up to authenticate against LDAP) but many elements have to line up properly for it to work. Notes on how to setup JAZN can be found here.

Regardless of which method you choose the steps to setup OC4J based authentication are the same:

1) Decided which method to use and configure OC4J properly,
2) Add a user and/or group,
3) Specify a role based security constraint for your application, and
4) Map the security constraint role to a group specified in step 2.

Step 1 – Decide which method to use

This is probably the easiest step; open /config/application.xml; by default as of version 9.0.4.0 OC4J will use JAZN over principals.xml if both are configured.

If you want to use principals.xml you must remove (or comment out) the configuration line:

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

If you want to use JAZN then make sure this line exists inside of your application.xml file.

Step 2 – Add a user and/or group

If you have setup your OC4J to run the Admin Applications you can point your browser to http://<oc4j uri here>/adminoc4j and use the web screens to add users and groups.

If your Admin application isn’t setup or you can’t login into it (user id and password should be required) then you can modify the principals.xml file by hand as follows:

a) Inside the <groups> tags you can add, remove, or modify a group; in this case we’re adding an fmanager-users group;

<group name="fmanager-users">
  <description>File Manager Users</description>
  <permission name="fmanager"/>
</group>

b) Inside the <users> tags you can add, remove, or modify a user; in this case we’re adding a happypapp user and making him part of the fmanager-users group and users group;

<user username="happypapy" password="abc1234">
  <description>HappyPappy</description>
  <group-membership group="users"/>
  <group-membership group="fmanager-users"/>
</user>

If you’re using JAZN you can manage users and groups using the jazn.jar (java -jar jazn.jar …) utility located in the same folder as oc4j.jar to maintain users and groups. JAZN reference can be found here.

Note that some of the features of JAZN only work when you are using the XML provider but not if you are using the LDAP provider.

There are a few subtle changes to this step depending on the version of OC4J used; in later versions of OC4J there no longer appears to be a global principals.xml and you simply use jazn.jar or the management console to modify groups and users.

Step 3 – Specify a role based security constraint

Although OC4J supports both global (for all applications and modules) and local (specific applications and modules) we will only focus on setting up a local application.

For more information regarding all the OC4J configuration files please check here.

In our case we edit the web.xml file inside your web module which typically resides in the WEB-INF folder.

Specifically we make the following additions:

<!-- define a constraint for any resource (*) under this applicaction
and require an fmanager-user role (not group) to access it -->
<security-constraint>
  <display-name>File Manager Access</display-name>
  <web-resource-collection>

    <web-resource-name>File Manager</web-resource-name>
    <url-pattern>*</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>fmanager-user</role-name>
  </auth-constraint>
</security-constraint>
<!-- specify BASIC authentication, remember OC4J supports several types -->
<login-config>
  <auth-method>BASIC</auth-method>
</login-config>
<!-- define a security role of fmanager-user -->
<security-role>
  <role-name>fmanager-user</role-name>
</security-role>

Map the security constraint role to a security group

This step is performed by editing an orion-web.xml file which exists in the same folder as your web.xml file.

In this case we simply map the fmanager-user role in our application to the fmanager-users group defined in principals.xml;

<?xml version = '1.0' encoding = 'windows-1250'?>
<!DOCTYPE orion-application PUBLIC "-//Evermind//DTD J2EE Application runtime 1.2//EN" "http://xmlns.oracle.com/ias/dtds/orion-application.dtd">

<orion-web-app>
 <security-role-mapping name="fmanager-user">
 <group name="fmanager-users" />
 </security-role-mapping>
</orion-web-app>

Wrap Up

Next time you access your application via the web (needs to be setup in application.xml and http-web-site.xml) OC4J will prompt you for a user inside the fmanager-users group defined in principals.xml.

A quick word of caution; I noticed that if you try binding a new Web module to the default application most of this doesn’t work, it’s just easier to install a new application whenever you want to use OC4J authentication.