4
Configuring and Administering Partner Applications

This chapter explains how to enable partner applications for single sign-on. This process involves registering mod_osso, the authentication module for the Oracle HTTP Server, with the single sign-on server. See "Partner Applications" in Chapter 1 for a definition of partner applications.

The chapter contains the following topics:

• Registering a Partner Application: What It Means

• Registering mod_osso

• Deploying Multiple Partner Applications with a Load Balancer

• Configuring mod_osso with Virtual Hosts

Registering a Partner Application: What It Means

Single sign-on partner applications are registered automatically by the OracleAS installer. Registering the application creates an entry for it in the identity management infrastructure database and configures registration on the partner application computer.

mod_osso-integrated applications are registered by the ossoreg.jar tool. OracleAS Portal, an SDK-integrated application, is registered by ptlasst. Both tools are invoked by the installer. Only the former is discussed here. See Portal documentation for a discussion of the latter.

Registering mod_osso

Under certain circumstances, you must reregister mod_osso manually, using the single sign-on registration tool. These circumstances are as follows:

• The host name and port number of the Oracle HTTP Server are changed after OracleAS is installed

• The osso.conf file is deleted or corrupted

• SSL is enabled on the single sign-on server after OracleAS is installed

In all three cases, running the single sign-on registration tool updates the mod_osso registration record in osso.conf. The tool generates this file whenever it runs.

This section contains the following topics:

• Syntax and Parameters for ossoreg.jar

• Command Example

• Restarting the Oracle HTTP Server

Syntax and Parameters for ossoreg.jar

Use the ossoreg.jar tool to register an application. Run the following command:

$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar
-oracle_home_path orcl_home_path
-site_name site_name
-config_mod_osso TRUE
-mod_osso_url mod_osso_url
-u userid
[-virtualhost]
[-update_mode CREATE | DELETE | MODIFY]
[-config_file config_file_path]
[-admin_info admin_info]
[-admin_id adminid]

A description of the parameters passed to the tool follows.

oracle_home_path

Absolute path to the Oracle home.

site_name

Name of the site--typically, the effective host name and port of the partner application. For example, application.mydomain.com.

config_mod_osso

If set to TRUE, this parameter indicates that the application being registered is mod_osso. You must include config_mod_osso for osso.conf to be generated.

mod_osso_url

The effective URL of the partner application. This is the URL that is used to access the partner application. The value should be specified in this URL format:

http://oracle_http_host.domain:port

For example:

http://application.mydomain.com:7777

u

The user name that will start the Oracle HTTP Server. In UNIX, this name is usually "root." On Windows NT/2000, it is SYSTEM. The parameter u is mandatory.

virtualhost

Optional. Include this parameter only if you are registering an Oracle HTTP virtual host with the single sign-on server. Omit the parameter if you are not registering a virtual host.

If you are creating an HTTP virtual host, use the httpd.conf file to fill in the following directive for each protected URL:

<VirtualHost host_name>
  OssoConfigFile $ORACLE_HOME/Apache/Apache/conf/osso/host_name/osso.conf
  OssoIpCheck off
  #<Location /your_protected_url>
  #  AuthType basic
  #  Require valid-user
  #</Location>
  #Other configuration information for the virtual host
</VirtualHost>

If, on the other hand, you are creating an HTTPS virtual host, use the ssl.conf file to fill in the same directive. Note that the commented lines must be uncommented before the application is deployed. Both httpd.conf and ssl.conf are in $ORACLE_HOME/Apache/Apache/conf.

After creating a virtual host, run this command to update the Distributed Cluster Management schema:

$ORACLE_HOME/dcm/bin/dcmctl updateConfig -v -d

config_file

Location of the osso.conf file for the virtual host if one is being configured. It may, for example, be $ORACLE_HOME/Apache/Apache/conf/osso/virtual_host_name/osso.conf.

This parameter is mandatory if you are registering a virtual host. If you omit config_file, the assumption is that you are registering a nonvirtual host. In this case, ossoreg.jar creates a file with the name osso.conf in $ORACLE_HOME/Apache/Apache/conf/osso.

