How-To Configure and Use Proxy-authentication with OC4J 10g (10.1.3) Data Sources

First Publication: 20-Jul-05
Last Update: 16-Jan-06
Author: Frances Zhao

Introduction
What are the Prerequisites?
How to Build the Application?
How to Run the Application?
Summary

Introduction

Oracle database supports proxy-authentication which allows a client user to connect to the database through an application server, as a proxy user. The client user authenticates itself with the application server, while the application server authenticates itself as the proxy user with the Oracle database. The client user's name is maintained all the way to the database on any proxy connection opened this way.

OC4J 10g (10.1.3) supports this with Oracle JDBC native data sources. This demo illustrates some of the key steps in configuring and using proxy-authentication with an Oracle JDBC native data source, and tests the proxy connections to the configured Oracle database in JSP code.

What are the Prerequisites?

What you should know?

You should be familiar with these technologies: DataSource, JSP, JDBC;
Link to other OC4J Howto's on OTN

What are the Software Requirements?

This demo requires that the following sofware components are installed and configured correctly:

Oracle Containers for J2EE 10g (10.1.3), standalone version, with a web site configured (example default-web-site)
Oracle Database 10g Release 1 (10.1.0.3)
Sun's JDK 1.4.1 or above, available from here
Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.

What are the Notations?

%ORACLE_HOME% - The directory where you installed OC4J.
%JAVA_HOME% - The directory where your JDK is installed
%HOWTO_HOME% - The directory where this demo is unzipped

How to Build the Application?

Defining a Native Data Source

First, we need to define a native data source that uses Oracle JDBC DataSource implementations. Like in previous OC4J versions, OC4J 10.1.3 data sources are still defined in an appliction's data-sources.xml file. The default data source configuration file for all applications is still located at %ORACLE_HOME%/j2ee/home/config/data-sources.xml.

To define data sources you can edit the data sources configuration file directly or use Enterprise Manager to create, delete, and modify data sources. This How-to uses the first approach only.

Here is the native data source definition, which can be found in the application-embedded data-sources.xml under %HOWTO_HOME%/etc.

<native-data-source
  name="OracleNativeDSForProxyDemo"
  jndi-name="jdbc/OracleNativeDSForProxyDemo"
  description="Native DataSource For Proxy Demo"
  data-source-class="oracle.jdbc.pool.OracleDataSource"
  user="scott"
  password="tiger"
  url="jdbc:oracle:thin:@//dbhost:1521/dbservicename">
</native-data-source>

Note that the data-source-class is an Oracle JDBC implementation of javax.sql.DataSource. The user and password attributes define the default user and password, which are not used in this demo.

Configuring the Oracle Database

The next step is to configure the Oracle database to set up the users, database roles, and the proxy mapping. You need to run the provided SQL script %HOWTO_HOME%/etc/setup.sql in SQLPlus with a Oracle DBA account.

Exexute the following command in SQLPlus:

SQL> @%HOWTO_HOME%/etc/setup.sql systempassword

There are several groups of operations in the script:

Create two users: testusr and proxyusr. User testusr has a table testusr_account.
Create three DB roles: role1, role2, and role3. All the roles are for accessing a table system.account.
User testusr by default are granted the above three roles.
Allow testusr to connect through the proxy user proxyusr.

Proxy-authentication

Clicking the associated test button would invoke a JSP that tests proxy connections obtained from the configured native data source. A new page would show the test logs, or if an exception has occurred. There would be a back link on the new page that brings you back to the beginning page.

Here are some important operations in the JSP code relevant to proxy-authentication:

Open a connection to the database using the proxy user proxyusr.
Check if the connection is a proxy connection with Oracle JDBC API isProxySession() in oracle.jdbc.OracleConnection.
Open a proxy connection that lets testusr connect through proxyusr, using Oracle JDBC API openProxySession(...) also in oracle.jdbc.OracleConnection. On this proxy connection, we specify that only two DB roles are allowed: role1 and role2, among the three DB roles testusr has been granted by default.
Check again if the connection is a proxy connection and user name.
Test DB operations related to the three DB roles and see if the specified proxy roles are observed -- only the deletion operation associated with role3 should fail.
Close the proxy connection using Oracle JDBC API close(OracleConnection.PROXY_SESSION), which does not close the original connection opened with proxyusr.
Check again if the connection is a proxy connection and the user name.
Close the original connection with proxyusr.

How to Run the Application?

The following instructions are for running this demonstration on a standalone instance of Oracle Containers for J2EE 10g (10.1.3).

Examining the How to Distribution

build - temporary directory created during the build
log - temporary directory holding build/deploy logs
etc - all necessary files to package the application
lib - holds the application archives that could be deployed (e.g., ear, war, rar, jar files)
doc - the How-to document and Javadoc's

javadoc - the javadoc of the different source files
how-to-ds-proxy.html - this How-to page

src - the source of the demo
- web - contains HTML pages and the JSP code

Setting Up the Application

Environment Configuration

Please check to make sure that the following properties are configured correctly in the ant-oracle.properties file located in the root of the sample's distribution (NOTE: Some of these properties will default to the values of corresponding environment variables as noted below. If you have these variables setup in your environment you may not have to alter the values in the file). If necessary, modify these variable to the proper values for you environment:

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".

In addition, please make sure that the ant command associated with the OC4J ant distribution is in your execution path (%ORACLE_HOME%/ant/bin).

Configuring the Environment for a Managed OracleAS Instance

If you are running a managed version of the Oracle Application Server 10g, you are using OPMN, you must change the following values to match your configuration:

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.

Database Configuration

This demo requires an Oracle database and listener to be running. Note down the hostname, port number, and the service name used -- you need to modify the %HOWTO_HOME%/etc/data-sources.xml with these information.

Starting the OC4J Instance

Start an OracleAS 10g (10.1.3) instance as follows:

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

Build the Application

Make sure that the ant command associated with the OC4J ant distribution is in your execution path (%ORACLE_HOME%/ant/bin).

In the top-level %HOWTO_HOME% directory, type the command:

You should now have newly created ds_proxy_demo.ear in your %HOWTO_HOME%/dist directory.

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

Deploy and Bind the Application

You can also deploy and bind the application separately by using the following command. Make sure the %ORACLE_HOME% environment variable is defined. In the top-level %HOWTO_HOME% directory, type the command:

ant bind-web-app

Running the Application

In a browser window, browse to:

http://localhost:8888/ds_proxy_demo/

If the website hostname or port number are different, then use those values instead.

Summary

In this document, you should have:

Learned how to use native data source with Oracle JDBC API for proxy-authentication