Skip Headers
Oracle® Application Server Administrator's Guide
10g Release 2 (10.1.2)
B13995-06
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

14 Using the SSL Configuration Tool

This chapter describes how to use the SSL Configuration Tool. The following topics are covered:

14.1 Overview

The SSL Configuration Tool is designed to be run after a successful Oracle Application Server installation to automate many of the manual steps currently required for securing HTTP. This means that all Oracle homes you plan to install are successfully installed. If you have a topology where both an OracleAS Infrastructure and middle tier are present, be sure to run the SSL Configuration Tool against the OracleAS Infrastructure first, then the middle tier.


Note:

The SSL Configuration Tool is only supported for Oracle Application Server 10g Release 2 (10.1.2).

If you install Oracle Application Server and choose to make some configuration changes before running the SSL Configuration Tool, you should run the tool and then refer to the SSL Configuration Tool log files to verify that your changes were not overwritten. The SSL Configuration Tool creates log files in the directory from which the tool is run. A new log file is created each time the tool is run. For these reasons, it is suggested that you create a separate directory from which you can run the SSL Configuration Tool.

If you encounter any problems, you should run the SSL Configuration Tool with the -rollback option to revert back to your configuration environment prior to running the tool. See Section 14.6 for information about troubleshooting the SSL Configuration Tool.

The SSL Configuration Tool is available with any Oracle Application Server installation type. OracleAS Infrastructure installations are the only installation type that support SSL configuration during the installation. This option is available on one of the installation screens. See Oracle Application Server Installation Guide for more information.


Note:

OracleAS Web Cache is the only standalone type supported by the SSL Configuration Tool. All other standalone types (for example, Apache) are not supported.

In some cases, the SSL Configuration Tool cannot completely configure SSL for your specific topology. When this occurs, you should refer to the appropriate component documentation for instructions on how to complete your SSL configuration manually. For some links to documentation containing manual steps, see Section 14.5, "Manual Steps".

14.2 Understanding SSL Termination

Oracle Application Server ships Oracle HTTP Server (OHS) as the web server software application. It can be configured to serve HTTP requests directly from the Internet. Optionally, OracleAS Web Cache can be installed in front of Oracle HTTP Server to improve performance and scalability. Many customers choose to further increase scalability by putting a load balancer (LBR) in front of both OracleAS Web Cache and Oracle HTTP Server, as illustrated in Figure 14-1.

Figure 14-1 Common Oracle Application Server Topology

Topology for Configuring SSL to Load Balancer for SSO/DAS
Description of "Figure 14-1 Common Oracle Application Server Topology"

HTTPS requests can be allowed to reach the load balancer, OracleAS Web Cache, or Oracle HTTP Server. Any one of these components can be configured as the SSL termination point, while any component before the termination point will be SSL secured. For example, in Figure 14-1, if OracleAS Web Cache is configured as the termination point, then the load balancer would be SSL secured.

SSL Termination at the Load Balancer

HTTPS requests are terminated at the load balancer in the following scenarios:

With SSL accelerator turned on, HTTPS traffic will terminate at the load balancer, meaning that the load balancer performs decryption and sends plain HTTP traffic to either OracleAS Web Cache or Oracle HTTP Server.

SSL Termination at OracleAS Web Cache

HTTPS requests are terminated at OracleAS Web Cache in the following scenarios:

The load balancer without SSL accelerator turned on sends HTTPS traffic to OracleAS Web Cache. OracleAS Web Cache, in turn, configured with SSL termination, performs decryption and sends plain HTTP traffic to Oracle HTTP Server.

SSL Termination at Oracle HTTP Server

HTTPS requests are terminated at Oracle HTTP Server in the following scenarios:

The load balancer without SSL accelerator and OracleAS Web Cache without HTTPS termination will both accept and forward HTTPS requests. When these requests reach Oracle HTTP Server with SSL termination configured, Oracle HTTP Server will perform decryption and send plain HTTP traffic to other Oracle Application Server components.

14.3 Command Line Interface

This section describes how to use the SSLConfigTool command. It contains the following sections:

14.3.1 Where Can I Find the SSL Configuration Tool?

The SSLConfigTool executable is located in the ORACLE_HOME/bin directory.

14.3.2 Syntax

The SSLConfigTool command is used as follows:

SSLConfigTool ( -config_w_prompt
               | -config_w_file <input_file_name>
               | -config_w_default
               | -rollback )
               [-dry_run]
               [-wc_for_infra]
               [-secure_admin]
               [-opwd <orcladmin_pwd>]
               [-ptl_dad <dad_name>]
               [-ptl_inv_pwd <ptl_inv_pwd>]

Table 14-1 describes the command line options for the SSLConfigTool command.

Table 14-1 SSL Configuration Tool Command Line Options

Parameter Description

-config_w_prompt

Run in interactive mode.

