Oracle® Application Server Single Sign-On Administrator's Guide
10g Release 2 (10.1.2) Part No. B14078-01 |
|
Previous |
Next |
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:
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.
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:
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.
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
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.
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:
|
Figure 4-1 shows what this hypothetical system looks like.
Figure 4-1 Load Balancer with Multiple Partner Applications
Setting up the system depicted in Figure 4-1 involves the following tasks:
Configuring the Oracle HTTP Servers on the Partner Application Middle Tiers
Reregistering mod_osso on the Partner Application Middle Tiers
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. |
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:
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
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.
Enter this line to load the module:
LoadModule certheaders_module libexec/mod_certheaders.so
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
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:
"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. |
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
.
To reregister mod_osso on pa2.mydomain.com
:
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
Use the Administer Partner Applications page to delete the existing entry for the partner application pa2.mydomain.com
.
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
.
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: Thessotransfer 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".
|
Restart the Oracle HTTP Server:
ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server
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.
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:
Make sure that Oracle Identity Management components are up and running—especially Oracle Internet Directory and the single sign-on server.
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
.
Create a partner application for the SSL site:
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".
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
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
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
.
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>
Update the Distributed Cluster Management Repository:
ORACLE_HOME/dcm/bin/dcmctl updateConfig -v -d
Restart the Oracle HTTP Server on the application middle tier:
ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server