B Using Oracle Application Server SSO Plug-in

This appendix explains how to use Oracle Application Server SSO Plug-in (OracleAS SSO Plug-in) to a protect third-party HTTP listener and its applications. The OracleAS SSO Plug-in works with the Sun ONE Web Server Enterprise Edition on UNIX and Windows systems, and the Microsoft Internet Information Server (IIS) on Windows systems.

B.1 Overview

OracleAS SSO Plug-in is Oracle's single sign-on (SSO) solution for third-party listeners such as Sun ONE and IIS. The plug-in is designed to protect native third-party listener applications using the SSO infrastructure. With the help of the OracleAS SSO Plug-in, you 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 application together as long as they are all protected on the same SSO server.

OracleAS 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 and global timeout, and basic authentication for legacy application are not implemented in the current OracleAS SSO Plug-in release.

Figure B-1 illustrates the process involved when you request a URL protected by the OracleAS SSO Plug-in.

Figure B-1 OracleAS SSO Plug-in

Description of "Figure B-1 OracleAS SSO Plug-in"

The user requests a URL through a Web browser.
The Web server looks for an OracleAS 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.
If the cookie does not exist, then the OracleAS SSO Plug-in redirects the user to the single sign-on server.
The single sign-on server looks for its own cookie in the browser. If it finds none, it tries to authenticate the user with a user name and password. If authentication is successful, the single sign-on server creates a cookie in the browser as a reminder that the user has been authenticated. If a cookie exists, the single sign-on server authenticates using the cookie.
The single sign-on server returns the user's encrypted information to the OracleAS SSO Plug-in.
OracleAS 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 OracleAS SSO Plug-in session cookie.

B.2 Downloading OracleAS SSO Plug-in

OracleAS SSO Plug-in is available on the Oracle Application Server 10g Companion CD, which is included in your Oracle Application Server CD Pack.

B.3 Installing OracleAS SSO Plug-in

Install OracleAS SSO Plug-in on a machine that has an Oracle Application Server installation. This installation is required only for the network and security dependent libraries and single sign-on registration tool; it is not required to be running. After the Oracle Application Server installation on UNIX systems, add ORACLE_HOME/lib to the LD_LIBRARY_PATH in the listener's start script. For example, the "start" script in Sun ONE. On Windows systems, the installation automatically sets the environment variable PATH. For example, ORACLE_HOME\bin.

Download, or copy, the plug-in, and place the configuration file and shared libraries in directories that the third-party listener can access. For security reasons, ensure that all the configuration files and plug-in modules are given minimum privileges.

On the Oracle Application Server 10g Companion CD, the files are located at /plugins/solaris/ for UNIX and /plugins/win32/ for Windows.

Table B-1 contains information about the shared libraries for OracleAS SSO Plug-in.

Table B-1 OracleAS SSO Plug-in Shared Libraries

Platform File Name Location and Description Instructions

Platform	File Name	Location and Description	Instructions
UNIX	`oracle_proxy.so`	`oracle_proxy.so` is the OracleAS SSO Plug-in file for Sun ONE Web listener. It is located in the `/plugins/solaris/sunone` directory	To install the plug-in into the listener, place `oracle_proxy.so` in a directory to which the listener has read and execute privileges.
Windows	`oracle_osso.dll`	`oracle_osso.dll` is the OracleAS SSO Plug-in file for the IIS Web listener. It is located in the `/plugins/win32/iis` directory.	To install the plug-in into the listener, copy `oracle_osso.dll` to a directory the listener can access.
`oracle_proxy_sunone.dll`	`oracle_proxy_sunone.dll` is the OracleAS SSO Plug-in file for Sun ONE Web listener. It is located in the `/plugins/win32/sunone` directory	To install the plug-in into the listener, copy `oracle_proxy_sunone.dll` to a directory the listener has read and execute privileges.

UNIX

oracle_proxy.so

oracle_proxy.so is the OracleAS SSO Plug-in file for Sun ONE Web listener. It is located in the /plugins/solaris/sunone directory

To install the plug-in into the listener, place oracle_proxy.so in a directory to which the listener has read and execute privileges.

Windows

oracle_osso.dll

oracle_osso.dll is the OracleAS SSO Plug-in file for the IIS Web listener. It is located in the /plugins/win32/iis directory.

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

oracle_proxy_sunone.dll

oracle_proxy_sunone.dll is the OracleAS SSO Plug-in file for Sun ONE Web listener. It is located in the /plugins/win32/sunone directory

To install the plug-in into the listener, copy oracle_proxy_sunone.dll to a directory the listener has read and execute privileges.