-config_w_file <input_file_name>

Run in silent mode using the values specified in the <input_file_name> file. This input file should be an XML file. For more information, see Section 14.3.3, "Configuration File for Silent Mode".

-config_w_default

Run in silent mode using the values specified in the portlist.ini and ias.properties files.

-rollback

Revert to the prior state before the command was last run. SSO registration will be done using virtual host and port.

-dry_run

Print the steps without implementing them.

-wc_for_infra

Forces an OracleAS Web Cache to be used as a load balancer for an infrastructure environment.

-secure_admin

Secure the OracleAS Web Cache and Enterprise Manager administration ports (the ports used to display Application Server Control Console).

-opwd <orcladmin_pwd>

Set the Oracle administrator password. This parameter is required.

-ptl_dad <dad-name>

Set the Portal dad name. If no name is specified, the default "portal" will be used.

-ptl_inv_pwd <ptl_inv_pwd>

Set the Portal invalidation password used to send invalidation to OracleAS Web Cache.

This parameter is required if you installed OracleAS Portal. If you are running SSLConfigTool with the -rollback parameter, this parameter is not required.


Note that the -config_w_prompt, -config_w_file, -config_w_default, and -rollback parameters are mutually exclusive; only one can be used with the SSLConfigTool command.

If you choose to run the tool interactively with the -config_w_prompt parameter, you will be prompted for the appropriate information one question at a time.

If you choose to run the tool silently by specifying a configuration file with the -config_w_file parameter, you should read Section 14.3.3, "Configuration File for Silent Mode" for information about constructing a valid input file.

14.3.3 Configuration File for Silent Mode

If you run SSLConfigTool in silent mode, you must provide an input file describing the components in the deployment topology.

The input file contains two main sections, <mid_tier> and <infra>, inside the <sslconfig> element:

<sslconfig>
   <mid_tier>
      ...
   </mid_tier>
   <infra>
      ...
   </infra>
</sslconfig>

The <mid_tier> and <infra> elements contain information the SSL Configuration Tool needs to know about this Oracle Application Server instance. The content inside both the <mid_tier> and <infra> elements must look like this:

<virtual_address ssl="on|off"
                 host="..."
                 port="..."
                 inv_port="..."
                 ssl_terminate="lbr|wc|ohs" />
<lbr loopback_port="..." />
<wc wallet="..." os_wallet="..."
<ohs wallet="..." />
   <servers>
      <server host="..." port="..." />
   </servers>
</ohs>

Each element is described in further detail in the remainder of this section. All elements and attributes have default values assigned in either the portlist.ini or ias.properties file.

<virtual_address> Element

This is a required element used to describe this virtual host. Its attributes are summarized in Table 14-2.

Table 14-2 Attributes for the <virtual_address> Element

Attribute Description

ssl

Required attribute. Sets whether SSL is on or off. Valid values are:

  1. on (enable HTTPS)

  2. off (enable HTTP)

host

Required attribute. Virtual host name.

port

Required attribute. Virtual host port number.

inv_port

Optional attribute. Specify the OracleAS Web Cache invalidation port. This attribute is only relevant for OracleAS Portal installations.

ssl_terminate

Required attribute when the ssl value is "on." Sets the SSL termination point. All components up to the specified termination point will be secured in SSL. Valid values are:

  • lbr (load balancer)

  • wc (OracleAS Web Cache)

  • ohs (Oracle HTTP Server)

For more information, see Section 14.2, "Understanding SSL Termination".


<lbr> Element

This element is required if there is a load balancer present in your topology. The <lbr> element takes one attribute, loopback_port, which is used to specify the loopback port number.

<wc> Element

This element is required if there is an OracleAS Web Cache present in your topology. The <wc> element takes the following optional attributes:

  • wallet—Location of the OracleAS Web Cache front-end wallet (used to communicate with an external browser).

  • os_wallet—Location of the OracleAS Web Cache back-end wallet (used to communicate with Oracle HTTP Server).

  • loopback_port—Loopback port number when there is no load balancer present in your topology and OracleAS Web Cache is acting as the load balancer. This attribute is valid for OracleAS Portal installations only.

See Section 14.3.4 for default wallet locations.

<ohs> Element

This element is used in conjunction with the <wc> element; if there is no OracleAS Web Cache present in your topology, then this element is not needed. In addition, this element is also not needed if OracleAS Web Cache and Oracle HTTP Server are installed on the same machine, and OracleAS Web Cache maps to the Oracle HTTP Server in the same Oracle home.

The <ohs> element takes one optional attribute, wallet, which is used to specify the location of the Oracle HTTP Server (Apache) wallet. See Section 14.3.4 for default wallet locations.

Additionally, the <ohs> element requires one <servers> element for each Oracle HTTP Server in the topology. The <servers> element takes the following attributes:

  • host—Name of the Oracle HTTP Server.

  • port—Oracle HTTP Server listen port.

