Oracle HTTP Server Administration Guide Release 2 (9.0.2) Part Number A92173-02 |
|
This appendix explains how the Oracle9iAS Proxy Plug-in enables you to use Oracle9iAS components in conjunction with a third-party HTTP listener. The Oracle9iAS Proxy Plug-in works with the Netscape iPlanet Web Server Enterprise Edition (version 4.1 and 6.0) on UNIX and Windows NT systems, or the Microsoft Internet Information Server (IIS) (version 4.0 or 5.0) on Windows systems, to send requests to Oracle9iAS.
This appendix contains the following topics:
The Oracle9iAS Proxy Plug-in is a reverse HTTP proxy. It forwards incoming HTTP requests to an Oracle9iAS instance as shown in Figure A-1.
This proxy logic is provided as a plug-in, a shared library that is loaded by the third-party HTTP listeners. The plug-in uses APIs provided with the third-party listeners to directly handle HTTP requests, in much the same way that modules (mods) are plugged into the Oracle HTTP Server.
The Oracle HTTP Server can mimic the address and port that the third-party listener is using. That is, when sending a request to the Oracle HTTP Server, the proxy can be configured to send a different Host: HTTP header than the actual hostname and port that the request is being sent to, so that downstream applications are shielded from the introduction of the reverse proxy.
The plug-in is distributed on the Integration CD, and available on OTN at
There is no installation procedure for the proxy plug-in. After downloading the plug-in, you need only place the configuration files and shared library in directories that the third-party listener can access.
The plug-in consists of a single shared library, oracle_proxy.so
. To install the plug-in into the listener, simply place the library in a directory to which the listener has read and execute privileges.
The plug-in consists of a single dll, oracle_proxy.dll
for IIS, or oracle_proxy_nes.dll
for Netscape. To install this plug-in, copy the .dll to a directory the listener can access.
There are three configuration files for the Oracle9iAS Proxy Plug-in, one to control the proxy functionality and two to control the single sign-on functionality. The presence of the configuration file in the web server's file system makes the functionality active.
You may also need to modify configuration files specific to the third-party listener to install the plugin on to these listeners. Configuration instructions for those files are not included here.
This file must reside in a directory that is readable by the third-party listener. Described in detail in Table A-1, this file contains:
Table A-1 Proxy Configuration File Parameters
In the proxy configuration file, you define which servers and URLs to proxy to the plugin.
oproxy.serverlist=ias1,ias2
oproxy.ias1.hostname=myhost.us.oracle.com oproxy.ias1.port=7777 oproxy.ias1.alias=www.oracle.com
The hostname must be provided. If you do not specify the port, 80 is assigned. If an alias value is not given, the combination of the hostname and port given are used. The alias enables the back end server to receive requests that have an HTTP Host: header that looks exactly like the one the client delivers to the third-party listener.
oproxy.ias1.urlrule=/*
maps all incoming requests to be proxied to the web server on the server ias1. These rules can be of three forms, exact URL, context match, or extension-based. An exact match maps exactly one URL to a server, for example:
oproxy.ias1.urlrule=/my/path/index.html
maps only accesses to /my/path/index.html for proxying. An example of a context rule is:
oproxy.ias1.urlrule=/app1/*
which maps any URL beginning with /app1.
An extension-based rule, such as:
oproxy.ias1.urlrule=/*.jsp
maps any URL ending with .jsp.
All requests sent to a mapped URL are proxied via HTTP/1.1 to the specified server.
This section provides proxy plug-in configuration instructions for the Netscape iPlanet Enterprise Server listener on UNIX and Windows NT systems.
magnus.conf
file (version 6) or obj.conf
(version 4) in the Netscape listener /config
directory.
For UNIX:
Init fn="load-modules" shlib="/path/oracle_proxy.so" funcs=op_init,op_ objecttype,op_service
For Windows NT:
Init fn="load-modules" shlib="/path/oracle_proxy_nes.dll" funcs=op_init,op_ objecttype,op_service
where /path/
is the path to the shared library for the plug-in. This line tells the listener where the proxy shared library is, and which functions are exposed by this library.
Init fn="op_init" server_defs="/path/config/servers" log_ file="/path/logs/oproxy.log" log_level=error
where /path/
is the path to the server definition and log files. The server definition file contains all of the configuration information for the servers that the proxy plug-in can communicate with. A log file and log level to log messages from the plug-in can also be specified (optional).
obj.conf
file, before all other lines beginning with the word ObjectType:
ObjectType fn=op_objecttype
Service type="oracle/proxy" fn="op_service"
This section provides proxy plug-in configuration instructions for the IIS listener on Windows systems. To configure the plug-in:
HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\IIS Proxy Adapter
log_file
and log_level
:
oracle_proxy.dll
. Name the directory oproxy
and give it execute access.
oracle_proxy.dll
as a filter in your IIS web site. The name of the filter should be oproxy
and its executable must point to the directory containing oracle_proxy.dll
(for example, d:\proxy\oracle_proxy.dll
).
In addition to the proxy functionality, the proxy plug-in includes the same functionality provided by mod_osso to the Oracle HTTP Server to support single sign-on. With single sign-on, users need authenticate only once to the web server; thereafter, the user name and password are relayed invisibly to Oracle9iAS applications.
If you want to use single sign-on functionality, you must first install the database Required Support Files libraries (v9.0.1.3) in order to get the necessary security libraries.
Oracle Single Sign-On (OSSO) can be used with iPlanet and IIS web servers. OSSO implements the basic functionalities of mod_osso, the single sign-on module for the Oracle HTTP Server. Features not implemented in the current release include:
Both iPlanet and IIS OSSO plug-ins use the same formatted osso_plugin.conf
file. You must create this file and put it in a location that the listener can access.
This section contains examples of entries from the OSSO configuration file osso_plugin.conf
.
LoginServerFile = "/path/config/sso_conf" HardTimeOut = 1000
In the LoginServerFile directive above, path is the iPlanet server root directory.
<OSSO /private/hello.html> IpCheck = true; HardTimeOut = 10000 </OSSO> <OSSO /private1/*> IpCheck = false </OSSO> <OSSO /private2/*.jsp> IpCheck = false HardTimeOut = 100 </OSSO>
This section describes the OSSO directives.
Specifies the location of the Single Sign-On Server configuration file that provides all the information about the Single Sign-On Server, such as version, cipher key, etc. This Single Sign-On Server configuration file is obfuscated. See "Obtaining an Obfuscated Single Sign-On Server Configuration File".
Currently, only one Single Sign-On Server is allowed for all the protected resources, so you cannot use this directive on a per-resource basis. You must provide one and only one Single Sign-On Server configuration file.
Specifies whether OSSO should check the IP address of each request when it examines the cookie. Valid values are true and false. Setting IpCheck to true prevents cookies being stolen.
Example:
IpCheck = true
Specifies the lifetime (in seconds) of the cookie for the protected resource. After this amount of time, the user will have to authenticate again.
Example:
HardTimeout = 100
You can specify URIs to protect in several ways:
This option identifies a particular file as a protected resource, for example:
/examples/Hello.html
This option identifies a directory as a protected resource, for example:
/examples/*
This option identifies files with a certain extension in a particular directory as a protected resource, for example:
/examples/*.jsp
This section provides instructions on configuring the iPlanet Enterprise Server listener to use the OSSO plug-in.
obj.conf
file in the Netscape listener /config directory.
Init fn="load-modules" shlib="/path/oracle_proxy.so" funcs="osso_ init,oracle_single_sign_on,osso_redirect,osso_success_service"
where /path/ is the path to the shared library for the plug-in. This line tells the listener where the proxy shared library is, and which functions are exposed by this library.
Init fn="osso_init" osso_properties="/path/config/osso_plugin.conf" log_ file="/path/debug.log" log_level=error
where /path/ is the iPlanet server root directory. This line contains the location of an OSSO definition file that contains all of the configuration information for the servers that the OSSO plug-in will use. This line can also specify a log file and log level to log messages from the plug-in (optional).
obj.conf
file, before all other lines:
AuthTrans fn="oracle_single_sign_on"
Service type="oracle/sso_redirect" fn="osso_redirect_service"
<Object ppath="/path/osso_login_success"> Service fn="osso_success_service" </Object>
where path is the path of your document root (e.g., home/me/iplanet/docs/). This should be the same path as named in
NameTrans fn=document-root root=/.../iplanet/docs
For version 6.0, the same shared library can be used as with version 4.1. The configuration is virtually the same, but the configuration files for Netscape have changed slightly in version 6.0. In this version, the two lines beginning with Init
that need to be added must be added at the end of the magnus.conf
file rather than to the obj.conf
file. The other two lines that should be added to obj.conf remain the same.
This section provides instructions on configuring the IIS Listener to use the OSSO plug-in. The plugin consists of a single dll, oracle_osso.dll
. To install the plugin, copy the .dll to the computer on which IIS resides and perform the following steps:
HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\IIS OSSO Adapter
.
cfg_file
and a value pointing to the location of your definition file.
oracle_osso.dll
. Name the directory osso
and give it execute access.
oracle_osso.dll
as a filter in your IIS web site. The name of the filter should be osso
and its executable must point to the directory containing oracle_osso.dll
(for example, d:\osso\oracle_osso.dll
).
Follow these steps to obtain an obfuscated Single Sign-On Server configuration file for the iPlanet server.
$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar \ -oracle_home_path $ORACLE_HOME \ -host login server database hostname \ -port login server database port \ -sid login server database sid \ -site_name name of iplanet server \ -success_url http://iplanet server hostname:port/osso login success url \ -cancel_url http://iplanet server hostname:port/cancel url \ -logout_url http://iplanet server hostname:port/osso logout success url \ -home_url http://iplanet server hostname:port/home url \ [-admin_id administrator user id] \ [-admin_info administrator information] \ -config_mod_osso TRUE \ -virtualhost \ -u userid \ -sso_server_version v1.2 \ -text_file $ORACLE_HOME/cleartext sso configuration file \ -config_file $ORACLE_HOME/Apache/Apache/conf/osso/sso_conf \
sso_conf
file to the iPlanet root directory
osso_plugin.conf
file specifies the generated sso_conf
file.
Table A-2 lists the command arguments for the SSO Registrar.
This section highlights development and usage practices to consider when developing an application that will run behind the Oracle9iAS Proxy Plug-in. Some of these also have relevance when enabling an application to run behind Oracle9iAS Web Cache.
This is usually only relevant if an application has a module that plugs directly into the Oracle HTTP Server. Specifically, look for dependencies on obtaining information about the client based on the connection made to the Oracle HTTP Server (such as using the SSL certificate for authentication). Currently, SSL is not supported, so even if the client uses SSL to connect to the third-party listener, an unencrypted HTTP message will be sent from the third-party listener to the Oracle HTTP Server. This means that client certificates will not be available to components that reside behind the plug-in. The environment variable REMOTE_ADDR has been specifically preserved when Oracle9iAS Proxy Plug-in and Web Cache are used, but other client information may, in practice, represent the machine on which the proxy resides rather than the actual client host. These behaviors must be discovered and eliminated in cases where the Oracle HTTP Server is not the external listener for Oracle9iAS.
This includes static HTML pages, dynamic pages generated by servlets, JSPs, PL/SQL, etc. Examine all code that obtains the server name of the Oracle HTTP Server to ensure that it is not embedding the server name into pages that are sent back to the client. To test for this behavior, use a "spider" application that traverses all links in a web site. Open source tools with this functionality are available.
If you have an application that uses browser-based code, ensure that the code does not contain the hostname and port of the Oracle HTTP Server that actually delivers the content. Instead, it must have the actual client-accessible address used by the third-party listener.
In order to successfully proxy all requests for an application, the Oracle9iAS Proxy Plug-in must have a complete description of the URL space for that application. Each Oracle9iAS application must describe the set of rules necessary to configure the plug-in for that application. This set of rules must include all URLs that the application could generate. If an application generates a URL that is not described by the proxy urlrule parameters, the request will be served by the third-party HTTP listener, and a "document not found" error may occur (or, worse, a document other then the intended document may be delivered to the client).
Developers of applications that use common top level directories (such as a reliance on mapping /images) should be prepared to:
This section describes common problems and possible solutions.
magnus.conf
file and ObjectType and Service lines are added to the obj.conf
file.
If you try to change the ports or turn on security (for SSL), the server may return the error message "Unable to parse magnus.conf".
If you are using a context-based urlrule parameter to retrieve a file that is known to exist, and the listener returns "Not Found", you probably need to set "stripcontext=true". See the oproxy.servername.urlrule parameter, stripcontext option, in the table "Proxy Configuration File Parameters".
The IIS and iPlanet servers auto-complete URLs differently. Requests of "http://serverName", "http://serviceman/", and "http://serviceman/index.html" do not necessarily return the same results on different platforms. The oproxy.servername.urlrule parameter (described in the table "Proxy Configuration File Parameters") can be used to work around this problem.
The default iPlanet configuration maps any URL requests to "/servlet" to its own servlet handler. You must edit the server definition file, or change the iPlanet configuration to correct this.
If you use an exact urlrule parameter (e.g. "urlrule=/*.html") in the server definition file (or a similar scenario), the server will retrieve the specified page, but all other links are forbidden to the user (including inline images in the page). (If you use an exact urlrule with stripcontext=true, a "Server Error" is returned.)
Clear the memory cache in your client browser. Earlier versions of Netscape and IE cache pages even when told to retrieve the page every time, when no memory is allocated for caching (you may need to restart the browser to get this behavior to work). If you see a page you're not expecting, try refreshing or reloading the page.
The REMOTE_ADDR field usually contains the IP address of the client machine. In some URL request cases, if there is a proxy server in the environment, the field may contain the IP address of the proxy server.
If the back-end server returns a redirect to the entry point of the network, do one of the following:
Set the following directives in the httpd.conf
file:
UseCanonicalName On ServerName name of listener computer Port port of listener computer
Set the following directives in the httpd.conf
file:
UseCanonicalName port Port port of Listener computer
Edit the proxy plug-in server configuration file:
oproxy.serverName.alias=name of listener computer:port of istener computer
The proxy plug-in supports SSL connections made between the client and the proxy computer, but does not support SSL connections between the proxy and the back-end server. To implement the latter, set up the listener to receive SSL connections and start the back-end server in non-SSL mode. No changes to the proxy configuration are needed.
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|