E Enabling SSL and PKI on SSO

The procedures in this Appendix are all the necessary and advisable steps for enabling SSL and PKI on Oracle Application Server Single Sign-On as of OracleAS 10g (10.1.4.0.1). Detailed descriptions with additional context explanations appear in the following manuals:

Oracle Application Server Single Sign-On Administrator's Guide
Oracle HTTP Server Administrator's Guide
Oracle Advanced Security Administrator's Guide

By default, OracleAS Single Sign-On uses the HTTP port of the Oracle HTTP Server, and single sign-on authentication is based on user name and password. However, OracleAS Single Sign-On can be configured for SSL to authenticate a user based on the user's certificate. Although the configuration steps are already documented in OracleAS Single Sign-On and OHS documentation, they are scattered in many places. For convenience, these steps are combined in this Appendix.

Three separate steps are needed to configure this feature: enable SSL for OracleAS Single Sign-On server, configure OracleAS Single Sign-On to use certificates, and register OracleAS Certificate Authority with the SSL-enabled OracleAS Single Sign-On server.

Note:

This document applies to both UNIX and Windows platforms, except that for Windows, the path separator should be '\', instead of '/' and variables are dereferenced with '%' instead of '$'.

To achieve the objective of enabling SSL and PKI on OracleAS Single Sign-On, you must complete three sets of procedures:

Enabling SSL on SSO
Enabling PKI on SSO
Re-registering the Virtual Host with the SSL-Enabled SSO

E.1 Enabling SSL on SSO

You can configure SSL for OracleAS Single Sign-On 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

Note:

For detailed information, refer to the Oracle Application Server Single Sign-On Administrator's Guide, specially the chapter on Enabling SSL.

For this section, use the ORACLE_HOME location where the OracleAS Single Sign-On server is installed.

Edit the $ORACLE_HOME/opmn/conf/opmn.xml file:
Search for id="HTTP_Server", and then, four lines down, change the following line:
```
<data id="start-mode value="ssl-disabled">
```
to read instead as follows:
```
<data id="start-mode value="ssl-enabled">
```
Restart opmn using the new xml file:
```
$ORACLE_HOME/opmn/bin/opmnctl reload
```
Edit the $ORACLE_HOME/Apache/Apache/conf/ssl.conf file:
On the line before </VirtualHost>, add the following:
```
RewriteEngine on
RewriteOptions inherit
```
Disable the SSL session cache to force SSL to perform a handshake when logging out of OracleAS Single Sign-On, as follows:

Comment out the SSLSessionCache and SSLSessionCacheTimeout directives in ssl.conf.sec:
```
# SSLSessionCache
# SSLSessionCacheTimeout 15
```
Then add the following line:
```
SSLSessionCache none
```
Update the wallet. If OracleAS Certificate Authority was installed in the same machine, you can use its SSL wallet for the OracleAS Single Sign-On server.

If not, you need to use Oracle Wallet Manager to generate a wallet for the OracleAS Single Sign-On server: see its documentation in the Oracle Advanced Security Administrator's Guide.

Typically an existing SSL wallet generated by OracleAS Certificate Authority is located in /app/oracle/oca/wallet/ssl. Locate the SSLWallet directive in this file (ssl.conf) and comment it out:
```
# SSLWallet file:/app/oracle/product/sec_inf/Apache/Apache/conf/ssl.wlt/default
```
and insert a new one that reads as follows:
```
SSLWallet file:/app/oracle/oca/wallet/ssl
```
Set client authentication by commenting out the following line:
```
# SSLVerifyClient require
```
and inserting a new one that reads as follows:
```
SSLVerifyClient optional
```
Reconfigure the OracleAS Single Sign-On server to use the SSL port. The command form is:
```
$ORACLE_HOME/sso/bin/ssocfg.sh https  hostname  ohs_ssl_port
```
So if the hostname is sso.us.oracle.com and ohs_ssl_port is 4443, then the command becomes the following line:
```
$ORACLE_HOME/sso/bin/ssocfg.sh https  sso.us.oracle.com 4443
```

Register mod_osso for sso by running the following command in the Oracle home where OracleAS Single Sign-On was installed (UNIX):

$ORACLE_HOME/sso/bin/ssoreg.sh \
-oracle_home_path $ORACLE_HOME   -site_name sso   -config_mod_osso TRUE \
-mod_osso_url  https://hostname.domain.com:ohs_ssl_port \
–update_mode CREATE   -u root

Note:

For Windows, the command is:

%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
-u userid
-virtualhost
-update_mode CREATE