There must be one <servers> element for each Oracle HTTP Server in your topology.

14.3.4 Default Wallet Locations

Default wallet locations are listed in Table 14-3.

Table 14-3 Default Wallet Locations

Wallet Default Location (File Path)

Web Cache Front-End Wallet

ORACLE_HOME/webcache/wallets/default

Web Cache Back-End Wallet

ORACLE_HOME/webcache/wallets/default

Apache Wallet

ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default


To specify your own wallet location, you must supply either the absolute path from the root (/) directory or a relative path from the Oracle home directory.

The following are some examples of an absolute path:

/etc/wallets/absolute/path/to/my/companys/wallet (UNIX)
C:\product\OracleAS\10.1.2\absolute\path\to\my\companys\wallet (Windows)

The following are some examples of a relative path:

%ORACLE_HOME%/relative/path/to/my/companys/wallet (UNIX)
%ORACLE_HOME%\relative\path\to\my\companys\wallet (Windows)

14.4 Common SSL Configuration Scenarios

This section describes how to use the SSL Configuration Tool for the following common topologies:

14.4.1 Configuring SSL to Load Balancer for OracleAS Single Sign-On/Oracle Delegated Administration Services

This configuration enables SSL at the load balancer for OracleAS Single Sign-On (SSO)/Oracle Delegated Administration Services (DAS). The load balancer acts as the front end for the SSO server (Figure 14-2).

SSL terminates at load balancer, meaning that the load balancer performs decryption and sends plain HTTP traffic directly to Oracle HTTP Server for infrastructure installations.

Figure 14-2 Topology and Summary of Changes

Description of Figure 14-2  follows
Description of "Figure 14-2 Topology and Summary of Changes"

14.4.1.1 What It Does

The SSL Configuration Tool performs the following to enable HTTPS:

  • Change the httpd.conf file to refer to the load balancer's host and port.

  • Run the ssocfg script to configure the SSO server.

  • Run the ssoreg script to re-register mod_osso in the current ORACLE_HOME.

  • Modify the DAS operation URL in the Oracle Internet Directory.

  • Modify the targets.xml file.

If you have multiple SSO/DAS homes in a high availability environment, you must run SSLConfigTool in each home, then perform step number 6 in the list of manual steps in Section 14.5.

14.4.1.2 Running the SSL Configuration Tool

Run the following command to configure SSL for this scenario. The name of the input configuration file is sslct_config.xml and the Oracle administrator password is "welcome1."

SSLConfigTool -config_w_file sslct_config.xml -opwd welcome1

The following are the contents of the sslct_config.xml input configuration file:

<sslconfig>
   <mid_tier>
      <virtual_address ssl="on"
                       host="mylogin.us.oracle.com"
                       port="443"
                       ssl_terminate="lbr" />
   </mid_tier>
</sslconfig>

To configure SSL interactively, use the -config_w_prompt option, as shown in the following example. The answers to the questions are in bold:

SSLConfigTool -config_w_prompt -opwd welcome1

Welcome to the OracleAS SSL Configuration Tool.
Below you will be guided with a series of questions.
If a question has the default answer,
the answer will be enclosed inside [square brackets].
Let's start now...

Do you want to configure your site to accept browser requests using SSL protocol? [y]: y
What is the virtual host name for your site? [mylogin.us.oracle.com]: mylogin.us.oracle.com
What is the virtual port number for your site? [4443]: 443
Does your site have an external load balancer (LBR)?
Note: Do NOT include OracleAS Web Cache as LBR here. [y]: y
Does your site have OracleAS Web Cache? [y]: n
Does your Oracle HTTP Server (OHS) accept requests in SSL protocol? [y]: n
You have supplied all the information. Are you ready to continue? [y]: y

14.4.2 Configuring SSL to Load Balancer for OracleAS Portal

This configuration enables SSL for Portal. A load balancer acts as the front end for two Portal middle tiers, each with its own OracleAS Web Cache and HTTP Server instances in the same ORACLE_HOME. In addition, the two OracleAS Web Caches have been manually clustered together (Figure 14-3).

SSL terminates at load balancer, meaning that the load balancer performs decryption and sends plain HTTP traffic directly to OracleAS Web Cache and then to Oracle HTTP Server.

Figure 14-3 Topology and Summary of Changes

Description of Figure 14-3  follows
Description of "Figure 14-3 Topology and Summary of Changes"

14.4.2.1 What It Does

The SSL Configuration Tool performs the following to enable HTTPS:

  • Change the httpd.conf file to refer to the load balancer's host and port.

  • Run the ssoreg script to re-register mod_osso in the current ORACLE_HOME.

  • Modify the iasconfig.xml file and then run the ptlconfig script against it.

  • Modify the webcache.xml file to create a new site, do the proper site-to-server mappings, and point to any user-specified wallet locations.

  • Modify the targets.xml file.