B.4 Registering with Single Sign-On

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 sso_conf is created. sso_conf is obfuscated for security purposes. Copy it to an appropriate location so that the listener can access it.

Oracle provides a Java-based single sign-on registration tool to automatically complete this process.

B.4.1 Using the Single Sign-On Registration Tool

ORACLE_HOME/jdk/bin/java -jar ORACLE_HOME/sso/lib/ossoreg.jar [arguments]

where ORACLE_HOME is the home directory of your Oracle Application Server installation. Be sure that LD_LIBRARY_PATH is set to include $ORACLE_HOME/lib32.

Note:

You can only run this tool on the same machine where your listener resides. Also, the resulting single sign-on configuration file has to be generated directly on the same machine. Do not copy the single sign-on configuration file across different machines.

A different version ossoreg.jar could have very different command arguments. If needed, run the command using "-help" first to get the complete usage information.

B.4.2 Common Single Sign-On Registrar Command Arguments

Table B-2 lists some important common arguments for the single sign-on registrar.

Table B-2 SSO Registrar Command Arguments

Argument	Description
`-oracle_home_path`	Absolute path to the Oracle home of the Oracle Application Server installation
`-site_name`	Name of the site, typically expressed as the contiguous string `host:port`.
`-ssoDBConnect`	Single sign-on database JDBC connect string.
`-pass`	`ORASSO_PA` password.
`-mod_osso_url`	`http://<listener_hostname.domain>:port`
`-admin_id`	User name of the third-party 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`	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 name of the account used to start the third-party listener. For example, use the value of `User` specified in the `magnus.conf` for Sun ONE and `SYSTEM` for IIS. The default is the user who runs the single sign-on registrar tool.
`-sso_server_version`	Must be set to `v1.2.`
`-virtualhost`	Be sure to include this argument.
`-config_file`	Specifies a path of the final obfuscated single sign-on configuration file. It has to be set under `$ORACLE_HOME`. Default is set to: UNIX: `ORACLE_HOME/Apache/Apache/conf/osso.conf` Windows: `ORACLE_HOME/Apache\Apache\conf\osso.conf`

Example B-1 Using Common Single Sign-On Registrar Command Arguments

On UNIX:

ORACLE_HOME/jdk/bin/java -jar ORACLE_HOME/sso/lib/ossoreg.jar \
-ssoDBConnect <host.domain>:1521:iasdb -pass your_password \
-oracle_home_path ORACLE_HOME -site_name <host.domain>:7778 \
-config_mod_osso TRUE -mod_osso_url http://<host.domain>:7778 \
-u nobody -admin_id admin_name -admin_info admin@company.com \
-sso_partner_version v1.2 \
-virtualhost \
-config_file ORACLE_HOME/Apache/Apache/conf/osso/sso_conf

On Windows:

ORACLE_HOME/jdk/bin/java -jar ORACLE_HOME/sso/lib/ossoreg.jar \
-ssoDBConnect <host.domain>:1521:iasdb -pass your_password \
-oracle_home_path ORACLE_HOME -site_name <host.domain>:8080 \
-config_mod_osso TRUE -mod_osso_url http://<host.domain>:8080 \
-u SYSTEM -admin_id admin_name -admin_info admin@company.com \
-sso_partner_version v1.2 \
-virtualhost \
-config_file ORACLE_HOME/Apache/Apache/conf/osso/sso_conf

B.5 Configuring OracleAS SSO Plug-in

Create a plug-in configuration file such as osso_plugin.conf. This is the file where you define all the plug-in functionality. It can also be referred as the osso property file. The syntax is exactly the same for all third-party listeners. This file must reside in a directory that is readable by the third-party listener. This file also contains the following:

Plug-in directives such as LoginServerFile and IpCheck
A set of rules that match resources to be protected.

B.5.1 OracleAS SSO Plug-in Configuration Directives

Table B-3 lists the configuration directives for the OracleAS SSO Plug-in.

Table B-3 SSO Plug-in Configuration Directives

Directive Name Function

Directive Name	Function
`LoginServerFile`	Specifies the location of the Single Sign-On Server configuration file such as `sso.conf` that is attained from the SSO registration process. This directive gets its name from Login Server, which is now called Single Sign-On Server, for historical reasons. This is a global parameter and should not be used on a per-resource basis. That is, you must provide one and only one Single Sign-On Server configuration file. Parameter Type: string Allowable Values: the full path of your Single Sign-On Server configuration file, such as `sso_conf`. Default Value: None. You must provide the exact location of the Single Sign-On server configuration file to allow SSO plug-in to be functional. Example: `LoginServerFile=/path/config/sso_conf`
`IpCheck`	Specifies whether the SSO plug-in 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. Parameter Type: Boolean Allowable Values: true/false. Default Value: false. Example: `IpCheck=true` Note: Set `IpCheck` to false if you have a proxy server or firewall between your Sun ONE server and your clients' browser.
`HardTimeout`	Deprecated.

LoginServerFile

Specifies the location of the Single Sign-On Server configuration file such as sso.conf that is attained from the SSO registration process. This directive gets its name from Login Server, which is now called Single Sign-On Server, for historical reasons.

This is a global parameter and should not be used on a per-resource basis. That is, you must provide one and only one Single Sign-On Server configuration file.

Parameter Type: string
Allowable Values: the full path of your Single Sign-On Server configuration file, such as sso_conf.
Default Value: None. You must provide the exact location of the Single Sign-On server configuration file to allow SSO plug-in to be functional.
Example: LoginServerFile=/path/config/sso_conf

IpCheck

Specifies whether the SSO plug-in 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.

Parameter Type: Boolean
Allowable Values: true/false.
Default Value: false.
Example: IpCheck=true

Note: Set IpCheck to false if you have a proxy server or firewall between your Sun ONE server and your clients' browser.

HardTimeout

Deprecated.

B.6 Resource Protection

Use the following format to protect resources:

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

Exact matches
Longest context match plus suffix match
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 B-2 Simple Single Sign-on Configuration File, osso_plugin.conf

LoginServerFile=/path/sso_conf
<OSSO /private/hello.html>
  IpCheck = false
</OSSO>
<OSSO /private1/*>
</OSSO>
<OSSO /private2/*.jsp>
  IpCheck = true
</OSSO>

B.7 Configuring Sun ONE Listener for Single Sign-on

This section provides OracleAS SSO Plug-in configuration instructions for the Sun ONE listener on UNIX and Windows systems.

Note:

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

Open the magnus.conf file, version 6, or obj.conf, version 4, in the Sun ONE listener /config directory.

Add the load-modules line:

On UNIX:

Init fn="load-modules" shlib="/path/oracle_proxy.so" funcs="osso_init,oracle_single_sign_on,osso_redirect_service,osso_success_service"

On Windows:

Init fn="load-modules" shlib="/path/oracle_proxy_sunone.dll" funcs="osso_init,oracle_single_sign_on,osso_redirect_service,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.

Add the configuration parameters line:
```
Init fn="osso_init" osso_properties="/path/osso_plugin.conf" log_file="/path/plugin.log" log_level=error
```
where /path/osso_plugin.conf is the exact location of the plug-in configuration file you just created. Also this line can specify a log file and log level to log messages from the plug-in (optional).
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"
```
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"
```
Add the following lines where /path/ is the path of your document root. For example: /home/Sun ONE/docs/ or $docroot.
```
<Object ppath="/path/osso_login_success">
  Service fn="osso_success_service"
