9
Developing Secure J2EE Applications

This chapter describes how to develop secure Java2 Platform, Enterprise Edition (J2EE) applications using the JAAS Provider and Oracle9iAS Containers for J2EE (OC4J).

This chapter contains these topics:

Developing Secure J2EE Applications Overview

J2EE application developers develop, deploy, and manage Web enabled, server-centric, enterprise level Java applications that are deployed in multiple tier environments. Using the JAAS provider enables developers to make these applications secure.

In J2EE applications, the JAAS provider is integrated with OC4J and provides the JAZNUserManager, an implementation of the OC4J UserManager.

After the creation of realms and related components described in Chapter 7, "Managing the JAAS Provider", the JAAS Provider can be integrated into J2EE applications to provide the following services:

Authentication in the J2EE Environment

Authentication is the process of verifying the identity of a user in a computing system, often as a prerequisite to granting access to resources in a system. User authentication in the J2EE environment is performed with the following:

Oracle9iAS Single Sign-On (for SSO environments) or the JAAS provider RealmLoginModule or other login module (for non-SSO environments)
JAZNUserManager for OC4J (Required)

Before HTTP requests can be dispatched to the target servlet, the JAZNUserManager gets the authenticated user information (set by mod_osso) from the HTTP request object and sets the JAAS subject in OC4J.

Running with the Permissions and Roles Associated with an Authenticated Identity (Optional)

You can choose to configure the JAZNUserManager so that a filter enables the target servlet to run with the permissions and roles associated with an authenticated identity or run-as identify. To do this, configure the jazn-web-app element.

See Also:

Chapter 7 of the Oracle9i Application Server Security Guide and "JAZNUserManager" for further information on options and configuration of the JAZNUserManager filter, including the jazn-web-app element

Interception of Servlet Invocation

The JAZNUserManager intercepts calls from Oracle9iAS Single Sign-On or the JAAS Provider RealmLoginModule and retrieves authentication information to identify the username and role.

Retrieving Authentication Information

The following javax.servlet.HttpServletRequest APIs retrieve authentication information within the servlet:

getRemoteUser for the authenticated username
getAuthType for the authentication scheme
getUserPrincipal for the authenticated principal object
getAttribute("java.security.cert.X509certificate") for the SSL client certificate.

(Optional if the Filter Element Has Been Set)

If the filter element has been set, JAZNUserManager performs the following when doFilter(ServletRequest request, ServletResponse response, FilterChain chain) is invoked:

For SSO or Basic authentication, the filter relies on JAZNUserManager to retrieve the authenticated user and the corresponding principal object.
For an SSL client certificate, the filter performs the following:
1. Retrieves SSL client certificate from the request object, if it is available
2. Instantiates java.security.cert.X509Certificate object x509cert based on the client certificate
3. Creates an array of type java.security.cert.X509Certificate and adds objects to the array
4. Sets the attribute on the request object ("java.security.cert .X509Certificate",x509cert)
5. Gets the SSL principal name by invoking oracle.security.jazn. util.CertHash.getHash(x509cert)
6. Gets the SSL principal object sslPrincipal, a RealmPrincipal object, from the default realm using the JAAS Provider API

The filter element constructs an oracle.security.jazn.oc4j. JAZNServletRequest request for the HTTP request.

(End of Optional Section)

Authorization begins with a call to Subject.doAs().

Authorization in the J2EE Environment

Authorization is the process of granting the permissions and privileges entitled to the user.

Once the user is authenticated, the JAZNUserManager invokes the target servlet within a Subject.doAs() block to enable JAAS-based authorization in the target servlets.

Authorization is achieved through the following:

JAZNUserManager
Methods based on the Java2 Security Model:
- Servlet.service() in the servlet
- Subject.doAs()in the client
- SecurityManager.checkPermission()in the server

Testing and Executing the J2EE Application

After completing all configuration tasks, follow these steps to test or execute the JAAS Provider within OC4J. These steps assume the following:

The current directory is $ORACLE_HOME/j2ee/home
mod_oc4j is configured

To build and configure your application, a sample application, callerInfo, has been provided. Chapter 5, "Quick Start JAAS Provider Demo" describes how to quickly run this sample application. This chapter elaborates on the information in Chapter 5 and discusses available configuration options.

