How-To Configure and Use
Proxy-authentication with Oracle Container for Java EE 11 Technology Preview Data
Sources
First Publication: 20-Jul-05
Last Update: 29-Apr-07
Author: Frances Zhao
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.
Oracle Container for Java EE 11 Technology Preview 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:
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 Java EE
Technology Preview 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.
More about this application
and related documentations
Note that the main purpose of this demo is to illustrate some of the key steps
and APIs involved in configuring and using proxy-authentication, like database
user setup, connect-through and role grants, openProxySession(), etc. It does
not cover all the possible proxy-authentication configuration scenarios
supported by Oracle database and Oracle JDBC. Refer to Oracle Database Security
Guide 10g and Oracle JDBC Developer's Guide and Reference 10g for more detailed
explanation on this subject.
How to Run the
Application?
The following instructions are for running this demonstration on a
standalone instance of Oracle Container for Java EE 11 Technology Preview.
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 Technology Preview instance as
follows:
o
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.
o
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:
Running the
Application
In a browser window, browse to:
If the website hostname or port number are different, then use those values
instead.
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.
Summary
In this document, you should have:
- Learned how to use native data
source with Oracle JDBC API for proxy-authentication
Bookmark
