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 SSO as of OracleAS 10g (9.0.4). 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, SSO authentication is based on user name and password. SSO can be configured to authenticate each user based on that user's certificate. Although the configuration steps are already documented in SSO 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 SSO server, configure SSO to use certificates, and register OCA with the SSL-enabled SSO 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 SSO, you must complete two sets of procedures:

Enabling SSL on SSO

Enabling PKI on SSO

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

E.1 Enabling SSL on SSO

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

Edit the $ORACLE_HOME/opmn/conf/opmn.xml file:
Search for ' id=ÓHTTP', 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 SSO, as follows:

Comment out the 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 SSO server.

If not, you need to use Oracle Wallet Manager to generate a wallet for the SSO 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
Edit the $ORACLE_HOME/sso/conf/sso_apache.conf file by adding the following lines to the end of the file:

<IfDefine SSL>

<location "/sso/auth">

SSLRequireSSL

</location>

<location "/sso/ChangePwdServlet">

SSLRequireSSL

</location>

</IfDefine>

<IfModule mod_ossl.c>

<Oc4jExtractSSL on

<Location /sso>

SSLOptions +ExportCertData +StdEnvVars

</Location>

</IfModule>
Reconfigure the SSO 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 SSO was installed:

$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar -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
Restart OHS for SSO 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 SSO server is installed.

The steps listed below enable PKI on SSO.

Configure the Single Sign-On System for Certificates by adding a tag to the orion-web.xml file at $ORACLE_HOME/j2ee/OC4J_SECURITY/application-deployments/sso/web, as follows:

Place the following tag before </orion-web-app>.

<jazn-web-app runas-mode="true" />

The following sample orion-web.xml file shows the tag correctly placed:

<jazn-web-app runas-mode="true" />

</orion-web-app>
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 SSO 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 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 SSO server to use SSL, the OCA virtual host must be re-registered with the SSL-enabled SSO server. All SSO-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/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar

-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 SSO 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

E.3.1 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
```

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

$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar
-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