update_mode

Optional. Creates, deletes, or modifies the partner registration record. CREATE, the default, generates a new record. DELETE removes the existing record. MODIFY deletes the existing record and then creates a new one.

admin_info

Optional. User name of the mod_osso administrator. If you omit this parameter, the Administrator Information field on the Edit Partner Application page is left blank.

admin_id

Optional. Any additional information, such as e-mail address, about the administrator. If you omit this parameter, the Administrator E-mail field on the Edit Partner Application page is left blank.

Command Example

This command sequence shows a mod_osso instance being reregistered with the single sign-on server:

• UNIX:

  setenv $ORACLE_HOME /private/oracle/gitm1
  
  setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$ORACLE_HOME/lib
  
  $ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar -oracle_
  home_path $ORACLE_HOME -site_name portal.mydomain.com -config_mod_osso TRUE 
  -mod_osso_url http://portal.mydomain.com -u root
  
  

• Windows NT/2000:

  set ORACLE_HOME=c:\private\oracle\gitml
  
  set PATH=%PATH%;%ORACLE_HOME%\bin;%ORACLE_HOME%\lib
  
  %ORACLE_HOME%\jdk\bin\java -jar %ORACLE_HOME%\sso\lib\ossoreg.jar -oracle_
  home_path %ORACLE_HOME% -site_name portal.mydomain.com -config_mod_osso TRUE 
  -mod_osso_url http://portal.mydomain.com -u SYSTEM
  

Restarting the Oracle HTTP Server

After running ossoreg.jar, restart the Oracle HTTP Server. For instructions, see "Stopping and Starting the Oracle HTTP Server" in Chapter 2.

Deploying Multiple Partner Applications with a Load Balancer

You can configure two or more partner application instances in a highly available deployment by placing a load balancer in front of them. The load balancer publishes a single address for partner applications while providing a farm of application servers that actually service requests. The HTTP load balancer can detect when one of the Oracle HTTP Server instances has failed and can then fail over requests to another instance.

The usage scenario presented here takes you through the steps required to configure partner applications with a load balancer.

Usage Scenario

This scenario assumes the following hypothetical configurations:

• There are two partner application computers: pa1.mydomain.com and pa2.mydomain.com. Both application servers listen on non-SSL port 7777.

• The partner application computers are configured to use the single sign-on server located at sso.mydomain.com.

• The effective host name of the partner application published to users is pa.mydomain.com. An HTTP load balancer is configured to listen at this address, on port 80. It load balances and fails over user requests between pa1.mydomain.com and pa2.mydomain.com.

• The single sign-on server, directory server, and identity management infrastructure database are located at sso.mydomain.com.

  Notes: In this scenario, the load balancer is listening on port 80, a non-SSL port number. If the load balancer is configured to use SSL to interact with the browser, a different port number must be selected. The default SSL port number is 443. In this scenario, two partner application computers are shown. There can, in fact, be any number of them.

Figure 4-1 shows what this hypothetical system looks like.

Figure 4-1 Load Balancer with Multiple Partner Applications

Text description of the illustration ssoag034.gif

Configuration Steps

Setting up the system presented in Figure 4-1 involves the following tasks:

• Installing the Partner Applications

• Configuring the Oracle HTTP Servers on the Partner Application Middle Tiers

• Configuring the HTTP Load Balancer

• Reregistering mod_osso on the Partner Application Middle Tiers

Installing the Partner Applications

Install the partner applications on pa1.mydomain.com and pa2.mydomain.com. When prompted by the installer for a directory location, choose the server located at sso.mydomain.com.

Note: The partner application mentioned here can be any Web-based application. In a simple case, it can be an OracleAS core installation that includes the Oracle HTTP Server and OC4J. Consult application-specific installation documentation.

Configuring the Oracle HTTP Servers on the Partner Application Middle Tiers

When a load balancer is placed between the user and the Oracle HTTP servers on the OracleAS middle tier, the effective URL of the partner application changes. The configuration file httpd.conf on both middle tiers must be modified to reflect this change. This file can be found at $ORACLE_HOME/Apache/Apache/conf.

