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 OracleAS Single Sign-On as of OracleAS 10g Release 2 (10.1.2). 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 authentication is based on user name and password. OracleAS Single Sign-On can be configured to authenticate each user based on that 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 user 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 OCA with the SSL-enabled OracleAS Single Sign-On server.Notes: This document applies to both UNIX and WINDOWS platforms, except that for WINDOWS, the path separator should be '\', 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 OCA's Virtual Host with the SSL-Enabled SSO

Enabling SSL on SSO

For this section, the ORACLE_HOME to use is the 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 OCA was installed in the same machine, you can use OCA's 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 OCA 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:

$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
```

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 steps listed below 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 OCA 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 OCA port is 4400, then the above line becomes the following:
```
oca.us.oracle.com\:4400=MediumSecurity
```
With these options all set, a user logging in to any partner application is required to have a certificate, except for OCA, 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
```

Re-registering OCA's Virtual Host with the SSL-Enabled SSO

For this section, the ORACLE_HOME to use is the location where OCA is installed.

Each time the administrator enables the OracleAS Single Sign-On server to use SSL, the OCA 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. OCA'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 OCA by running the following command:

$ORACLE_HOME/sso/bin/ssoreg.sh

-oracle_home_path $ORACLE_HOME -site_name oca -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 OCA's mod_osso record in the osso.conf file, reflecting SSL settings on the single sign-on server.

Restart OHS for OCA by running the following command:

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

Example of Re-Registration OCA

Suppose that the OCA host name is myoca.mysite.com and the OCA server authentication port is 4400. 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):
```
setenv ORACLE_HOME /sso_server/oracle_home

setenv LD_LIBRARY_PATH $ORACLE_HOME/lib
```
Note:
For Bourne and ksh shells, these setenv commands would instead be:
ORACLE_HOME=/private/oracle/gitm1; export ORACLE_HOME

Using these variables as set, the actual command 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:4400

-u root -config_file $ORACLE_HOME/Apache/Apache/conf/osso/oca/osso.conf

-virtualhost

Note:

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:4400

-u SYSTEM 

-config_file $ORACLE_HOME\Apache\Apache\conf\osso\oca\osso.conf

-virtualhost