If you have multiple OracleAS Portal instances, you must run SSLConfigTool for each Portal instance, then perform steps 2, 3, 4, and 6 in the list of manual steps in Section 14.5. If you are using OracleAS Wireless with OracleAS Portal, you must also perform step 5.

14.4.2.2 Running the SSL Configuration Tool

Run the following command to configure SSL for this scenario. The name of the input configuration file is sslct_config.xml, the Oracle administrator password is "welcome1," and the Portal invalidation password is also "welcome1."

SSLConfigTool -config_w_file sslct_config.xml -opwd welcome1 -ptl_inv_pwd welcome1

The following shows the contents of the sslct_config.xml input configuration file:

<sslconfig>
   <mid_tier>
      <virtual_address ssl="on"
                       host="mylogin.us.oracle.com"
                       port="443"
                       inv_port="4001"
                       ssl_terminate="lbr" />
   <lbr loopback_port="7780" />
   <wc/>
   <ohs>
      <servers>
         <server host="ohs6.us.oracle.com" port="7778" />
         <server host="ohs8.us.oracle.com" port="7778" />
      </servers>
   </ohs>
   </mid_tier>
</sslconfig>

To configure SSL interactively, use the -config_w_prompt option, as shown in the following example. The answers to the questions are in bold:

SSLConfigTool -config_w_prompt -opwd welcome1 -ptl_inv_pwd welcome1

Welcome to the OracleAS SSL Configuration Tool.
Below you will be guided with a series of questions.
If a question has the default answer,
the answer will be enclosed inside [square brackets].
Let's start now...

Do you want to configure your site to accept browser requests using SSL protocol? [y]: y
What is the virtual host name for your site? [mylogin.us.oracle.com]: mylogin.us.oracle.com
What is the virtual port number for your site? [4443]: 443
What is the invalidation port number your Portal uses? [4001]: 4001
Does your site have an external load balancer (LBR)?
Note: Do NOT include OracleAS Web Cache as LBR here. [y]: y
Does your site have OracleAS Web Cache? [y]: y
Does your Web Cache accept requests in SSL protocol? [y]: n
Does your Oracle HTTP Server (OHS) accept requests in SSL protocol? [y]: n
What is the Portal loop-back port in LBR or Web Cache? [7780]: 7780
How many OHS instances does your Web cache route traffic to? [1]: 2
Please enter host name for OHS #1: ohs6.us.oracle.com
Please enter port number for OHS #1: 7778
Please enter host name for OHS #2: ohs8.us.oracle.com
Please enter port number for OHS #2: 7778
You have supplied all the information. Are you ready to continue? [y]: y

14.4.2.3 For More Information

For detailed information about configuring SSL in this scenario, see:

14.4.3 Configuring SSL to Oracle HTTP Server for Oracle HTTP Server/Oracle Application Server Containers for J2EE

This configuration enables SSL for OHS/OC4J. Two Oracle HTTP Servers are configured in a high availability environment and both are configured to accept HTTPS requests from a front-end load balancer (Figure 14-4).

SSL terminates at Oracle HTTP Server, meaning that Oracle HTTP Server performs decryption and sends plain HTTP traffic directly to other Oracle Application Server components.

Figure 14-4 Topology and Summary of Changes

Description of Figure 14-4  follows
Description of "Figure 14-4 Topology and Summary of Changes"

14.4.3.1 What It Does

The SSL Configuration Tool does the following to enable HTTPS:

  • Change the opmn.xml file to enable Oracle HTTP Server.

  • Change the ssl.conf file to point to the specified wallet location.

  • Run the ssoreg script to re-register mod_osso in the current ORACLE_HOME if SSO is enabled.

For multiple Oracle Application Server Containers for J2EE (OC4J) homes in a high availability environment, you must run SSLConfigTool in each home, then perform step number 6 in the list of manual steps in Section 14.5 if OC4J is protected by OracleAS Single Sign-On.

14.4.3.2 Running the SSL Configuration Tool

Run the following command to configure SSL for this scenario. The name of the input configuration file is sslct_config.xml and the Oracle administrator password is "welcome1."

SSLConfigTool -config_w_file sslct_config.xml -opwd welcome1

The following shows the contents of the sslct_config.xml input configuration file:

<sslconfig>
   <mid_tier>
      <virtual_address ssl="on"
                       host="mylogin.us.oracle.com"
                       port="443"
                       ssl_terminate="ohs" />
   </mid_tier>
</sslconfig>

To configure SSL interactively, use the -config_w_prompt option, as shown in the following example. The answers to the questions are in bold:

SSLConfigTool -config_w_prompt -opwd welcome1

Welcome to the OracleAS SSL Configuration Tool.
Below you will be guided with a series of questions.
If a question has the default answer,
the answer will be enclosed inside [square brackets].
Let's start now...