Complete the following steps:

1. Modify the Oracle HTTP servers at the OracleAS middle tier to listen at the externally published name, which, in the scenario presented, is pa.mydomain.com.

   Add the following lines to the httpd.conf file on pa1.mydomain.com and pa2mydomain.com:

   ServerName pa.mydomain.com
   Port 80
   

   Note: If multiple ports are listed in httpd.conf, the effective port must appear last.

2. If you configure SSL between the browser and the load balancer, and the SSL connection terminates at the load balancer, configure mod_certheaders on both pa1.mydomain.com and pa2.mydomain.com. This module enables the Oracle HTTP Server to treat requests that it receives over HTTP as SSL requests. The sequence is as follows:
   1. Enter this line in httpd.conf:

      LoadModule certheaders_module libexec/mod_certheaders.so
      
      

   2. If you are using OracleAS Web Cache as a load balancer, enter this line:

      AddCertHeader HTTPS
      
      

   If you are using a hardware load balancer, enter this line:

   SimulateHttps on
   
   

   You can add steps a and b to the end of httpd.conf. Just where they appear in the file is unimportant.

Configuring the HTTP Load Balancer

The HTTP load balancer that you use can be hardware such as BigIP, Alteon, or Local Director or software such as OracleAS Web Cache.

• Hardware Load Balancer

  If you are using a hardware load balancer, configure one pool of real servers with the addresses pa1.mydomain.com and pa2.mydomain.com. Configure one virtual server with the address pa.mydomain.com. This virtual server is the external interface of the load balancer. For instructions, consult the documentation provided by your load balancer vendor.

• Software Load Balancer

  If you are using OracleAS Web Cache to load balance connection requests, see the following links:

  • "Leveraging Oracle Identity Management Infrastructure" in Oracle Application Server Web Cache Administrator's Guide.

  • "Routing Single Sign-On Server Requests," also in Oracle Application Server Web Cache Administrator's Guide.

    Note: For optimal performance, use a hardware load balancer.

Reregistering mod_osso on the Partner Application Middle Tiers

On both partner application instances, reregister mod_osso as the partner application pa.mydomain.com.

To reregister mod_osso on pa1.mydomain.com, run the registration script. In the example that follows, be sure to substitute values appropriate to your installation. The script creates a partner application called pa.mydomain.com.

$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar
-oracle_home_path orcl_home_path
-site_name site_name
-config_mod_osso TRUE
-mod_osso_url mod_osso_url
-u userid
[-virtualhost virtual_host_name]
[-update_mode CREATE | DELETE | MODIFY]
[-config_file config_file_path]
[-admin_id adminid]
[-admin_info admin_info]

See "Registering mod_osso" for a command example and a description of command parameters.

Note: If you are configuring the partner application computers for Distributed Cluster Management, omit the following steps. Instead, run this command on pa1.mydomain.com: $ORACLE_HOME/dcm/bin/dcmctl updateConfig -v -d

To reregister mod_osso on pa2.mydomain.com:

1. On pa2.mydomain.com, log in to the single sign-on administration pages as the single sign-on administrator. Be sure to log in to this URL:

   http://sso.mydomain.com/pls/orasso
   
   

2. Use the Administer Partner Applications page to delete the existing entry for the partner application pa2.mydomain.com.

3. Copy the osso.conf file from pa1.mydomain.com. Make sure that you use binary mode if you FTP the file. The default location of the file is $ORACLE_HOME/Apache/Apache/conf/osso.

4. Synchronize the Distributed Cluster Management repository with the file copy. You do this by running the following command on pa2.mydomain.com:

   $ORACLE_HOME/Apache/Apache/bin/ssotransfer $ORACLE_
   HOME/Apache/Apache/conf/osso/osso.conf
   

   Note: The ssotransfer command should not be used to synchronize the Distributed Cluster Management repository with the mod_osso configuration file created for a virtual host. To learn how to register mod_osso for a virtual host, see "Configuring mod_osso with Virtual Hosts".

