7 Enabling SSL

This chapter explains how to enable the single sign-on server for Secure Sockets Layer (SSL). In SSL, a secret session key is created, enabling the exchange of information over a secure channel. When the user logs in, the Web server sends the browser a digital certificate. The browser uses a public key sent by the Web server to encrypt a random number. This encrypted data is used in turn to create the secret key. Enabling the single sign-on server for SSL confers this form of protection on the server's partner applications. The process provides OracleAS with a high degree of security.

Out of the box, the single sign-on server uses the HTTP port of the Oracle HTTP Server. You can, however, configure SSL after installation using either an automated or manual approach.

Automated SSL Configuration

For common topologies, the SSL Configuration Tool can perform the steps required to enable post-installation SSL of the Oracle HTTP Server. For details about the tool and how to run it, see "Using the SSL Configuration Tool" in the Oracle Application Server Administrator's Guide.

Manual SSL Configuration

If you prefer a manual approach to enabling SSL, complete the following tasks in the order listed:

Enable SSL on the Single Sign-On Middle Tier
Reconfigure the Identity Management Infrastructure Database
Protect Single Sign-On URLs
Restart the Oracle HTTP Server and the Single Sign-On Middle Tier
Reregister Partner Applications

Note:

If the Oracle HTTP Server is configured for SSL (topic 1) you must configure the single sign-on server for SSL as well (remaining topics); otherwise users will be unable to access single sign-on URLs. To skirt this restriction, disable SSL directives for URLs that you want to access over HTTP. You do this by editing ORACLE_HOME/sso/conf/sso_apache.conf.

7.1 Enable SSL on the Single Sign-On Middle Tier

The following steps involve configuring the Oracle HTTP Server. In performing them, keep the following in mind:

You must configure SSL on the computer where the single sign-on middle tier is running—that is, on the computer that hosts the single sign-on server.
You are configuring one-way SSL.
You may enable SSL for simple network encryption; PKI authentication is not required. Note though that you must use a valid wallet and server certificate. The default wallet location is ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default. If you want to use a different wallet, see the guidelines in the section "Oracle HTTP Server" in Chapter 8. The chapter about managing wallets and certificates in Oracle Application Server Administrator's Guide is also helpful.

To quickly enable SSL on the Oracle HTTP Server, do the following:

Back up the opmn.xml file, found at ORACLE_HOME/opmn/conf.

In opmn.xml, change the value for the start-mode parameter to ssl-enabled. This parameter appears in boldface in the xml tag immediately following.

 <ias-component id="HTTP_Server"> 
    <process-type id="HTTP_Server" module-id="OHS"> 
        <module-data> 
           <category id="start-parameters"> 
               <data id="start-mode" value="ssl-enabled"/> 
           </category> 
        </module-data> 
    <process-set id="HTTP_Server" numprocs="1"/> 
    </process-type> 
</ias-component>

Update the distributed cluster management database with the change:
```
ORACLE_HOME/dcm/bin/dcmctl updateconfig -ct opmn
```
Reload the modified opmn configuration file:
```
ORACLE_HOME/opmn/bin/opmnctl reload 
```
Keep a non-SSL port active. The External Applications portlet communicates with the single sign-on server over a non-SSL port. The HTTP port is enabled by default. If you have not disabled the port, this step requires no action.
Apply the rule mod_rewrite to SSL configuration. This step involves modifying the ssl.conf file on the middle-tier computer. The file is at ORACLE_HOME/Apache/Apache/conf. Back up the file before editing it.

Because the Oracle HTTP Server has to be available over both HTTP and HTTPS, the SSL host must be configured as a virtual host. Add the lines that follow to the SSL Virtual Hosts section of ssl.conf if they are not already there. These lines ensure that the single sign-on login module in OC4J_SECURITY is invoked when a user logs in to the SSL host.
```
<VirtualHost ssl_host:port>
  .
  .
  .
  RewriteEngine on
  RewriteOptions inherit
</VirtualHost>
```
Save and close the file.
Update the distributed cluster management database with the changes:
```
ORACLE_HOME/dcm/bin/dcmctl updateconfig -ct ohs
```