Do you want to configure your site to accept browser requests using SSL protocol? [y]: y
What is the virtual host name for your site? [mylogin.us.oracle.com]: mylogin.us.oracle.com
What is the virtual port number for your site? [4443]: 443
Does your site have an external load balancer (LBR)?
Note: Do NOT include OracleAS Web Cache as LBR here. [y]: y
Does your site have OracleAS Web Cache? [y]: n
Do you want to supply your own wallet location for OHS? [n]: n
You have supplied all the information. Are you ready to continue? [y]: y

14.4.3.3 For More Information

For detailed information about configuring SSL in this scenario, see:

  • "Section 1.2, A Standard Enterprise Deployment for J2EE Applications: myJ2EECompany.com" in the Oracle Application Server Enterprise Deployment Guide.

  • "Chapter 3, Configuring the Application Infrastructure for myJ2EECompany.com" in the Oracle Application Server Enterprise Deployment Guide.

14.4.4 Configuring SSL to OracleAS Web Cache for J2EE

This scenario enables SSL for J2EE in smaller Oracle Application Server shops, where there is no load balancer and OracleAS Web Cache is used as the load balancer (Figure 14-5).

SSL terminates at OracleAS Web Cache, meaning that OracleAS Web Cache performs decryption and sends plain HTTP traffic directly to Oracle HTTP Server. Alternatively, if OracleAS Web Cache is not used, then SSL would terminate at Oracle HTTP Server.

Figure 14-5 Topology and Summary of Changes

Description of Figure 14-5  follows
Description of "Figure 14-5 Topology and Summary of Changes"

14.4.4.1 What It Does

The SSL Configuration Tool does the following to enable HTTPS:

  • Change the opmn.xml file to enable Oracle HTTP Server.

  • Change the ssl.conf file to point to the load balancer's host and port.

  • Run the ssoreg script to re-register mod_osso in the current ORACLE_HOME if SSO is enabled.

  • Modify the webcache.xml file to define the new site, origin server, listen port, do the proper site-to-server mappings, and point to any user-specified wallet locations.

14.4.4.2 Running the SSL Configuration Tool

Run the following command to configure SSL for this scenario. The name of the input configuration file is sslct_config.xml and the Oracle administrator password is "welcome1."

SSLConfigTool -config_w_file sslct_config.xml -opwd welcome1

The following shows the contents of the sslct_config.xml input configuration file:

<sslconfig>
   <mid_tier>
      <virtual_address ssl="on"
                       host="mylogin.us.oracle.com"
                       port="443"
                       ssl_terminate="wc" />
   <wc/>
   <ohs>
      <servers>
         <server host="ohs6.us.oracle.com" port="7778" />
         <server host="ohs8.us.oracle.com" port="7778" />
      </servers>
   </ohs>
   </mid_tier>
</sslconfig>

To configure SSL interactively, use the -config_w_prompt option, as shown in the following example. The answers to the questions are in bold:

SSLConfigTool -config_w_prompt -opwd welcome1

Welcome to the OracleAS SSL Configuration Tool.
Below you will be guided with a series of questions.
If a question has the default answer,
the answer will be enclosed inside [square brackets].
Let's start now...

Do you want to configure your site to accept browser requests using SSL protocol? [y]: y
What is the virtual host name for your site? [mylogin.us.oracle.com]: mylogin.us.oracle.com
What is the virtual port number for your site? [4443]: 443
Does your site have an external load balancer (LBR)?
Note: Do NOT include OracleAS Web Cache as LBR here. [y]: n
Does your Oracle HTTP Server (OHS) accept requests in SSL protocol? [y]: n
Do you want to supply your own wallet locations for Web Cache? [n]: n
How many OHS instances does your Web cache route traffic to? [1]: 2
Please enter host name for OHS #1: ohs6.us.oracle.com
Please enter port number for OHS #1: 4443
Please enter host name for OHS #2: ohs8.us.oracle.com
Please enter port number for OHS #2: 4443
You have supplied all the information. Are you ready to continue? [y]: y

14.4.4.3 For More Information

For detailed information about configuring SSL in this scenario, see "Chapter 9, Configuring OracleAS Web Cache for HTTPS Requests" in Oracle Application Server Web Cache Administrator's Guide.

14.4.5 Configuring SSL to Oracle HTTP Server for OracleAS Single Sign-On/Oracle Delegated Administration Services

This scenario enables SSL for SSO/DAS with Oracle HTTP Server acting as the front end. There is no load balancer or front-end OracleAS Web Cache in this scenario (Figure 14-6).

SSL terminates at the Oracle HTTP Server tier. This means Oracle HTTP Server performs decryption and sends plain HTTP traffic directly to other Oracle Application Server components.

Figure 14-6 Topology and Summary of Changes

