Skip Headers
Oracle® Application Server Single Sign-On Administrator's Guide
10g Release 2 (10.1.2)
Part No. B14078-01
  Go To Table Of Contents
Contents
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Index
Index

Previous
Previous
Next
Next
 

4 Configuring and Administering Partner Applications

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

The chapter contains the following topics:

4.1 Registering a Partner Application: What It Means

Single sign-on partner applications are integrated with mod_osso, which is registered automatically by the OracleAS installer. In essence, partner applications are registered by way of mod_osso. Registering the module creates an entry for it in the identity management infrastructure database as well as on the application computer.

mod_osso-integrated applications are registered either by the ssoreg.sh script or by the ssoreg.bat batch file, depending upon whether the platform is UNIX or Windows. OracleAS Portal, an application enabled for single sign-on not by mod_osso but by an SDK, is registered by the ptlconfig script. All three tools are invoked by the installer. Only ssoreg.sh and ssoreg.bat are discussed here. To learn how to use ptlconfig, see the appendix devoted to this tool in Oracle Application Server Portal Configuration Guide.

4.2 Registering mod_osso

Under certain circumstances, you must reregister mod_osso manually, using the single sign-on registration tool. For instance, the host name and port number of the Oracle HTTP Server on either the infrastructure or the application tier may change after OracleAS is installed. Or SSL may be enabled after installation.

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:

4.2.1 Syntax and Parameters for ssoreg

The ssoreg.sh and ssoreg.bat scripts share the same parameters. The syntax for both commands is provided here. Before running the script, set the ORACLE_HOME environment variable to point to the directory where OracleAS is installed. See the section "Command Example" if you need help. In the example, the home directory is called gitm1.

Here is the command:

  • UNIX:

    $ORACLE_HOME/sso/bin/ssoreg.sh
    -oracle_home_path orcl_home_path
    -site_name site_name
    -config_mod_osso TRUE
    -mod_osso_url mod_osso_url
    [-virtualhost]
    [-update_mode CREATE | DELETE | MODIFY]
    [-config_file config_file_path]
    [-admin_info admin_info]
    [-admin_id adminid]
    
    
  • Windows:

    %ORACLE_HOME%\sso\bin\ssoreg.bat
    -oracle_home_path orcl_home_path
    -site_name site_name
    -config_mod_osso TRUE
    -mod_osso_url mod_osso_url
    [-virtualhost]
    [-update_mode CREATE | DELETE | MODIFY]
    [-config_file config_file_path]
    [-admin_info admin_info]
    [-admin_id adminid]
    
    

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

Omit the port number if the partner Oracle HTTP Server is listening on the default HTTP port of 80 or on the default HTTPS port of 443.

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

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.

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, ssoreg creates a file with the name osso.conf in ORACLE_HOME/Apache/Apache/conf/osso.

admin_info

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

admin_id

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

4.2.2 Command Example

This command sequence that follows shows a mod_osso instance being reregistered with the single sign-on server. In the example, the Oracle home is a directory called gitm1

  • UNIX (csh and tcsh):

    setenv ORACLE_HOME /private/oracle/gitm1
    
    $ORACLE_HOME/sso/bin/ssoreg.sh     
    -oracle_home_path $ORACLE_HOME
    -site_name myhost.mydomain.com
    -config_mod_osso TRUE
    -mod_osso_url http://myhost.mydomain.com
    
    
  • UNIX (Bourne and ksh)

    ORACLE_HOME=/private/oracle/gitm1; export ORACLE_HOME
    
    $ORACLE_HOME/sso/bin/ssoreg.sh     
    -oracle_home_path $ORACLE_HOME
    -site_name myhost.mydomain.com
    -config_mod_osso TRUE
    -mod_osso_url http://myhost.mydomain.com
    
    
  • Windows:

    set ORACLE_HOME=c:\private\oracle\gitm1
    
    %ORACLE_HOME%\sso\bin\ssoreg.bat
    -oracle_home_path %ORACLE_HOME%
    -site_name myhost.mydomain.com
    -config_mod_osso TRUE
    -mod_osso_url http://myhost.mydomain.com
    

4.2.3 Restarting the Oracle HTTP Server

After running ssoreg, restart the Oracle HTTP Server:

ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server

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

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


    Note:

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

    • Two partner application computers are deployed. There can, in fact, be any number of them.

    • The host names presented are examples only. These names may not work in an actual implementation. Substitute values that apply to your installation.


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

Figure 4-1 Load Balancer with Multiple Partner Applications

Description of ssoag034.gif follows
Description of the illustration ssoag034.gif

4.3.2 Configuration Steps

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

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

4.3.2.2 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 is 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. Add the lines that follow to httpd.conf. You can place them at the end of the file. Where they appear is unimportant.

    1. Enter this line to load the module:

      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
      

4.3.2.3 Configuring the HTTP Load Balancer

The HTTP load balancer that you use can be either hardware or software. If you elect to use the latter, you can use OracleAS WebCache.

  • Hardware Load Balancer

    If you use 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 use OracleAS Web Cache to load balance connection requests, see the following links:

4.3.2.4 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 ssoreg, the registration script. See "Registering mod_osso" earlier in the chapter to learn how to run the script. Following the example, the script creates a partner application called pa.mydomain.com.


Note:

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

This command saves your changes to the Distributed Cluster Management repository, which serves as a backup facility for OracleAS configuration files.


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:

    ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server
    
    
  6. Test the partner application, using the effective URL:

    http://pa.mydomain.com
    
    

For more information about integrating partner applications with mod_osso, see the chapter about developing applications for single sign-on in Oracle Identity Management Application Developer's Guide.

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

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. The OracleAS installer does this in the Virtual Host Context section of the ssl.conf file. The file is 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. If you need help, see the command examples in the section "Registering mod_osso".

    2. Run this command on the middle tier:

      • UNIX:

        $ORACLE_HOME/sso/bin/ssoreg.sh
        -oracle_home_path $ORACLE_HOME
        -site_name app.mydomain.com
        -config_mod_osso TRUE
        -mod_osso_url https://app.mydomain.com:4443
        -virtualhost
        -config_file $ORACLE_HOME/Apache/Apache/conf/osso/osso-https.conf
        
        
      • Windows:

        %ORACLE_HOME%\sso\bin\ssoreg.bat
        -oracle_home_path %ORACLE_HOME%
        -site_name app.mydomain.com
        -config_mod_osso TRUE
        -mod_osso_url https://app.mydomain.com:4443
        -virtualhost
        -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 this directive:

    • UNIX:

      LoadModule osso_module libexec/mod_osso.so
      
      
    • Windows:

      LoadModule osso_module modules\ApacheModuleOsso.dll
      
      
  5. In httpd.conf, found in the conf directory, add the directive that you just commented in the preceding step. In a default setup, place the directive right after LoadModule wchandshake_module libexec/mod_wchandshake.so.

  6. In ssl.conf, which is also in the conf directory, update VirtualHost to include the osso.conf file for the virtual host. Name the file osso-https.conf to avoid conflict with the default osso.conf file. Check that the file name matches the name used in the registration script.

    <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. Update the Distributed Cluster Management Repository:

    ORACLE_HOME/dcm/bin/dcmctl updateConfig -v -d
    
    
  8. Restart the Oracle HTTP Server on the application middle tier:

    ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server
    
    
  9. Test both the SSL and the non-SSL site.