Restart the Oracle HTTP Server:

ORACLE_HOME/opmn/bin/opmnctl stopproc process-type=HTTP_Server
ORACLE_HOME/opmn/bin/opmnctl startproc process-type=HTTP_Server

Verify that you have enabled the single sign-on middle tier for SSL by trying to access the OracleAS welcome page, using the format https://host:ssl_port.

Note:

If your installation has two or more middle tiers, make sure that you complete step 2 in "Configure the Oracle HTTP servers on the single sign-on middle tiers". This is a subsection of "Multiple Single Sign-On Middle Tiers, One Oracle Internet Directory" one of the deployment scenarios presented in Chapter 9.

7.2 Reconfigure the Identity Management Infrastructure Database

To reconfigure the Identity Management Infrastructure Database, you must:

Change all references of http in single sign-on URLs to https within the identity management infrastructure database.
When you change single sign-on URLs in the database, you must also change these URLs in the targets.xml file on the single sign-on middle tier. targets.xml is the configuration file for the various "targets" that Oracle Enterprise Manager monitors. One of these targets is OracleAS Single Sign-On.
Configure Oracle Enterprise Manager Security.

These steps are described in the subsequent sections.

7.2.1 Change Single Sign-On URLs

Run the ssocfg script, taking care to enter the command on the computer where the single sign-on middle tier is located. Use the following syntax:

UNIX:

$ORACLE_HOME/sso/bin/ssocfg.sh protocol host ssl_port

Windows:

%ORACLE_HOME%\sso\bin\ssocfg.bat protocol host ssl_port

In this case, protocol is https. (To change back to HTTP, use http.) The parameter host is the host name, or server name, of the Oracle HTTP listener for the single sign-on server.

Here is an example:

ssocfg.sh https login.acme.com 4443

To determine the correct port number, examine the ssl.conf file. Port 4443 is the port number that the OracleAS installer assigns during installation.

If you run ssocfg successfully, the script returns a status 0. To confirm that you were successful, restart the OC4J_SECURITY instance:

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

Then try logging in to the single sign-on server at its SSL address:

https://host:ssl_port/pls/orasso/

7.2.2 Update targets.xml

After running ssocfg, update the targets.xml file on the single sign-on middle tier.

To update targets.xml:

Back up the file:

cp ORACLE_HOME/sysman/emd/targets.xml ORACLE_HOME/sysman/emd/targets.xml.backup

Open the file and find the target type oracle_sso_server. Within this target type, locate and edit the three attributes that you passed to ssocfg:
- HTTPMachine—the HTTP server host name
- HTTPPort—the SSL port number of the Oracle HTTP server
- HTTPProtocol—the server protocol
If, for example, you run ssocfg like this:
```
ORACLE_HOME/sso/bin/ssocfg.sh https sso.mydomain.com:4443
```
Update the three attributes this way:
```
<Property NAME="HTTPMachine" VALUE="sso.mydomain.com"/>
<Property NAME="HTTPPort" VALUE="4443"/>
<Property NAME="HTTPProtocol" VALUE="HTTPS"/>
```
Save and close the file.
Reload the OracleAS console:
```
ORACLE_HOME/bin/emctl reload
```

7.2.3 Configure Oracle Enterprise Manager Security

Since you are enabling the single sign-on server for SSL, you will need to follow all the configuration instructions detailed in the chapter about Oracle Enterprise Manager security in Oracle Enterprise Manager Advanced Configuration. Specifically, pay close attention to the section titled "Configuring Beacons to Monitor Web Applications Over HTTPS." Oracle Beacons, which are part of the Application Service Level Management features of Enterprise Manager, provide application performance availability and performance monitoring. Beacons are used to monitor a URL over SSL using an HTTPS URL.