Description of Figure 14-6  follows
Description of "Figure 14-6 Topology and Summary of Changes"

14.4.5.1 What It Does

The SSL Configuration Tool does the following to enable HTTPS:

  • Change the opmn.xml file to enable Oracle HTTP Server.

  • Change the ssl.conf file to point to the load balancer's host and port.

  • Run the ssocfg script to configure the OracleAS Single Sign-On Server.

  • Run the ssoreg script to re-register mod_osso in the current ORACLE_HOME if SSO is enabled.

  • Modify the Oracle Delegated Administration Services operation URL in Oracle Identity Management and the ssl.conf file to add rewrite directives.

  • Modify the targets.xml file.

If you have multiple SSO/DAS homes in a high availability environment, you must run SSLConfigTool in each home, then perform step number 6 in the list of manual steps in Section 14.5.

14.4.5.2 Running the SSL Configuration Tool

Run the following command to configure SSL for this scenario. The name of the input configuration file is sslct_config.xml and the Oracle administrator password is "welcome1."

SSLConfigTool -config_w_file sslct_config.xml -opwd welcome1

The following shows the contents of the sslct_config.xml input configuration file:

<sslconfig>
   <mid_tier>
      <virtual_address ssl="on"
                       host="ohs6.us.oracle.com"
                       port="443"
                       ssl_terminate="ohs" />
   </mid_tier>
</sslconfig>

To configure SSL interactively, use the -config_w_prompt option, as shown in the following example. The answers to the questions are in bold:

SSLConfigTool -config_w_prompt -opwd welcome1

Welcome to the OracleAS SSL Configuration Tool.
Below you will be guided with a series of questions.
If a question has the default answer,
the answer will be enclosed inside [square brackets].
Let's start now...

Do you want to configure your site to accept browser requests using SSL protocol? [y]: y
What is the virtual host name for your site? [mylogin.us.oracle.com]: ohs6.us.oracle.com
What is the virtual port number for your site? [4443]: 443
Does your site have an external load balancer (LBR)?
Note: Do NOT include OracleAS Web Cache as LBR here. [y]: n
Does your site have OracleAS Web Cache? [y]: n
Do you want to supply your own wallet location for OHS? [n]: n
You have supplied all the information. Are you ready to continue? [y]: y

14.4.5.3 For More Information

For detailed information about configuring SSL in this scenario, see:

14.4.6 Configuring SSL to Oracle HTTP Server for OracleAS Portal

This scenario enables SSL for OracleAS Portal. A load balancer and OracleAS Web Cache are both in front of OracleAS Portal. The OracleAS Web Cache is a standalone installation, and uses the Oracle HTTP Server in the middle tier. The OracleAS Web Cache from the OracleAS Portal installation is rendered inactive (Figure 14-7).

For the purposes of this configuration, you should specify Oracle HTTP Server as the point of SSL termination. HTTPS, however, is used throughout OracleAS Portal.

Figure 14-7 Topology and Summary of Changes

Description of Figure 14-7  follows
Description of "Figure 14-7 Topology and Summary of Changes"

14.4.6.1 What It Does

The SSL Configuration Tool does the following to enable HTTPS:

  • Change the opmn.xml file to enable Oracle HTTP Server.

  • Change the ssl.conf file to point to the load balancer's host and port.

  • Run the ssoreg script to re-register mod_osso in the current ORACLE_HOME if SSO is enabled.

  • Modify the iasconfig.xml file and then run the ptlscript script against it.

  • Modify the web.xml file to refer to the load balancer's port.

  • Modify the webcache.xml file to define the new site, origin server, listen port, do the proper site-to-server mappings, and point to any user-specified wallet locations if OracleAS Web Cache is installed.

If you have multiple OracleAS Portal instances, you must run SSLConfigTool for each Portal instance, then perform steps 2, 3, 4, and 6 in the list of manual steps in Section 14.5. If you are using OracleAS Wireless with OracleAS Portal, you must also perform step 5.

14.4.6.2 Running the SSL Configuration Tool

Run the following command to configure SSL for this scenario. The name of the input configuration file is sslct_config.xml, the Oracle administrator password is "welcome1," and the Portal invalidation password is also "welcome1."

SSLConfigTool -config_w_file sslct_config.xml -opwd welcome1 -ptl_inv_pwd welcome1

The following shows the contents of the sslct_config.xml input configuration file:

<sslconfig>
   <mid_tier>
      <virtual_address ssl="on"
                       host="mylogin.us.oracle.com"
                       port="443"
                       inv_port="4001"
                       ssl_terminate="ohs" />
   <lbr loopback_port="7780" />
   <wc/>
   <ohs>
      <servers>
         <server host="machine_6.us.oracle.com" port="4443" />
      </servers>
   </ohs>
   </mid_tier>
</sslconfig>

To configure SSL interactively, use the -config_w_prompt option, as shown in the following example. The answers to the questions are in bold:

SSLConfigTool -config_w_prompt -opwd welcome1 -ptl_inv_pwd welcome1

Welcome to the OracleAS SSL Configuration Tool.
Below you will be guided with a series of questions.
If a question has the default answer,
the answer will be enclosed inside [square brackets].
Let's start now...

Do you want to configure your site to accept browser requests using SSL protocol? [y]: y
What is the virtual host name for your site? [mylogin.us.oracle.com]: mylogin.us.oracle.com
What is the virtual port number for your site? [4443]: 443
What is the invalidation port number your Portal uses? [4001]: 4001
Does your site have an external load balancer (LBR)?
Note: Do NOT include OracleAS Web Cache as LBR here. [y]: y
Does your Web Cache accept requests in SSL protocol? [y]: y
Does your Oracle HTTP Server (OHS) accept requests in SSL protocol? [y]: y
What is the Portal loop-back port in LBR or Web Cache? [7780]: 7780
Do you want to supply your own wallet locations for Web Cache? [n]: n
Do you want to supply your own wallet location for OHS? [n]: n
How many OHS instances does your Web Cache route traffic to? [1]: 1
What is the host name for OHS? [ohs6.us.oracle.com]: ohs6.us.oracle.com
What is the port number for OHS? [4443]: 4443
You have supplied all the information. Are you ready to continue? [y]: y

14.4.6.3 For More Information

For detailed information about configuring SSL in this scenario, see "Section 6.3.2.1, Configuring SSL for OracleAS Portal" in the Oracle Application Server Portal Configuration Guide.

14.4.7 Configuring an HTTP Instance

The SSL Configuration Tool can also be used to configure an HTTP-only instance. To accomplish this using a configuration input file, set the ssl attribute of the <virtual_address> element to "off," as shown in the following example:

<sslconfig>
   <mid_tier>
      <virtual_address ssl="off"
                       host="mylogin.us.oracle.com"
                       port="80" />
   </mid_tier>
</sslconfig>

To configure HTTP using the SSL Configuration Tool in interactive mode, answer "n" to the following question:

Do you want to configure your site to accept browser requests using SSL protocol? [y]: n

14.4.8 Configuring SSL for Cluster Configurations

To configure SSL in a clustered environment (for example, clustered Identity Management or Oracle Application Server High Availability Solutions), perform the following steps:

  1. Add the first node and HTTPS listener port to the new load balancer configuration. You should refer to your load balancer documentation for information on how to do this.

  2. Run the SSL Configuration Tool on the first node to enable HTTPS.

  3. Add the second node and HTTPS listener port to the load balancer configuration. You should refer to your load balancer documentation for information on how to do this.

  4. Run the SSL Configuration Tool on the second node to enable HTTPS.

14.5 Manual Steps

After the SSL Configuration Tool has run, you will see the following message:

The tool has completed the configuration steps. But please keep in
mind that there are still some manual steps left for you to
perform before you can use the environment in SSL mode.
1) The tool has not done anything about the SSL certificates. You
need to make sure you use a real certificate inside the wallets.
2) The tool has done limited configuration about EM monitoring. E.g.
you need to import the root CA certificate into EM wallet, etc.
You need to follow the instructions in the documentation.
3) You may need to cluster Web Cache on your own.
4) You may need to manually upload the Portal Preference Store to
the database using Portal scripts.
5) You may need to configure Wireless following the instructions
in the documentation.
6) When you have multiple installations of the same type, you need
to manually copy osso.conf from one install to the rest as well as
run 'ssotransfer' command against them.
For more, please refer to the documentation.

The corresponding documentation for these tasks can be found as listed in the following:

  1. See Chapter 15 for information about certificates and wallets.

  2. See Section 16.3.7, "Configuring SSL for Oracle Enterprise Manager 10g" for details about how to enable SSL communication in Oracle Enterprise Manager 10g.

    For information about configuring a certificate in Oracle Enterprise Manager 10g, refer to the section titled "Enable Monitoring of the Load Balancing Router's OracleAS Portal Host and Port Settings" in the Oracle Application Server Enterprise Deployment Guide.

  3. See "Chapter 3, Cache Clustering" in the Oracle Application Server Web Cache Administrator's Guide for information about OracleAS Web Cache clusters.

  4. See PDK-Java Release Notes, available on Portal Center at http://portalcenter.oracle.com, for information about how to perform this procedure.

  5. See Oracle Application Server Wireless Administrator's Guide for information about configuring Oracle Application Server Wireless. Additional wireless configuration information can be found in "Section C.8, Using the cfgiasw Script to Configure Mobile Settings" in Oracle Application Server Portal Configuration Guide.

  6. See "Section 4.3.2.4, Reregistering mod_osso on the Partner Application Middle Tiers" in the Oracle Application Server Single Sign-On Administrator's Guide for an example of how to do this procedure.

