Skip Headers

Oracle HTTP Server Administration Guide
Release 2 (9.0.2)

Part Number A92173-02
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

A
Using the Oracle9iAS Proxy Plug-in

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:

Overview

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.

Figure A-1 Oracle9iAS Proxy Plug-in

Text description of proxya.gif follows.
Text description of the illustration proxya.gif

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.

Downloading the Plug-in

The plug-in is distributed on the Integration CD, and available on OTN at

http://otn.oracle.com

Installing the Plug-in

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.

Installing the Plug-in on UNIX Systems

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.

Installing the Plug-in on Windows Systems

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.

Configuring the Plug-in

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.

Proxy Configuration File

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:

Defining Proxy Plug-in Behavior

In the proxy configuration file, you define which servers and URLs to proxy to the plugin.

  1. In the first line of the file, specify the list of all the servers that can be used by the plugins. For example:

    oproxy.serverlist=ias1,ias2
    
  2. Set the relevant properties (hostname, port, and server alias) for each server. For example:

    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.

  3. Set the urlrule parameter to specify redirection between servers. For example, the rule:

    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.

Configuring the iPlanet Listener to Use the Proxy Plug-in

This section provides proxy plug-in configuration instructions for the Netscape iPlanet Enterprise Server listener on UNIX and Windows NT systems.



Notes:

If you are configuring the iPlanet listener on Windows NT, use forward slashes (/) in all paths.

The default configuration files for Netscape iPlanet route all incoming requests for the URI /servlet to the Netscape servlet handler. The Oracle Proxy Plug-in does not override settings Netscape configuration settings. You must ensure that the URL mappings to the Oracle9iAS Proxy Plug-in are distinct from the URL mappings to the Netscape servlet engine.  


  1. Open the magnus.conf file (version 6) or obj.conf (version 4) in the Netscape listener /config directory.

  2. Add the load-modules line:

    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.

  3. Add the configuration parameters line:

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

  4. Add the following line to the <Object name=default> section of the obj.conf file, before all other lines beginning with the word ObjectType:

    ObjectType fn=op_objecttype
    
  5. Add the following line before all other lines that begin with the word Service:

    Service type="oracle/proxy" fn="op_service"
    
  6. Start the listener using the GUI or the shell script.

Configuring the IIS Listener to Use the Proxy Plug-in

This section provides proxy plug-in configuration instructions for the IIS listener on Windows systems. To configure the plug-in:

  1. Create a new registry key named HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\IIS Proxy Adapter

  2. Specify the location of your server definition file by adding a string value with the name server_defs, and a value pointing to the location of your definition file.

  3. (Optional) Specify log_file and log_level:

    1. Add a string value with the name log_file and the desired location of the log file (for example, d:\proxy\proxy.log)

    2. Add a string value with the name log_level and a value for the desired log level. Valid values are debug, inform, error and emerg.

  4. Using the IIS management console, add a new virtual directory to your IIS web site with the same physical path as that of oracle_proxy.dll. Name the directory oproxy and give it execute access.

  5. Using the IIS management console, add 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).

  6. Restart IIS (stop and then start the IIS Server), ensuring that the oproxy filter is marked with a green upward arrow.


    Note:

    To restart IIS, you must stop all of the IIS services through the control panel, or restart the computer. This is the only way to ensure that the DLL is reloaded (restarting IIS through the management console is not sufficient).  


Using Single-Sign On with the Plug-in

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.

Configuring Single Sign-On Plug-Ins

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.

OSSO Configuration File Examples

This section contains examples of entries from the OSSO configuration file osso_plugin.conf.


Note:

The osso_plugin.conf file must be referenced by the obj.conf file, configuration parameters line, as follows:

Init fn="osso_init" osso_properties="/path/config/osso_
plugin.conf" log_file="/path/debug.log" log_level=error

This line can also specify a log file and log level to log messages from the plug-in (optional).  


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> 

OSSO directives

This section describes the OSSO directives.

LoginServerFile

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.

IpCheck

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  


Note:

Set IpCheck to false if you have a proxy server or firewall between your iPlanet server and your clients' browser.  


HardTimeout

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

Specifying Protected URIs

You can specify URIs to protect in several ways:

Exact Context

This option identifies a particular file as a protected resource, for example:

/examples/Hello.html
Context Based

This option identifies a directory as a protected resource, for example:

/examples/*
Context and Suffix

This option identifies files with a certain extension in a particular directory as a protected resource, for example:

/examples/*.jsp 

Configuring the iPlanet Listener for Single Sign-on

This section provides instructions on configuring the iPlanet Enterprise Server listener to use the OSSO plug-in.

  1. Open the obj.conf file in the Netscape listener /config directory.

  2. Add the load-modules line:

    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.

  3. Add the configuration parameters line:

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

  4. Add the following line to the <Object name=default> section of the obj.conf file, before all other lines:

    AuthTrans fn="oracle_single_sign_on"
    
  5. Add the following line to the Object name=default section before all other lines that begin with the word Service:

    Service type="oracle/sso_redirect" fn="osso_redirect_service"
    
  6. Add the following lines:

    <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
    
  7. Change the LD_LIBRARY_PATH variable in your start script to include the location of libclntsh.so.

  8. Start the listener using the GUI or the shell script.

Usage Notes for Netscape/iPlanet Enterprise Server Version 6.0

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.

Configuring the IIS Listener for Single Sign-On

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:

  1. Edit your registry to create a new registry key named HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\IIS OSSO Adapter.

  2. Specify the location of your osso configuration file by adding a string value with the name cfg_file and a value pointing to the location of your definition file.

  3. (Optional) Specify a log_file and log_level:

    1. Add a string value with the name log_file and the desired location of the log file (for example, d:\osso\osso.log)

    2. Add a string value with the name log_level and a value for the desired log level. Valid values are debug, inform, error and emerg.

  4. Using the IIS management console, add a new virtual directory to your IIS web site with the same physical path as that of oracle_osso.dll. Name the directory osso and give it execute access.

  5. Using the IIS management console, add 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).

  6. Restart IIS (stop and then start the IIS Server), ensuring that the oproxy filter is marked with a green up-pointing arrow.


    Note:

    To restart IIS, you must stop all of the IIS services through the control panel, or restart the computer. This is the only way to ensure that the DLL is reloaded (restarting IIS through the management console is not sufficient).  


Obtaining an Obfuscated Single Sign-On Server Configuration File

Follow these steps to obtain an obfuscated Single Sign-On Server configuration file for the iPlanet server.

  1. Install the Oracle9iAS core components on the computer on which the iPlanet server resides.

  2. Register the iPlanet server with a Single Sign-On server using the command below. If entered line by line on a terminal, each line must end with the backslash character. Command arguments are shown in italics; you must supply valid values. Arguments are described in Table A-2, "SSO Registrar Command Arguments".

    $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 \
    
  3. Copy the generated sso_conf file to the iPlanet root directory

  4. Ensure that the LoginServerFile directive in the osso_plugin.conf file specifies the generated sso_conf file.

SSO Registrar Command Arguments

Table A-2 lists the command arguments for the SSO Registrar.

Table A-2 SSO Registrar Command Arguments
Argument  Description 

-oracle_home_path  

Absolute path to the Oracle home.  

-site_name 

Name of the site, typically expressed as the contiguous string host:port.  

-success_url 

URL to the routine responsible for establishing the partner application session and session cookies. The URL is:

http://iplanet server hostname:port/osso_login_success 

-cancel_url 

URL to which the SSO server redirects when the user cancels authentication.  

-admin_id 

User name of the mod_osso administrator. This argument is optional.  

-admin_info 

Information associated with the administrator's user name, such as e-mail address. This argument is optional.  

-config_ mod_osso 

If set to TRUE, this parameter indicates that the application being registered is mod_osso. This argument is necessary to generate the sso_conf file.  

-u 

Specifies the user name under which the Oracle HTTP Server was started. In the case of the iPlanet server, it is the name of the user under which the iPlanet server will run (specified during iPlanet server configuration).

Note the difference between the -u value specified for the Oracle HTTP Server and that specified for the iPlanet server:

  • For the Oracle HTTP Server, -u is the user that started the server.

  • For the iPlanet server, -u is the user under which the server answers client requests.

You can specify -u root for the Oracle HTTP Server. However, Oracle Corporation recommends against specifying -u root when configuring an iPlanet server (and, by implication, not to use -u root when registering the iPlanet server with the SSO server.

This argument is optional. The default is the user name under which the SSORegistrar tool is run. In this case, the Oracle HTTP Server must be started under that user name, and the iPlanet server must be configured to answer client requests under that name.  

-sso_server_version 

Must be set to v1.2 in Oracle9iAS Release 2.  

-virtualhost 

Must be specified when registering an iPlanet server. However, it is optional when registering Oracle HTTP Server. If it is left unspecified, the Oracle HTTP server belongs to a cluster.  

-text_file 

Specifies a path to a temporary version of the mod_osso configuration file. It is optional, and the default location is:

ORACLE_HOME/Apache/Apache/conf/osso/osso.txt.  

-config_file 

Specifies a path to the mod_osso configuration file. It must be specified if -virtualhost is present. For this release, its value can only be set to:

ORACLE_HOME/Apache/Apache/conf/osso/sso_osso.  

Proxy Plug-In Usage Notes

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.

Troubleshooting

This section describes common problems and possible solutions.

Listener Fails To Start

Listener Returns Incorrect URLs

Changes Made to Server Definition File Are Not Reflected

IIS Listener Displays Incomplete Pages or Garbled Characters

Parsing Error Occurs with iPlanet 6.0

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

"File Not Found" Error Occurs

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

Partial URL Requests Return Unexpected Results

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.

iPlanet Server Returns "Server Error" With "/servlet" Request

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.

Server Returns Page With Broken Image Links

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

Unexpected Pages Are Displayed

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.

REMOTE_ADDR Contains Unexpected IP Address

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.

Redirects Go To Network Entry Point

If the back-end server returns a redirect to the entry point of the network, do one of the following:

Solution 1 (Preferred)

Set the following directives in the httpd.conf file:

UseCanonicalName On 
ServerName name of listener computer 
Port port of listener computer 
Solution 2

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

SSL Requests Yield Unexpected Results

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.


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index