Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle HTTP Server
11g Release 1 (11.1.1)
Part Number E10144-02
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

A Using Oracle Plug-ins for Third-Party Web Servers

This appendix explains how the Oracle Proxy Plug-In and Oracle SSO Plug-In enable you to use Oracle Fusion Middleware components in conjunction with a third-party HTTP listener. This appendix includes the following sections:

Documentation from the Apache Software Foundation is referenced when applicable.

A.1 Using Oracle Proxy Plug-In

Oracle Proxy Plug-In enables you to proxy/send requests from a third-party HTTP listener to Oracle Fusion Middleware. The Oracle Proxy Plug-In is provided and certified to work with Sun Java System Web Server Enterprise Edition on UNIX and Microsoft Windows systems, or Microsoft Internet Information Server (IIS) v6.0 and 7.0.

For other third-party HTTP listeners, you can use the respective listener's native proxy functionality.

See Also:

http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html for complete certification information.

This section includes the following topics:

A.1.1 Overview of Oracle Proxy Plug-In

Oracle Proxy Plug-In is a reverse HTTP proxy. The plug-in forwards incoming HTTP requests from a Sun Java System or Microsoft IIS server HTTP listener to an Oracle Fusion Middleware instance, as shown in Figure A-1.

Figure A-1 Oracle Proxy Plug-In

Description of Figure A-1 follows
Description of "Figure A-1 Oracle Proxy Plug-In"

The proxy logic is provided as a plug-in, 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 are used with Oracle HTTP Server.

Oracle HTTP Server can mimic the address and port used by the third-party listener. When sending a request to Oracle HTTP Server, the proxy can be configured to send a different Host: HTTP header than the actual host name and port that the request is being sent to, so that other applications are safeguarded from the reverse proxy.

Oracle Proxy Plug-In does not perform load balancing; it only forwards requests to a single back-end Oracle HTTP Server for a given URL. Also, Oracle Proxy Plug-In does not support SSL between a third-party listener and Oracle HTTP Server.

A.1.2 Installing Oracle Proxy Plug-In

Oracle Proxy Plug-In for Sun Java System or Microsoft IIS is available on the Oracle Fusion Middleware WebTier and Utilities CD for Microsoft Windows, which is included in your Oracle Fusion Middleware CD Pack. Place the appropriate definition file and shared library in directories that are accessible to the third-party listener.

Files on the Oracle Fusion Middleware Web Tier CD-ROM are in the following locations, based on platform:

  • UNIX: /plugins/solaris/ for UNIX

  • Microsoft Windows: /plugins/win32/

Table A-1 contains information about the shared libraries for the OracleAS Proxy Plug-In.

Table A-1 Oracle Proxy Plug-In Shared Libraries

Listener Location and Description

Sun Java System Web Listener

Location on CD-ROM:

  • UNIX: /Disk1/plugins/sjsws/oracle_proxy.so

  • Microsoft Windows: \Disk1\plugins\sjsws\oracle_proxy.dll

To install the plug-in for the listener, copy the .dll file to a directory that the listener has read and execute privileges for UNIX, or a directory that the listener can access for Microsoft Windows.

Microsoft IIS

Location on CD-ROM:

  • \Disk1\plugins\iis\oracle_proxy.dll

To install the plug-in for the listener, copy oracle_proxy.dll to a directory the listener can access.

A.1.3 Configuring Oracle Proxy Plug-In

There is one definition file for the Oracle Proxy Plug-In that controls the proxy functionality. The presence of the file in the Web server file system makes the proxy functionality active. You also need to modify the configuration file(s) specific to the third-party listener, such as the Sun Java System Listener or Microsoft IIS configuration file, to enable the plug-in on these listeners. The definition file for the Oracle Proxy Plug-In can have any name.

A.1.3.1 Proxy Server Definition File

The proxy server definition file must reside in a directory that is readable by the third-party listener. For example, you could create a directory called proxy in a directory on your system, and place the proxy server definition file, the proxy shared library file, and proxy log files in it.

The proxy server definition file contains the following parameters:

  • Name-value pairs that describe the servers that will be used to proxy requests to Oracle Fusion Middleware

  • Options for communicating with the servers

  • A set of rules that map URLs to the servers

You can create this file with the text editor of your choice.

A.1.3.2 Proxy Definition File Parameters

The following proxy parameters are used in the proxy definition file:

A.1.3.2.1 oproxy.serverlist

Lists all the server names recognizable to the plug-in.

Category Value
Allowable Values Comma-separated list of server names, one for each Oracle HTTP Server to which requests will be sent. All servers in the server list must also be defined in the file.

Note: Oracle Proxy Plug-In does not do load balancing; therefore, if you define two servers with same urlrule, it will forward requests to only one of those servers.
Default Value None. At least one server name must be provided for the proxy to be functional.
Example oproxy.serverlist=ohs1,ohs2

A.1.3.2.2 oproxy.servername.hostname

Defines the host name to use when communicating with a specific server.

Category Value
Allowable Values A valid host name
Default Value None
Example oproxy.ohs1.hostname=host1.acme.com

A.1.3.2.3 oproxy.servername.port

Defines the port to use when communicating with a specific server.