7.3 Protect Single Sign-On URLs

When the single sign-on server is enabled for SSL, you must specify that HTTP access be limited to those hosts that must access the server using this protocol. This is especially true in the case of those computers hosting the OracleAS installer and OracleAS Portal.

This section provides instructions for:

Protecting URLs in the Absence of a Load Balancing Router
Protecting URLs in the Presence of a Load Balancing Router

7.3.1 Protecting URLs in the Absence of a Load Balancing Router

Use these instructions when no load balancing router is deployed in front of the single sign-on server and OracleAS Portal. In ORACLE_HOME/sso/conf/sso_apache.conf, locate and uncomment the three directives that follow; then provide a value for the Allow from parameter.

Invoke the first directive if you are installing a release 9.0.2 middle tier with a release 10.1.2 single sign-on server. This directive enables the installer to access the single sign-on server over HTTP. Replace <your_domain_name> with the fully qualified host name of the middle tier on which the installer is located; then uncomment the line. If you plan to install from more than one location, enter just a domain name.

 <Location "/pls/orasso/*[Ss][Ss][Oo][Pp][Ii][Nn][Gg]">
   Order deny,allow
   Deny from all
#  Allow from <your_domain_name>
 </Location>

OracleAS Portal must use HTTP to access the URL that provides a list of external applications. The directive that follows enables such access. Replace <your_domain_name> with the fully qualified Portal host name; then uncomment the directive. If you have more than one Portal database, enter just the domain name for these databases.

#<Location "/pls/orasso/*[Aa][Pp][Pp][Ss]_[Ll][Ii][Ss][Tt]">
#  Order deny,allow
#  Deny from all
#  Allow from <your_domain_name>
#</Location>

Versions of OracleAS Portal that predate release 9.0.2 use HTTP to verify whether a user exists in the single sign-on database. This last directive enables verification. Again, replace <your_domain_name> with the fully qualified Portal host name; then uncomment the directive. If you have more than one Portal database, enter just the domain name for these databases.

#<Location "/pls/orasso/[Oo][Rr][Aa][Ss][Ss][Oo].wwsso_app_admin.validate_user*">
#  Order deny,allow
#  Deny from all
#  Allow from <your_domain_name>
#</Location>

After editing sso_apache.conf, update the repository for Distributed Cluster Management:

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

7.3.2 Protecting URLs in the Presence of a Load Balancing Router

In a deployment configuration where the single sign-on server and OracleAS Portal are front-ended by a load-balancing router, the rule for limiting access to hosts should be set directly with the load-balancing router. Do not attempt to add such a rule in the ORACLE_HOME/sso/conf/sso_apache.conf file to allow or deny access to a host for this configuration.

Here is an example of such a rule for BigIP:

if (client_addr != <infrastructure db IP> netmask 255.255.255.0 and 
    (http_uri starts_with 
    "/pls/orasso/orasso.wwsso_app_admin.external_apps_list" or 
    http_uri starts_with 
    "/pls/orasso/orasso.wwsso_app_admin.validate_user")) {
discard 
} 
else { 
    use pool SSO 
}

Note:

This is a specific example and is presented for illustration only. In practice, you should ensure that any access rule you apply is consistent with the load balancing router in use.

7.4 Restart the Oracle HTTP Server and the Single Sign-On Middle Tier

Issue these two commands:

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

7.5 Reregister Partner Applications

Once you have enabled the single sign-on server for SSL, reregister mod_osso on the single sign-on middle tier and on the application middle tiers. This step configures mod_osso to use the effective single sign-on URL. See "Configuring mod_osso with Virtual Hosts (SSL and non-SSL)" in Chapter 4 for instructions. To reregister OracleAS Portal, an application integrated with the single sign-on SDK, use the ptlconfig tool. To learn how to use ptlconfig, see Appendix B in Oracle Application Server Portal Configuration Guide.