See Also:

Chapter 7 of the Oracle9i Application Server Security Guide for detailed configuration information

Setting Up

You must perform the following tasks to test and run a J2EE application:

Task 1: Install Ant (Optional)

You can install Ant, an XML-based build tool (similar to make), from Apache's Jakarta Project or plan to use jar directly. If you do not have Ant installed, you can download it from:

http://jakarta.apache.org/ant/index.html

Once you have installed Ant, and before running it, you must configure files as described in the next section, "Task 2: Modify OC4J Files".

Task 2: Modify OC4J Files

In order to run a servlet, you need to modify several OC4J Files.

Modifying OC4J Files Where OC4J is Not Running

Modify the OC4J server.xml file in $ORACLE_HOME/j2ee/home/config/ by adding the following line:

<application name="myApp1" path="../jazn/demo/myApp1/  

   myApp1.ear" />

For the callerInfo demo, the line is as follows:

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

   callerInfo.ear" />

Modify the OC4J default-web-site.xml file in $ORACLE_HOME/j2ee/home/ config/ by adding the following line:
```
<web-app application="myApp1" name="myApp1-web" root="/jazn" />
```
For the callerInfo demo, the line is as follows:
```
<web-app application="callerInfo" name="callerInfo-web" root="/jazn" />
```

Deploying an Application When the OC4J Server is Running

If the OC4J server is already up and running, you can perform the following steps to deploy your application.

java -jar $J2EE_HOME/admin.jar 
ormi://oc4j_host:rmi_port admin_user admin_password 
-deploy -file $J2EE_HOME/jazn/demo/myApp1/myApp1.ear -deploymentName callerInfo



java -jar $J2EE_HOME/admin.jar 
ormi://oc4j_host:rmi_port admin_user admin_password
-bindWebApp myApp1 myApp1-web default-web-site /jazn

For the callerInfo demo, enter the following:

java -jar $J2EE_HOME/admin.jar 
ormi://oc4j_host:rmi_port admin_user admin_password
-file $J2EE_HOME/jazn/demo/callerInfo/callerInfo.ear 
-deploymentName callerInfo



java -jar $J2EE_HOME/admin.jar 
ormi://oc4j_host:rmi_port admin_user admin_password
-bindWebApp callerInfo callerInfo-web default-web-site /jazn

See Also:

Oracle9iAS Containers for J2EE User's Guide for further information on OC4J configuration
Chapter 7 of the Oracle9i Application Server Security Guide for further information on JAAS Provider configuration

Task 3: Change Default Configurations

The default realm is set to sample_subrealm. To change to another realm, you must modify the jazn element of the OC4J orion-application.xml (in the directory jazn/demo/callerinfo/etc/) as follows:

Using XML-Based Realms (Default)

Change the realm, default-realm, from the default value, sample_subrealm, to any realm that you have created.
Change location from the default value, jazn-data.xml, to any properly configured data file that you have created. Conversely, you can also use jazn-data.xml as a template for your own file.

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

Using LDAP-Based Realms

Since the installation defaults to the XML-based provider type, you need to modify certain files if you are using the LDAP provider type environment.

Note:

You must use the Oracle9iAS Infrastructure installation type if you use the LDAP provider type environment.

In the orion-application.xml file in directory jazn/demo/ callerinfo/etc/, make the following changes:

Change the JAAS Provider type to LDAP.
Enter your LDAP location URL (for example, ldap://myoid.us.oracle.com)

Using SSL and SSO Integration

If you are using SSO or SSL integration, make the following addition to the mod_oc4j.conf file to add redirection information.

Oc4jMount /jazn/* ajp13_worker 
Oc4jMount /jazn ajp13_worker

Assuming that ajp13_worker is a defined worker in the oc4j.conf file, this directs any request matching /jazn/* to be handled by ajp13_worker. Any request matching /jazn/ is to be handled by ajp13_worker.

Using SSO

If you are using SSO integration, make the following change in the orion-web.xml:

Set the auth-method in the jazn-web-app element file to "SSO"as in the following example:


<jazn-web-app 
    auth-method="SSO" (optional - default to null) 
    runas-mode="false" (optional - default to false) 
    doasprivileged-mode="true" (optional - default to true) 
/>

Task 4: Build the Directory

To build the directory, either use jar or Ant to create a new directory (build) containing the .EAR and .WAR files for your application.

To build the directory using Ant:

Open a command line shell.
Go to the jazn/myApp1/myApp1 directory

For the callerInfo demo, go to jazn/demo/callerInfo directory,
Type: ant

Starting an Application

This is the first real JAAS provider test.

To start your application:

Start the Oracle HTTP Server listener as follows:
- for mod_osso (SSO environments), enter apachectl start
- for mod_ossl (SSL environments) apachectl startssl
  
  Note:
  Skip this step if you are using Basic Authentication.
Start OC4J with the JAAS provider by entering the following:
```
java -jar oc4j.jar 
```
Or start OC4J with the JAAS provider in secure mode (assuming that you have configured your java2.policy) with the SecurityManager:
```
java -Djava.security.manager. 
-Djava.security.policy=/jazn/config/java2.policy -jar oc4j.jar 
```
Run the servlet from a Web browser using:
```
http://hostname:1234/myApp1/myApp1
```
Or to run the sample application, use:
```
http://hostname:1234/jazn/callerInfo 
```
where 1234 is the port configured for your HTTP listener.

See Also:
Oracle9iAS Containers for J2EE User's Guide

Sample J2EE Application

This sections shows the sample J2EE application, callerInfo, which you can run using the commands described in "Testing and Executing the J2EE Application" or in Chapter 5, "Quick Start JAAS Provider Demo".

Sample J2EE Application callerInfo

package oracle.security.jazn.samples.http;

import java.io.IOException;
import java.util.Date;
import java.util.Properties;
import javax.naming.*;
import javax.servlet.*;
import javax.servlet.http.*;

/**
 * A simple demo that exercises the Servlet security APIs. 
 * 
 * @author rkng
 */
public class CallerInfo extends HttpServlet {

    public CallerInfo() 
    {
	super();
    }
    public void init(ServletConfig config) 
	throws ServletException 
    {
	super.init(config);
    }
    public void doGet(HttpServletRequest request, HttpServletResponse response)
	throws ServletException, IOException 
    {
	ServletOutputStream out = response.getOutputStream();

	response.setContentType("text/html");
	out.println("<HTML><BODY bgcolor=\"#FFFFFF\">");
	out.println("Time stamp: " + new Date().toString());
	out.println("request.getRemoteUser = " + request.getRemoteUser() + "<br>");
	out.println("request.isUserInRole('FOO') = " + request.isUserInRole("FOO") + 
"<br>");
	out.println("request.isUserInRole('ar_manager') = " + 
request.isUserInRole("ar_manager") + "<br>");
	out.println("request.isUserInRole('ar_developer') = " + 
request.isUserInRole("ar_developer") + "<br>");
	out.println("request.getUserPrincipal = " + request.getUserPrincipal() + 
"<br>"); 
	out.println("</BODY>");
	out.println("</HTML>");
    }
}

Discussion of the J2EE Sample Application Code

When the call to callerInfo is successful, 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])

9 Developing Secure J2EE Applications

Developing Secure J2EE Applications Overview

Authentication in the J2EE Environment

Running with the Permissions and Roles Associated with an Authenticated Identity (Optional)

Interception of Servlet Invocation

Retrieving Authentication Information

(Optional if the Filter Element Has Been Set)

(End of Optional Section)

Authorization in the J2EE Environment

Testing and Executing the J2EE Application

Setting Up

Task 1: Install Ant (Optional)

Task 2: Modify OC4J Files

Modifying OC4J Files Where OC4J is Not Running

Deploying an Application When the OC4J Server is Running

Task 3: Change Default Configurations

Using XML-Based Realms (Default)

Using LDAP-Based Realms

Using SSL and SSO Integration

Using SSO

Task 4: Build the Directory

Starting an Application

Sample J2EE Application

Sample J2EE Application callerInfo

Discussion of the J2EE Sample Application Code

9
Developing Secure J2EE Applications