Restart OHS for OracleAS Single Sign-On by running the following command:
```
$ORACLE_HOME/opmn/bin/opmnctl restartproc type=ohs
```

E.2 Enabling PKI on SSO

For this section, the Oracle home to use is the location where the OracleAS Single Sign-On server is installed.

The following steps enable PKI on OracleAS Single Sign-On:

Edit $ORACLE_HOME/sso/conf/policy.properties to set the default authentication level to High and to set the correct corresponding plugin, as follows:
```
DefaultAuthLevel = MediumHighSecurity

MediumHighSecurity_AuthPlugin = oracle.security.sso.server.auth.SSOX509CertAuth
```
Configure OracleAS Certificate Authority to use username and password for provisioning, using lines of the following form:
```
MediumSecurity_AuthPlugin = oracle.security.sso.server.auth.SSOServerAuth
```
```
Oca_hostname\:port = MediumSecurity
```
For example, if the Oca_hostname is oca.us.oracle.com and the OracleAS Certificate Authority port is 6600, then this option is written as follows:
```
oca.us.oracle.com\:6600=MediumSecurity
```
With these options all set, a user logging in to any partner application is required to have a certificate, except for OracleAS Certificate Authority, where he can get a certificate.

Restart the OracleAS Single Sign-On server using the following commands:
```
$ORACLE_HOME/opmn/bin/opmnctl stopproc  process-type=OC4J_SECURITY
$ORACLE_HOME/opmn/bin/opmnctl startproc  process-type=OC4J_SECURITY
```

E.3 Re-registering the Virtual Host with the SSL-Enabled SSO

For this section, the ORACLE_HOME to use is the location where OracleAS Certificate Authority is installed.

Each time the administrator enables the OracleAS Single Sign-On server to use SSL, the OracleAS Certificate Authority virtual host must be re-registered with the SSL-enabled OracleAS Single Sign-On server. All OracleAS Single Sign-On-using applications must do so. Re-registration is done by using the single sign-on registration tool, ossoreg.jar. OracleAS Certificate Authority's use of this tool is explained here; its general use for all Single Sign-On enabled applications is explained in Oracle Application Server Single Sign-On Administrator's Guide.

Re-register mod_osso for OracleAS Certificate Authority by running the following command:
```
$ORACLE_HOME/sso/bin/ssoreg.sh \
-oracle_home_path $ORACLE_HOME -site_name OracleAS Certificate Authority \
-config_mod_osso TRUE \
-mod_osso_url https://hostname.domain.com:oca_ssl_port  -u root \
-virtualhost \
-config_file $ORACLE_HOME/Apache/Apache/conf/osso/oca/osso.conf
```
Running this tool on the machine hosting the OracleAS Single Sign-On server generates OracleAS Certificate Authority's mod_osso record in the osso.conf file, reflecting SSL settings on the single sign-on server.
Restart OHS for OracleAS Certificate Authority by running the following command:

$ORACLE_HOME/opmn/bin/opmnctl restartproc type=ohs

E.3.1 Example of Re-Registration

Suppose that the OracleAS Certificate Authority host name is myoca.mysite.com and the OracleAS Certificate Authority server authentication port is 6600. The following steps accomplish the re-registration:

Use these two commands to set the variables to be used by the actual command (in step 2):

On csh and tcsh:

setenv ORACLE_HOME /sso_server/oracle_home
setenv LD_LIBRARY_PATH $ORACLE_HOME/lib

On Bourne and ksh shells:

set ORACLE_HOME=/sso_server/oracle_home; export ORACLE_HOME
set LD_LIBRARY_PATH=$ORACLE_HOME/lib; export LD_LIBRARY_PATH

Using these variables as set, the actual command on a UNIX system would be as follows (although on a single line):

$ORACLE_HOME/sso/bin/ssoreg.sh \
-oracle_home_path $ORACLE_HOME -site_name my_oca_site_name \
-config_mod_osso TRUE  -mod_osso_url https://myoca.mysite.com:6600 \
-u root -config_file $ORACLE_HOME/Apache/Apache/conf/osso/oca/osso.conf \
-virtualhost

For Windows, the commands are:

set ORACLE_HOME=c:\sso_server\oracle_home

%ORACLE_HOME%\sso\bin\ssoreg.bat
-oracle_home_path $ORACLE_HOME
-site_name "my_oca_site_name"
-config_mod_osso TRUE
-mod_osso_url https://myoca.mysite.com:6600
-u SYSTEM 
-config_file $ORACLE_HOME\Apache\Apache\conf\osso\oca\osso.conf
-virtualhost