5. Restart the Oracle HTTP Server. For instructions, see "Stopping and Starting the Oracle HTTP Server" in Chapter 2.

6. Test the partner application using the effective URL:

   http://pa.mydomain.com
   
   

For more information about integrating partner applications with mod_osso, see "Developing Single Sign-On-Enabled Applications" in Oracle Application Server Single Sign-On Application Developer's Guide.

Configuring mod_osso with Virtual Hosts

Some deployments may require more than one Web site to be deployed on a single Oracle HTTP Server. An application may, for example, have to be available both over HTTP and HTTPS. In the scenario that follows, an SSL virtual host is configured to be protected by mod_osso. Although the virtual host is an SSL host, the scenario applies to any virtual host.

The scenario assumes the following conditions:

• The host name of the application middle tier is app.mydomain.com.

• The middle tier is already configured as a non-SSL partner application. This is typically done by the OracleAS Installer when the application is first installed.

• The default SSL port number of the application middle tier is 4443.

To configure app.mydomain.com as an SSL virtual host:

1. Make sure that Oracle identity management components are up and running--especially Oracle Internet Directory and the single sign-on server.

2. Check that app.mydomain.com has been defined as an SSL virtual host. In release 9.0.4, the OracleAS installer does this in the VirtualHost section of the ssl.conf file. In release 9.0.2, the installer defines an SSL virtual host in the VirtualHost section of httpd.conf. Both files are in $ORACLE_HOME/Apache/Apache/conf.

3. Create a partner application for the SSL site:
   1. Make sure that the Oracle home of the middle tier is set with the correct path:
      • UNIX:

        setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$ORACLE_HOME/lib
        
        

      • Windows NT/2000

        set PATH=%PATH%;%ORACLE_HOME%\bin;%ORACLE_HOME%\lib
        

   2. For a release 9.0.4 middle tier, run the following command:

      $ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar -oracle_
      home_path $ORACLE_HOME -site_name app.mydomain.com -config_mod_osso TRUE 
      -mod_osso_url https://app.mydomain.com:4443 -u root -virtualhost 
      -config_file $ORACLE_HOME/Apache/Apache/conf/osso/osso-https.conf
      
      

   3. For a release 9.0.2 middle tier, go to $ORACLE_HOME/Apache/Apache/conf; then run the following command:

      $ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar 
      -virtualhost -site_name https://app.mydomain.com -oracle_home_path 
      $ORACLE_HOME -success_url https://app.mydomain.com:4443/osso_login_
      success -logout_url https://app.mydomain.com:4443/osso_logout_success 
      -cancel_url https://app.mydomain.com:4443/ -home_url 
      https://app.mydomain.com:4443/ -config_mod_osso TRUE -u root -sso_
      server_version v1.2 -config_file  $ORACLE_
      HOME/Apache/Apache/conf/osso/osso-https.conf
      
      

4. Go to the mod_osso.conf file at $ORACLE_HOME/Apache/Apache/conf. Once there, comment out this line:

   LoadModule osso_module libexec/mod_osso.so
   
   

5. In httpd.conf, add the directive that follows right after LoadModule wchandshake_module libexec/mod_wchandshake.so with a default setup:

   LoadModule osso_module libexec/mod_osso.so
   
   

6. Update VirtualHost to include the mod_osso file for the virtual host. Recall that, for SSL virtual hosts, this directive is configured in ssl.conf in release 9.0.4 and in httpd.conf in release 9.0.2.

   <VirtualHost _default_:4443>
   .
   .
   .
   OssoConfigFile $ORACLE_HOME/Apache/Apache/conf/osso/osso-https.conf
   OssoIpCheck off
   <Location /your_protected_url_for_the virtual site>
     AuthType basic
     Require valid-user
   </Location>
   .
   .
   .
   </VirtualHost>
   
   

7. Restart the Oracle HTTP Server on the application middle tier. See "Stopping and Starting the Oracle HTTP Server" in Chapter 2, for instructions.

8. Test both the SSL and the non-SSL site.