4 Configuring and Administering Partner Applications

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]
  [-remote_midtier]
  [-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]
  [-remote_midtier]
  [-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.

remote_midtier

Specifies that the mod_osso partner application to be registered is at a remote midtier. Specify this option only when the mod_osso partner application to be configured is at a different ORACLE_HOME, and the OracleAS Single Sign-On server runs locally at the current ORACLE_HOME.

config_file

Location of the osso.conf file. The path is typically in the form of <ORACLE_HOME_PATH>/Apache/Apache/conf/osso/<filename> or a subdirectory under it. This parameter is optional except when -virtualhost or -remote_midtier is specified.

• when -virtualhost is specified, this is the location of the osso.conf file for the virtual host if one is being configured.

  For example, it may be specified as the following:

  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.

• when -remote_midtier is specified, the partner application is at a remote midtier. The resulting osso.conf configuration file can then be copied or sent using ftp to the remote midtier.

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.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 "Figure 4-1 Load Balancer with Multiple Partner Applications"

4.3.2 Configuration Steps

Setting up the system depicted 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

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