14.6 Troubleshooting the SSL Configuration Tool

This section contains information that may help you in the event you encounter any problems while running the SSL Configuration Tool. The following topics are covered:

14.6.1 General Troubleshooting Procedure

If the SSL Configuration Tool is able to detect a specific error, it will print some instructions on the screen and then exit. You should follow these instructions and take the recommended actions listed. For example:

Executing command:
/scratch/testuser/product/10.1.3/OracleAS/opmn/bin/opmnctl stopproc ias-component=dcm-daemon
 
ERROR: failed to run '/scratch/testuser/product/10.1.3/OracleAS/opmn/bin/opmnctl'.
ACTION: Please refer to the log file for the previous command.
ACTION: You may try running it explicitly from the command line to get more information about the error. 

If the SSL Configuration Tool hangs while it is running, you should press CTRL-C to exit. On the screen, you should see a series of commands that have been executed up to the point where you had to exit. Start with the most recent command and work backwards, consulting the documentation as necessary to determine the nature of the problem.

In either case, whether the SSL Configuration Tool exists or hangs, you should make the changes and run the SSLConfigTool command again. If the problems persist, you should run the SSLConfigTool -rollback command to revert to the environment prior to running the SSLConfigTool command.


Note:

you do not need to run the SSLConfigTool -rollback command if you do not see this line upon execution (the directories in this example may differ from your own):
Configuring HTTPS for your ORACLE_HOME at: /private/iasinst/work/ssltool_A
Backing up file '/private/iasinst/work/ssltool_A/opmn/conf/opmn.xml' to file '/p
rivate/iasinst/work/ssltool_A/opmn/conf/opmn.xml.orig_SSLConfigTool'

This is because no files on your system are changed prior to this point in the execution of the SSLConfigTool command.


If you encounter failures during the execution of the SSLConfigTool -rollback command, you must resolve the issues and run the SSLConfigTool -rollback again. This procedure must be repeated until you have a successful rollback. If you are unable to rollback successfully, contact your Oracle support representative for assistance.

14.6.2 Oracle Application Server Wireless Requires Manual Changes

Modifying OracleAS Web Cache settings (for example, changing the Listener port) can affect the OracleAS Portal URL. Rather than pointing to https, the URL will begin with http. To fix this, you must manually update your OracleAS Wireless settings. Refer to the following sections in Oracle Application Server Portal Configuration Guide for details:

  • "Section 6.3.2.1.3, SSL to OracleAS Web Cache"

  • "Section C.8, Using the cfgiasw Script to Configure Mobile Settings"

14.6.3 Configuring Seeded Providers for OracleAS Portal

OracleAS Portal includes several default (seeded) user accounts and groups. The SSL Configuration Tool is not able to configure SSL for seeded user accounts and groups; you must enable SSL for them manually. For the manual steps, see "Section 5.6.4, Configure Seeded Providers and Locally Hosted Web Providers" in Oracle Application Server Portal Configuration Guide.

14.6.4 SSL Configuration Tool Does Not Support IASCONFIG_LOC Environment Variable

The IASCONFIG_LOC environment variable is used to override the default location of the iasconfig.xml file (the Portal Dependency Settings file). The SSL Configuration Tool does not modify the IASCONFIG_LOC environment variable, which means only the iasconfig.xml file in the default location (ORACLE_HOME/portal/conf) will be updated during SSL configuration.

For more information about the IASCONFIG_LOC environment variable, see "Appendix A, Using the Portal Dependency Settings Tool and File" in Oracle Application Server Portal Configuration Guide.

14.6.5 SSL Configuration Tool Does Not Modify sso_apache.conf File

The SSL Configuration Tool does not modify the sso_apache.conf file. This file needs to be modified in order for external applications to work in an SSL environment.

For information about modifying the sso_apache.conf file, see "Section 8.1.3, Protect Single Sign-On URLs" in Oracle Application Server Single Sign-On Administrator's Guide.

14.6.6 SSL Configuration Tool Does Not Modify opmn.xml Parameters

If you install Oracle Business Intelligence, Oracle Business Intelligence Discoverer adds the following parameters to the opmn.xml file:

  • oracle.discoverer.applications.host

  • oracle.discoverer.applications.port

By default, the oracle.discoverer.applications.host parameter is set to the local host, and the oracle.discoverer.applications.port parameter is set to the Apache non-SSL port.

The SSL Configuration Tool does not modify these parameters, so you have to modify them manually after running the SSL Configuration Tool:

  • Change oracle.discoverer.applications.host to point to your LBR's virtual IP address (if you are using an LBR).

  • Change oracle.discoverer.applications.port to point to your SSL port.

After making these changes, save opmn.xml, then run the following commands:

opmnctl reload
opmnctl restartproc type=oc4j instancename=OC4J_BI_FORMS