</Object>
```
Change the LD_LIBRARY_PATH variable in your start script to include the location of ORACLE_HOME/lib32, where ORACLE_HOME is the Oracle Application Server installation home directory.
Restart the listener.

B.7.1 Usage Notes for Sun ONE 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 Sun ONE 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.

B.8 Configuring IIS Listener for Single Sign-On

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

Edit your registry to create a new registry key named HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\IIS OSSO Adapter.
Specify the exact location of your plug-in configuration file you just created. For example: d:\osso\osso_plugin.conf, by adding this string value with the name cfg_file and a value pointing to the location of your configuration file.
Specify a log_file and log_level. This is optional.
1. Add a string value with the name log_file and the desired location of the log file. For example: d:\ossoplugin.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 emergency.
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.
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.

Stop and then start the IIS Server, ensuring that the 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.
If you want multiple Oracle installations on the same home, the ORACLE_HOME\bin PATH entry for the installation that you wish to use in conjunction with the OracleAS SSO Plug-in must appear first in your PATH.

B.9 Troubleshooting

This section describes common problems and possible reasons.

Oracle Dependency Libraries Not Found

OracleAS SSO Plug-in could not find the libraries it needs. Possible reason would be that you do not have ORACLE_HOME/lib included in your LD_LIBRARY_PATH on UNIX. On Windows, you do not have ORACLE_HOME/bin included in your PATH.

Single Sign-On Server Configuration File De-obfuscation Fails

Single sign-on server configuration file, for example, sso_conf, is obfuscated using a certain account and this account has to be the one being used to start your listener. For example, use the value of User specified in magnus.conf for Sun ONE and usually SYSTEM for IIS.

IIS Oracle Application Server OracleAS SSO Plug-in Does Not Work with HTML Authentication

OracleAS SSO Plug-in is designed to not work with other authentication modules. It is either a native listener authentication module, or third-party module.