Category Value
Allowable Values A port value
Default Value 80
Example oproxy.ohs1.port=7777

A.1.3.2.4 oproxy.servername.alias

Supports the alias feature of the proxy by defining the host name and port that clients use to access the third-party HTTP listener. If defined, then this value will be passed as the Host: HTTP header. If not defined, then the host name and port of the system actually being communicated with will be sent.

Category Value
Allowable Values host:port
Example oproxy.ohs1.alias=www.example.com:80

A.1.3.2.5 oproxy.servername.resolveall

Directs the proxy plug-in to resolve the host name to the backend server on every request. This enables DNS based failover or routing between the proxy plug-in and backend servers. The use of this parameter requires going to the DNS server for every incoming request, and should only be used if the mapping from host name to IP address will change dynamically.

Category Value
Allowable Values true | false
Default Value false
Example oproxy.ohs1.resolveall=true

A.1.3.2.6 oproxy.servername.urlrule

Describes a URL or set of URLs that are redirected to this server. A given server can have any number of urlrule properties assigned to it.

Category Value
Example oproxy.ohs1.urlrule=/foo/*

The following types of rules can be used:

  • Exact matches: One URL is mapped to a server. For example:

    oproxy.ohs1.urlrule=/foo/bar/foo.html

    maps only the URL /foo/bar/foo.html. This would be the proxy for the server with the name ohs1.

  • Context matches: A set of URLs with a common prefix or context are mapped to a server. For example:

    oproxy.ohs1.urlrule=/foo/*

    maps URLs beginning with /foo to the server with the name ohs1.

    For context matches, you can use the stripcontext option with the urlrule parameter to send only the portion of the URL following the wildcard to the server. The default for the stripcontext option is false, so you do not need to include it unless you are setting it to true. It is shown for completeness of the example.

    Parameters URL Request Result 
    oproxy.ohs1.urlrule=/foo/*
oproxy.ohs1.stripcontext=true

    http://hostname/foo/header1.gif

    ORACLE_INSTANCE/config/OHS/<ohs_name>/htdocs/header1.gif

    oproxy.ohs1.urlrule=/foo/*
oproxy.ohs1.stripcontext=false

    http://hostname/foo/header1.gif

    ORACLE_INSTANCE/config/OHS/<ohs_name>/htdocs/foo/header1.gif

  • Suffix matches: All files with a common file extension are mapped to a server.

    For example:

    oproxy.ohs1.urlrule=/*.jsp

    maps all the URLs that end in .jsp to the server ohs1. This can be combined with the context rule to have /foo/bar/*.jsp so that only URLs that start with /foo/bar and end in .jsp would be proxied.

Note:

For oproxy.servername.urlrule, when multiple rules apply to the same URL, the following precedence applies:

  1. Exact matches

  2. Longest context match plus suffix match

  3. Longest context match

Some examples of the precedence are as follows:

  • /foo/bar/index.html would take precedence over /foo/bar/*

  • /foo/bar/*.jsp would take precedence over /foo/bar/*

  • /foo/bar/* would take precedence over /foo/*

A.1.3.3 Defining Oracle Proxy Plug-In Behavior

In the proxy server definition file, you define which servers and URLs to use as proxy to the plug-in.

  1. In the first line of the file, specify the list of all the servers that can be used by the plug-ins, such as the following:

    oproxy.serverlist=ohs1,ohs2

  2. View the Oracle HTTP Server ports using Fusion Middleware Control or the opmnctl command-line utility. The port number will be used in the next step.

  3. Set the relevant properties (host name, port, and server alias) for each server. For example:

    oproxy.ohs1.hostname=host1.acme.com.us.example.com
oproxy.ohs1.port=7777
oproxy.ohs1.alias=www.example.com

    The host name must be provided. If an alias value is not given, the combination of the host name and port is used. The alias enables the backend server to receive requests that have an HTTP Host header that looks exactly like the one the client delivers to the third-party listener.

  4. Set the urlrule parameter to specify redirection between servers. For example, this rule maps all incoming requests to proxy to the Web server on the server ohs1:

    oproxy.ohs1.urlrule=/*

Example A-1 is a sample proxy server definition file.

Example A-1 Sample Proxy Server Definition File

# This file defines proxy server behavior.
#
# Server names that the proxy plug-in will recognize.
oproxy.serverlist=ohs1

# Hostname to use when communicating with a specific server.
oproxy.ohs1.hostname=host1.acme.com

# Port to use when communicating with a specific server.
oproxy.ohs1.port=7777

# URL(s) that will be redirected to this server.
oproxy.ohs1.urlrule=/*

A.1.4 Configuring Sun Java System Listener to Use Oracle Proxy Plug-In

This section provides proxy plug-in configuration information for Sun Java System listener on UNIX and Microsoft Windows platforms.

The default configuration files for Sun Java System route all incoming requests for the URI /servlet to the Sun Java System servlet handler. The Oracle Proxy Plug-In does not override the Sun Java System server configuration settings. You must ensure that the URL mappings to the Oracle Proxy Plug-In are distinct from the URL mappings to the Sun Java System servlet engine.

If you are configuring the Sun Java System listener on Microsoft Windows, use forward slashes (/) in all paths.

  1. Open the magnus.conf file located in the /config directory for the Sun Java System listener version 6 or 7.

  2. Add the following load-modules line, depending on the operating system:

    • For UNIX:

      Init fn="load-modules" shlib="/path/oracle_proxy.so" funcs=op_init,op_objecttype,op_service

    • For Microsoft Windows:

      Init fn="load-modules" shlib="/path/oracle_proxy.dll" funcs=op_init,op_objecttype,op_service

    In the preceding lines, path is the path to the shared library for the plug-in. This tells the listener where the proxy shared library is, and which functions are exposed by this library.

  3. Add the following configuration parameters:

    Init fn="op_init" server_defs="/path/to/proxy/definition/file" log_file="/path/to/proxy/log/file" log_level=loglevel

    For example:

    Init fn="op_init" server_defs="/oracle/proxyplugin/proxydefs" log_file="/oracle/proxyplugin/oproxy.log" log_level=error

    The proxy server definition file contains all the configuration information for the servers that can communicate with the proxy plug-in. The definition file can have any name.

    A log file and log level can be specified to log messages from the plug-in. This is optional.

    See Also:

    See Section A.1.3.1, "Proxy Server Definition File" for a complete description and example

  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. Save the file.

  7. Start the listener using the Sun Java System GUI or the shell script.

A.1.5 Configuring Microsoft IIS 6.0 Listener to Use Oracle Proxy Plug-In

This section provides proxy plug-in configuration instructions for the Microsoft IIS 6.0 listener on Microsoft Windows platforms. The procedure involves creating Microsoft Windows registry entries and using the Microsoft IIS 6.0 management console to add directories and filters. You must restart the listener after configuring the plug-in.

To configure the plug-in, perform the following steps:

  1. Use the Microsoft Windows Registry Editor to create new registry entries.

    1. From the Start menu, Select Run, and the type regedit in the dialog box, and click OK. The Registry Editor window opens

    2. Expand the HKEY_LOCAL_MACHINE folder by clicking the plus sign (+) preceding its name In the Registry Editor window.

    3. Expand the SOFTWARE folder by clicking the plus sign (+) preceding its name, and then Click the ORACLE folder.

    4. From the Edit menu, select New > Key. A new folder is added under the ORACLE folder with the name New Key #1.

    5. Enter IIS Proxy Adapter for the key name.

    6. From the Edit menu, select New > String Value. A new value is added in the right window pane with the name New Value #1. Enter server_defs for the value name.

    7. From the Edit menu, select Modify. The Edit String dialog box appears.

    8. In the Value data field, enter the full path of your proxy server definition file, and then click OK.

    9. Optionally, you can specify log_file and log_level using the procedure specified in steps d.) – h.).

      • Add a string value with the name log_file and the desired location of the log file, such as d:\proxy\proxy.log.

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

    10. Close the Registry Editor window by selecting Exit from the File menu.

  2. Use the Microsoft IIS management console to add a new virtual directory to your Microsoft IIS Web site with the same physical path as that of the oracle_proxy.dll.

    1. Open the IIS Manager by clicking Start -> Programs -> Administrative Tools -> Internet Information Services (IIS) Manager.

    2. Expand the server folder by clicking the plus sign (+) preceding the server name.

    3. Right-click the Default Sites folder, and then select the New -> Virtual Directory option from the menu.

    4. In the Virtual Directory Creation Wizard window, enter oproxy for the Alias. Then, enter the path or browse to the directory containing the oracle_proxy.dll file (e.g., c:\OProxy) and select the Execute (such as ISAPI applications or CGI) check box.

    5. Click Finish to close the Virtual Directory Creation Wizard.

  3. Use the Microsoft IIS management console to add oracle_proxy.dll as a filter in your Microsoft IIS Web site. The name of the filter should be oproxy and its executable must point to the directory containing the oracle_proxy.dll file.

    1. Right-click the Default Sites folder, and then select the Properties option from the menu.

    2. In the Default Web Site Properties window, select the ISAPI Filters tab.

    3. Click Add to add a new filter.

      The Add/Edit Filter Properties window is displayed.

    4. Enter oproxy for the filter name. Then, enter the path or browse to the directory containing the oracle_proxy.dll file (e.g., c:\OProxy\oracle_proxy.dll).

      Description of iis6_addfilter_p.gif follows
      Description of the illustration iis6_addfilter_p.gif

    5. Click OK to close the Add/Edit Filter Properties window.

    6. Click OK to close the Default Web Site Properties window.

  4. Under the server name folder, click the Web Service Extensions folder to open the Web Service Extensions page. Select All Unknown ISAPI Extensions in the right panel and click Allow. The status of this item should change from Prohibited to Allowed.

  5. Select the Application Pools folder, and then right-click the Properties option from the menu. On the Application Pools Properties window, select the Identity tab and change the Predefined identity to Local System. A confirmation dialog box displays asking Are you sure you want to do this? Select Yes.

  6. Stop and restart the Microsoft IIS 6.0 server.

    Note:

    To restart Microsoft IIS, you must stop all the Microsoft IIS services through the control panel or restart the computer. This is the only way to ensure that the .dll is reloaded. Restarting Microsoft IIS 6.0 through the management console is not sufficient.

  7. Make sure the newly created oproxy filter is marked with a green upward arrow.

A.1.6 Configuring Microsoft IIS 7.0 Listener to Use Oracle Proxy Plug-In

This section provides proxy plug-in configuration instructions for the Microsoft IIS 7.0 Listener on Microsoft Windows platforms. The procedure involves creating Microsoft Windows registry entries and using the Microsoft IIS 7.0 management console to add directories and filters. You must restart the listener after configuring the plug-in.

To configure the plug-in, perform the following steps:

  1. Complete step 1 in Section A.1.5, "Configuring Microsoft IIS 6.0 Listener to Use Oracle Proxy Plug-In" to use the Registry Editor to create new registry entries for the plug-in.

  2. Use the Microsoft IIS management console to add the proxy plug-in filter:

    1. Open the IIS Manager by clicking Start -> Programs -> Administrative Tools -> Internet Information Services (IIS) Manager.

    2. Expand the server folder by clicking the plus sign (+) preceding the server name (e.g, DSCDAA10-VM6).

    3. Expand the Sites folder by clicking the plus sign (+) preceding its name.

    4. Click the Default Web Site icon to open the Default Web Site Home page.

    5. Double-click the ISAPI Filters icon to open the ISAPI Filters page, and then complete the following tasks:

      • In the Actions pane, click Add to open the Add ISAPI Filter dialog box.

      • In the Filter Name field, enter a user-friendly name for the ISAPI filter.

      • In the Executable field, enter the file system path for the location of ISAPI filter file, or click the ellipsis button (...) to navigate to the folder that contains the ISAPI filter file.

        Description of isapi3_p.gif follows
        Description of the illustration isapi3_p.gif

      • Click OK.

  3. Follow these steps to configure the newly added ISAPI filter:

    1. Click the Default Web Site icon in the navigation panel to view all the settings related to the application that can be modified.

    2. Click the Handler Mappings option to set the mappings for the handler for a particular MIME type.

    3. Click the StaticFile option in the Handler Mappings page, and in the Edit Module Mapping dialog box, change the Request path to *.*.

    4. In the Actions area of the Handler Mappings page, click the Add Script Map option.

    5. In the Edit Script Map dialog box: enter * for the Request path. Use the Executable field to browse to the oracle_proxy.dll file and add it as the executable. Name it as proxy.

    6. Click the Request Restrictions button to open the Request Restrictions dialog box. Clear the Invoke handler only if the request is mapped to check box and then click OK to add this Handler mapping.

    7. Click Yes on the Add Script Map dialog box.

    When you click the Root node of the IIS manager tree, and then click on the ISAPI and CGI Restrictions, you should see an entry for the oracle_proxy.dll, as shown here:

    [No Description] Allowed C:\proxy\oracle_proxy.dll

  4. Restart the Microsoft IIS server by opening the Services Control Panel, and then stopping and restarting the World Wide Web Publishing Service.

    Note:

    To restart Microsoft IIS, you must stop all the Microsoft IIS services through the control panel or restart the computer. This is the only way to ensure that the .dll is reloaded. Restarting Microsoft IIS 7.0 through the management console is not sufficient.

A.1.7 Oracle Proxy Plug-In Usage Information

This section highlights development and usage practices to consider when developing an application that runs behind the Oracle Proxy Plug-In. Some of the practices also apply when enabling an application to run behind Oracle Web Cache.

  • Check for configurations based on Oracle HTTP Server being the entry point into the network.

    This is usually only relevant if an application has a module that plugs directly into Oracle HTTP Server. Specifically, look for dependencies on obtaining information about the client based on the connection made to Oracle HTTP Server, such as using the SSL certificate for authentication. Currently, Secure Socket Layer (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 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 Oracle Proxy Plug-In and Oracle Web Cache are used, but other client information may, in practice, represent the system on which the proxy resides rather than the actual client host. These behaviors must be discovered and eliminated in cases where Oracle HTTP Server is not the external listener for Oracle Fusion Middleware.

  • Avoid embedding host names into HTML unless the link is external to the Web site.

    This includes static HTML pages, dynamic pages generated by servlets, JSPs, PL/SQL, and so on. Examine all code that obtains the server name of Oracle HTTP Server to ensure that the code is not embedding the server name into pages that are sent back to the client. To test for this behavior, use a Web crawler application (also known as a spider) to traverse all links in a Web site. Open source tools with this functionality are available.

  • Avoid returning host and port information in applications (such as applets or javascript) downloaded to the client.

    If you have an application that uses browser-based code, ensure that the code does not contain the host name and port of Oracle HTTP Server that actually delivers the content. Instead, it must have the actual client-accessible address used by the third-party listener.

  • Ensure that all URLs within an application can be easily mapped to a set of rules that the proxy can use.

    To successfully proxy all requests for an application, the Oracle Proxy Plug-In must have a complete description of the URL space for that application. Each Oracle Fusion Middleware 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, then the request will be served by the third-party HTTP listener, and a "document not found" error may occur, or a different 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 the following:

    • Change these common links to something that will not conflict with applications that might already be deployed on the third-party listener.

    • Instruct the user to copy the necessary content to the third-party listener directory structure. For performance reasons, it is a good idea to have the third-party listener handle static .gif and .jpg files, but it requires that the files be copied to the third-party listener.

A.1.8 Troubleshooting Oracle Proxy Plug-In

This section describes common problems and solutions related to Oracle Proxy Plug-In.

Listener Fails to Start

  • Check for problems in the proxy server definition file. Each server in the server list line must be defined later in the file, and you must define at least one server. If a server name is listed but not defined, then the listener may not start. Ensure that there are no typographical errors or missing quotes in the proxy server definition file.

  • For Sun Java System 6.0: Ensure that Init lines are added to the magnus.conf file, and the ObjectType and Service lines are added to the obj.conf file.

Listener Returns Incorrect URLs

  • Verify that changes to the proxy server definition file were saved and the listener was restarted.

  • Ensure that there are no typographical errors in the proxy server definition file.

  • Ensure that the urlrule parameter is set up correctly, and determine whether the stripcontext option should be set to true.

  • Verify that the serverlist line in the proxy server definition file specifies the back-end server you are trying to reach.

  • Verify that the back-end server is running, and that the file you are attempting to retrieve exists and is accessible on the back-end server.

  • Verify that the host, port and urlrule parameters in the proxy server definition file target the correct area on the back-end server.

  • Ensure that client requests are being sent to the correct port on the third-party listener machine.

  • Check the listener log files, the proxy log, and the back-end server logs to verify that requests are getting through. The proxy log may need to be set to debug mode You may need to restart the listener.

Changes Made to Proxy Server Definition File are Not Reflected

  • Verify that changes to the proxy server definition file were saved and the listener was restarted.

  • For Microsoft IIS, verify that WWW Publishing Service was stopped and started from the Control Panel. This may take a few minutes.

Microsoft IIS Listener Displays Incomplete Pages or Garbled Characters

Do not display Microsoft IIS pages with a Sun Java System browser.

Parsing Error Occurs with Sun Java System 6.0 or 7.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."

Remove any comments and added lines preceding and following the Init lines in the magnus.conf file.

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 Also:

Section A.1.3.2.6, "oproxy.servername.urlrule"

Sun Java System Web Server Returns Server Error with /servlet Request

The default Sun Java System configuration maps any URL requests to /servlet to its own servlet handler. You must edit the proxy server definition file, or change the Sun Java System configuration to correct this.

Partial URL Requests Return Unexpected Results

The Microsoft IIS and Sun Java System servers auto-complete URLs differently than others. Requests to http://example, http://example/, and http://example/index.html do not necessarily return the same results on different platforms. Use the oproxy.servername.urlrule parameter to work around this problem.

See Also:

Section A.1.3.2.6, "oproxy.servername.urlrule"

Server Returns Page with Broken Image Links

If you use an exact urlrule parameter in the proxy server definition file, such as urlrule=/*.html, the server retrieves the specified page. All other links are forbidden to the user, including inline images on 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 Sun Java System and Microsoft Internet Explorer use cached pages even when set to retrieve the page every time and 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 are not expecting, try refreshing the browser or reloading the page.

REMOTE_ADDR Contains Unexpected IP Address

The REMOTE_ADDR field usually contains the IP address of the client system. 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, the host and port information should be updated. Choose one of the following options, based on your installation. The first option is the preferred method.

  • Use the Advanced Configuration page of Fusion Middleware Control to set the following directives in the httpd.conf file:

    UseCanonicalName On 
ServerName name of listener host 
Port port of listener host

  • Use the Advanced Configuration page of Fusion Middleware Control to set the following directives in the httpd.conf file:

    UseCanonicalName port 
Port port of listener host

Edit the proxy plug-in server definition file to use the following:

oproxy.serverName.alias=name of listener host:port of listener host

A.2 Using Oracle SSO Plug-In

Oracle SSO Plug-In is designed to protect native third-party listener applications using the Oracle single sign-on (SSO) infrastructure. The Oracle SSO Plug-In is provided and certified to work with Sun Java System Web Server Enterprise Edition on UNIX and Microsoft Windows systems, and Microsoft Internet Information Server (IIS) v6.0 and v7.0 on Microsoft Windows systems.

See Also:

http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html for complete certification information

This chapter includes the following topics:

A.2.1 Overview of Oracle SSO Plug-In

Oracle SSO Plug-In is the Oracle single sign-on (SSO) solution for third-party listeners, such as Sun Java System and Microsoft IIS. The plug-in is designed to protect native third-party listener applications using the SSO infrastructure. With the help of the Oracle SSO Plug-In, users can be authenticated to different third-party listener applications using only one SSO password. You can integrate these SSO-protected third-party listener applications with SSO-enabled Oracle HTTP Server applications or legacy Oracle SSO enabled applications as long as they are all protected on the same SSO server.

Oracle SSO Plug-In is a simple version of mod_osso, and only implements some of its basic functionality. Features such as dynamic authentication, global logout, idle timeout, global timeout, and basic authentication for legacy application are not implemented in the current Oracle SSO Plug-In release.

Figure A-2 illustrates the process when a user requests a URL protected by the Oracle SSO Plug-In.

Figure A-2 Oracle SSO Plug-In

Description of Figure A-2 follows
Description of "Figure A-2 Oracle SSO Plug-In"

  1. The user requests a URL through a Web browser.

  2. The Web server looks for an Oracle SSO Plug-In cookie for the user. If the cookie exists, the Web server extracts the user's information and uses it to log the user in to the requested application.

  3. If the cookie does not exist, the Oracle SSO Plug-In redirects the user to the single sign-on server.

  4. The single sign-on server looks for its own cookie in the browser. If a cookie exists, then the single sign-on server authenticates using the cookie. If authentication is successful, then the single sign-on server creates a cookie in the browser as a reminder that the user has been authenticated. If it finds none, it tries to authenticate the user with a user name and password.

  5. The single sign-on server returns the user's encrypted information to the Oracle SSO Plug-In.

  6. Oracle SSO Plug-In creates its own cookie for the user in the browser and redirects the user to the requested URL.

    During the same session, if the user again seeks access to the same or to a different application, the user is not prompted for a user name and password. The application uses an HTTP header to obtain this information from the Oracle SSO Plug-In session cookie.

See Also:

Oracle Fusion Middleware Security Guide

A.2.2 Installing Oracle SSO Plug-In

Oracle SSO Plug-In for Sun Java System and Microsoft IIS is available on the Oracle Fusion Middleware Web Tier and Utilities CD from Microsoft Windows, which is included in your Oracle Fusion Middleware CD Pack.

Install Oracle SSO Plug-In on a system that has an Oracle Fusion Middleware installation. This installation is required only for the network and security dependent libraries and the single sign-on registration tool. It is not required to be running.

Place the configuration file and shared library in directories that are accessible to the third-party listener. For security reasons, ensure that all the configuration files and plug-in libraries are given minimum privileges.

On the Oracle Fusion Middleware Web Tier and Utilities CD, the files are located at /plugins/solaris/ for UNIX and /plugins/win32/ for Microsoft Windows.

Table A-2 contains information about the shared libraries for Oracle SSO Plug-In.

Table A-2 Oracle SSO Plug-In Shared Libraries

Listener Location and Description

Sun Java System Web Listener

Location on CD-ROM:

  • UNIX: /Disk1/plugins/sjsws/oracle_osso.so

  • Microsoft Windows: \Disk1\plugins\sjsws\oracle_osso.dll

To install the plug-in for the listener, copy the .dll file to a directory that the listener has read and execute privileges for UNIX, or a directory that the listener can access for Microsoft Windows.

Microsoft IIS

Location:

  • \Disk1\plugins\iis\oracle_osso.dll

To install the plug-in for the listener, copy oracle_osso.dll to a directory the listener can access.

A.2.3 Registering with the Oracle Single Sign-On Server

The single sign-on registration process enables the single sign-on server and the listener to share information such as server location, protocol version, and common encryption key, before they communicate. After the registration process, this information is stored on the single sign-on server side as a single sign-on partner application entry. On the listener side, a single sign-on file called osso_conf is created. The osso_conf file is obfuscated for security purposes. Copy the file to an appropriate location so the listener can access it.

See Also:

Oracle Fusion Middleware Security Guide for details on how to register with Oracle Single Sign-On.

A.2.4 Configuring the Oracle SSO Plug-In

To configure Oracle SSO Plug-In, you must create a configuration file such as the osso_plugin.conf file. This file must reside in a directory that is readable by the third-party listener. You define all the plug-in functionality within the file. It can also be referred as the osso property file. The file contains the following:

  • Plug-in directives such as LoginServerFile and IpCheck

  • A set of rules that match resources to be protected.

A.2.4.1 Oracle SSO Plug-In Directives

Table A-3 lists the configuration directives for the Oracle SSO Plug-In.

Table A-3 Oracle SSO Plug-In Configuration Directives

Directive Function

LoginServerFile

Specifies the location of the single sign-on server configuration file such as the osso.conf file that is attained from the SSO registration process.

This is a global parameter and should not be used on a per-resource basis. You must provide one and only one single sign-on server configuration file.

  • Value: The full path of your Single Sign-On Server configuration file

  • Default: None

  • Example: LoginServerFile=c:\OSSO\config\osso.conf

IpCheck

Specifies whether the Oracle SSO plug-in should check the IP address of each request when it examines the cookie. Setting it to true prevents cookies from being accessed by another person.

  • Values: true | false

  • Default: false

  • Example: IpCheck=true

Note: Set it to false if you have a proxy server or firewall between your Sun Java System server and your client browsers.

A.2.4.2 Rules to Protect Resources

To ensure resource protection via the Oracle SSO Plug-In, a set of rules must be defined. The rules are defined according to the following format:

<OSSO url-matching-rule>
  SSO_configuration_directives
</OSSO>

Use the following rules to define the url-matching-rule:

Rule Name Description
Exact Match This option identifies an exact file as a protected resource, for example: /examples/hello.html
Context Match This option identifies a directory as a protected resource, for example: /examples/*
Extension Match This option identifies files with a certain extension in a particular directory as a protected resource, for example: /examples/*.jsp

When multiple rules apply to the same URL, the following precedence applies:

  1. Exact matches

  2. Longest context match plus suffix match

  3. Longest context match

Some examples of the precedence are:

  • /foo/bar/index.html would take precedence over /foo/bar/*

  • /foo/bar/*.jsp would take precedence over /foo/bar/*

  • /foo/bar/* would take precedence over /foo/*

Example A-2 shows a simple file with the commands for resource protection. In the example, the IpCheck directive is set to false for the /private/hello.html file, but it is set to true for /private2/*.jsp. This setting ensures the cookies used with requests to the /private2/*.jsp files are not accessed by another user.

Example A-2 Simple Single Sign-on Configuration File, osso_plugin.conf

LoginServerFile=c:\OSSO\conf\osso.conf
<OSSO /private/hello.html>
  IpCheck=false
</OSSO>
<OSSO /private1/*>
</OSSO>
<OSSO /private2/*.jsp>
  IpCheck=true
</OSSO>

A.2.5 Configuring Sun Java System Listener for Single Sign-on

This section provides Oracle SSO Plug-In configuration information for the Sun Java System listener. You can use any text editor to edit the files.

Note:

If you are configuring the Sun Java System listener on Microsoft Windows, use forward slashes (/) in all paths.

  1. Open the magnus.conf configuration file located in the /config directory for the Sun Java System version 6 or 7 listener.

  2. Add the following lines to the file. The two lines beginning with Init must be added at the end of the file.

    On UNIX:

    Init fn="load-modules" shlib="/path1/oracle_osso.so" funcs="osso_init, \
oracle_single_sign_on,osso_redirect_service,osso_success_service"

Init fn="osso_init" osso_properties="/path2/osso_plugin.conf"   \
log_file="/path2/plugin.log" log_level=error

    On Microsoft Windows:

    Init fn="load-modules" shlib="/path1/oracle_osso.so" \
funcs="osso_init,oracle_single_sign_on,osso_redirect_service, \
osso_success_service"

Init fn="osso_init" osso_properties="/path2/osso_plugin.conf"   \
log_file="/path2/plugin.log" log_level=error

    In the preceding lines, the following variables were used:

    • path1 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.

    • path2 is the path to the plug-in configuration file you just created. This line can specify a log file and log level to log messages from the plug-in (optional).

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

    AuthTrans fn="oracle_single_sign_on"

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

  5. Add the following lines:

    <Object ppath="/path/osso_login_success">
Service fn="osso_success_service"
</Object>

    path is the path of your document root, for example, /home/Sun Java/docs/ or $docroot.

  6. Change the library path variable in the start script to include the location of the ORACLE_HOME/lib32 directory.

  7. Restart the listener.

A.2.6 Configuring Microsoft IIS 6.0 Listener to Use Oracle Single Sign-On

This section provides instructions on configuring the Microsoft IIS 6.0 Listener to use Oracle SSO Plug-In. The plug-in consists of a single .dll file, oracle_osso.dll. To install the plug-in, copy the .dll to the host on which Microsoft IIS 6.0 resides and perform the following steps:

  1. Use the Microsoft Windows Registry Editor to create new registry entries.

    1. From the Start menu, Select Run, and the type regedit in the dialog box, and click OK. The Registry Editor window opens

    2. Expand the HKEY_LOCAL_MACHINE folder by clicking the plus sign (+) preceding its name In the Registry Editor window.

    3. Expand the SOFTWARE folder by clicking the plus sign (+) preceding its name, and then Click the ORACLE folder.

    4. From the Edit menu, select New > Key. A new folder is added under the ORACLE folder with the name New Key #1.

    5. Enter IIS OSSO Adapter for the key name.

    6. From the Edit menu, select New > String Value. A new value is added in the right window pane with the name New Value #1. Enter cfg_file for the value name.

    7. From the Edit menu, select Modify. The Edit String dialog box appears.

    8. In the Value data field, enter the full path of the OSSO plug-in configuration file you created (e.g., c:\osso\osso_plugin.conf).

      Note:

      This is the plug-in configuration file and not the encrypted osso.conf file generated by the SSO registration process.

    9. Optionally, you can specify log_file and log_level using the procedure specified in steps d.) through h.).

      • Add a string value with the name log_file and the desired location of the log file, such as c:\osss\osso_plugin.log.

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

    10. Close the Registry Editor window by selecting Exit from the File menu.

  2. Use the Microsoft IIS management console to add a new virtual directory to your Microsoft IIS Web site with the same physical path as that of the osso.dll.

    1. Open the IIS Manager by clicking Start -> Programs -> Administrative Tools -> Internet Information Services (IIS) Manager.

    2. Expand the server folder by clicking the plus sign (+) preceding the server name.

    3. Right-click the Default Sites folder, and then select the New -> Virtual Directory option from the menu.

    4. In the Virtual Directory Creation Wizard window, enter osso for the Alias. Then, enter the path or browse to the directory containing the oracle_osso.dll file (e.g., c:\osso) and select the Execute (such as ISAPI applications or CGI) check box.

    5. Click Finish to close the Virtual Directory Creation Wizard.

  3. Use the Microsoft IIS management console to add oracle_osso.dll as a filter in your Microsoft IIS Web site. The name of the filter should be osso and its executable must point to the directory containing the oracle_osso.dll file.

    1. Right-click the Default Sites folder, and then select the Properties option from the menu.

    2. In the Default Web Site Properties window, select the ISAPI Filters tab.

    3. Click Add to add a new filter.

      The Add/Edit Filter Properties window is displayed.

    4. In the Filter Name field, enter osso for the filter name.

    5. In the Executable field, enter the path for the location containing the oracle_osso.dll (e.g., c:\osso\oracle_osso.dll), or click the ellipsis button (...) to navigate to the folder that contains the oracle_osso.dll file.

      Description of iis6_addfilter_osso.gif follows
      Description of the illustration iis6_addfilter_osso.gif

    6. Click OK to close the Add/Edit Filter Properties window.

    7. Click OK to close the Default Web Site Properties window.

  4. Configure security settings for Oracle Home directory. Make sure you login to machine as an administrator user.

    1. In Windows Explorer, right-click the ORACLE_HOME\bin folder, select Properties from the menu, and then click the Security tab.

    2. Add the IIS_WPG, NETWORK and NETWORK SERVICE groups with Read and Execute permissions.

    3. Click OK.

  5. Stop and restart the Microsoft IIS 6.0 Server.

Notes:

  • To restart Microsoft IIS 6.0, you must stop all the Microsoft IIS 6.0 services through the control panel or restart the computer. This is the only way to ensure that the .dll file is reloaded. Restarting Microsoft IIS 6.0 through the management console is not sufficient.

  • If you want multiple Oracle installations on the same home, then the ORACLE_HOME\bin PATH entry for the installation that you plan to use in conjunction with the Oracle SSO Plug-In must appear first in your PATH.

  • Make sure the newly added ISAPI filter is marked with a green upward arrow.

A.2.7 Configuring Microsoft IIS 7.0 Listener to Use Oracle Single Sign-On

This section provides instructions on configuring the Microsoft IIS 7.0 Listener to use Oracle SSO Plug-In. The plug-in consists of a single .dll file, oracle_osso.dll. To install the plug-in, copy the .dll to the host on which Microsoft IIS 7.0 resides and perform the following steps:

  1. Complete step 1 in Section A.2.6, "Configuring Microsoft IIS 6.0 Listener to Use Oracle Single Sign-On" to use the Microsoft Windows Registry Editor to create new registry entries for the plug-in.

  2. Use the Microsoft IIS management console to add the oracle_osso.dll as a filter in your Microsoft IIS Web site:

    1. Open the IIS Manager by clicking Start -> Programs -> Administrative Tools -> Internet Information Services (IIS) Manager.

    2. Expand the server folder by clicking the plus sign (+) preceding the server name (e.g, DSCDAA10-VM6).

    3. Expand the Sites folder by clicking the plus sign (+) preceding its name.

    4. Click the Default Web Site icon to open the Default Web Site Home page.

    5. Double-click the ISAPI Filters icon to open the ISAPI Filters page, and then complete the following tasks:

      • In the Actions pane, click Add to open the Add ISAPI Filter dialog box.

      • In the Filter Name field, enter osso.

      • In the Executable field, enter the file system path for the location containing the oracle_osso.dll (e.g., c:\osso\oracle_osso.dll), or click the ellipsis button (...) to navigate to the folder that contains the oracle_osso.dll file.

        Description of isapi3_osso.gif follows
        Description of the illustration isapi3_osso.gif

      • Click OK.

  3. Configure security settings for Oracle Home directory. Make sure you log in to machine as an administrator user.

    1. In Windows Explorer, right-click the ORACLE_HOME\bin folder, select Properties from the menu, and then click the Security tab.

    2. Add the IIS_WPG, NETWORK and NETWORK SERVICE groups with Read and Execute permissions.

    3. Click OK.

  4. Restart the Microsoft IIS server by opening the Services Control Panel, and then stopping and restarting the World Wide Web Publishing Service.

Notes:

  • To restart Microsoft IIS 7.0, you must stop all the Microsoft IIS 7.0 services through the Services Control Panel or restart the computer. This is the only way to ensure that the .dll file is reloaded. Restarting Microsoft IIS 7.0 through the management console is not sufficient.

  • If you want multiple Oracle installations on the same home, then the ORACLE_HOME\bin PATH entry for the installation that you plan to use in conjunction with the Oracle SSO Plug-In must appear first in your PATH.

A.2.8 Troubleshooting Oracle SSO Plug-In

This section describes common problems and solutions.

Oracle Dependency Libraries Not Found

You may not have included ORACLE_HOME in your path.

Solution

Check to see that you have ORACLE_HOME/lib included in your library path variable on UNIX. On Microsoft Windows, ensure that you have ORACLE_HOME\bin in your path.

Microsoft IIS Oracle SSO Plug-In Does not Work with HTML Authentication

The Oracle SSO Plug-In is designed not to work with other authentication modules. Authentication is either a native listener authentication module or a third-party module.

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us