Göteborgs universitet - Pablo Millet
Doc. Version: 0.1 : 17/7 - 2006 (first release)

All files needed (source, libs, docs. etc) are under the Attachement-tab (See above).

CAS 2 - Oracle SSO/Oracle Portal Installation

The documentation shows how to CASify the SSO part of the OCS.

Guthenburg university uses the whole OCS (Oracle Collaboration Suite)
-- Midtier ( Portal, Mail, Calendar)
-- Infra (OID, SSO)
-- DB (database, mail)

CAS use OID for looking up and validating accounts.
Oracle Portal uses the same OID.

CASifying the Oracle SSO part means that ALL Oracle SSO enabled applications and tools (eg, Oracle Portal, Mail, Calendar) will appear as if they where CAS clients.
Behind the curtains its only the SSO part of the OCS that works with CAS.
A user logged on to CAS should not have to login again when accessing Oracle SSO enabled applications.

This is generally done in three steps;

First we need to install and configure a CAS-server.

Second, we need to "rebuild" the Oracle SSO application so that it becomes a CAS-client. This means all users requesting an Oracle SSO enabled application (Portal, OCS, Portlets etc) will have to pass trough here which results in users being redirected to the CAS-server for authentication.

Third, we need to configure and replace the standard Oracle SSO plugin with our own CASAuthenticator. CASAuthenticator takes care of users coming from the CAS-server and validates its service-tickets. After the validation procedure is done, it passes the user to standard Oracle SSO procedures and hands over responsibility.

1. Purpose of this document

This document describes how to use CAS with Oracle Portal and SSO. This document does not instruct in detail how to install CAS or Oracle Portal/SSO. It is assumed you have basic knowledge about Tomcat, CAS and Oracle products. At the end of this document you'll find some useful links. Otherwise you'll find plenty of howtos out there.

Notice!!
Other versions of Oracle products and CAS have not been tested.

The following is required to be installed and running:

Server 1
- SSL enabled Tomcat version 4 or later.
- CAS version 2.1.1

Server 2
- Oracle Portal version 10.1.2
- Oracle SSO version 10.1.2

2. Install CAS version 2.1.1 (Server1)

Setting up the CAS software is straightforward.
First, download the CAS server and client libraries from: http://www.ja-sig.org/products/cas/

CAS uses HTTPS, so you must enable this in Tomcat. This can be a bit tricky, but if you follow the links below and the instructions it should work fine. In Apache Tomcat's website you'll find plenty of information and howtos for SSL enabling Tomcat.

2.1 Configure CAS-server (Server1)

See CAS documentation

3. Rebuild Oracle SSO to become a CAS-client (Server2)

This step assumes that you have a CAS server up and running.
We are now going to configure Oracle SSO to use CAS.

3.1 Import CAS-server certificate

You need to import your CAS-servers SSL Certificate into the keystore(s) used by your system.
Example on three different keystores. :

cd %ORACLE_HOME/infra/jre/1.4.2/bin

./keytool -alias my-cas-server.net -import -file /tmp/certs/my-cas-server.net.crt -keystore %ORACLE_HOME/jre/1.4.2/lib/security/cacerts

./keytool -alias my-cas-server.net -import -file /tmp/certs/my-cas-server.net.crt -keystore %ORACLE_HOME/javavm/lib/security/cacerts

./keytool -alias my-cas-server.net -import -file /tmp/certs/my-cas-server.net.crt -keystore %ORACLE_HOME/jdk/jre/lib/security/cacerts

Note:
If you are not familiar with javas keytool consider using Portecle (http://portecle.sourceforge.net/).
Portecle is a great tool for managing keystores, certificates import/export, etc.

3.2 Apply the CAS-filter to Oracle SSO application

This step assumes you have done step 3.1.

1. Copy cas-client-java-2.1.1.jar and commons-logging-api.jar to:
%ORACLE_HOME/j2ee/OC4J_SECURITY/applib

2. Copy gu-localplugins.jar to:
%ORACLE_HOME/j2ee/OC4J_SECURITY/applications/sso/web/WEB-INF/lib/

3. Edit the Portal SSO applications web.xml to include the CASSimpleFilter servlet filter.
The configuration example below uses my-cas-server.net and port 8443 for HTTPS. You should change this to suit your own configuration.

Open and edit:
%ORACLE_HOME/j2ee/OC4J_SECURITY/applications/sso/web/WEB-INF/web.xml

Place the following filter between <web-app> and </web-app> in web.xml.

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web app_2_2.dtd">

<web-app>

<!- START CAS -filter ->

<filter>
    <filter-name>CASSimpleFilter</filter-name>
    <filter-class>se.gu.cas.filter.CASSimpleFilter</filter-class>

    <init-param>
        <param-name>se.gu.cas.filter.loginUrl</param-name>
        <param-value>https://my-cas-server.net:8443</param-value>
    </init-param>

    <!- Not implemented in CASSimpleFilter ->
    <init-param>
        <param-name>se.gu.cas.filter.validateUrl</param-name>
        <param-value>https://my-cas-server.net:8443/serviceValidate</param-value>
    </init-param>

    <init-param>
        <param-name>se.gu.cas.filter.serverName</param-name>
        <param-value>this-oracle-sso-server-name.net</param-value>
    </init-param>
</filter>

<filter-mapping>
    <filter-name>CASSimpleFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

<!- END CAS-filter ->

<!- START SOME OTHER DEFAULT SSO APPLICATION SETTINGS ->
    ...
<!- END SOME OTHER DEFAULT SSO APPLICATION SETTINGS ->

</web-app>

What se.gu.cas.filter.CASSimpleFilter does (very simple):
1. If no CAS ServiceTicket (ST) is found in the request it redirects the client to CAS
2. If a ST is found it continues processing the request... meaning that the client will end up on se.gu.cas.oracle.plugin.CASAuthenticator

From now on requests to any Oracle SSO enabled application (Portal, OCS, Portlets) will be redirected to the CAS-server. (https://my-cas-server.net:8443).

4. Install and configure the SSO-plugin - CASAuthenticator

Now we need to replace the standard Oracle SSO plugin with our own CASAuthenticator plugin.

This plugin is the key workhorse in CAS-Oracle SSO. Its main purpose is to validate tickets (ST-ServiceTickets) on our CAS-server and enable a valid Oracle SSO-session upon validation for the requesting client/browser.

What se.gu.cas.oracle.plugin.CASAuthenticator does (very simple):
1. Validates the given CAS ServiceTicket (ST).
2. If validation of ST returns success it starts a Oracle SSO session and then hands over the responsibility to standard Oracle SSO.

4.1. Replace default Oracle SSO with CASAuthenticator

1. Copy:

cas.properties and gu-localplugins.jar to %ORACLE_HOME/sso/plugin/
(see "Configure CASAuthenticator - cas.properties" for configuration instructions)
cas-client-java-2.1.1.jar to %ORACLE_HOME/sso/lib/

2. Edit: %ORACLE_HOME/sso/conf/policy.properties

Look for "MediumSecurity_AuthPlugin".

Comment out the default AuthPlugin, like this
#MediumSecurity_AuthPlugin = oracle.security.sso.server.auth.SSOServerAuth

and use CASAuthenticator as plugin instead,
MediumSecurity_AuthPlugin = se.gu.cas.oracle.plugin.CASAuthenticator

Save the file and exit... done!

4.2 Configure CASAuthenticator - cas.properties

#
# Configuration for 'se.gu.cas.oracle.plugin.CasAuthenticator'
#
# The following logfiles are interesting in your system:
# %ORACLE_HOME/opmn/logs/OC4J~OC4J_SECURITY~default_island~1
# %ORACLE_HOME/sso/log/ssoServer.log
#
# Pablo Millet
# Goteborgs universitet
# pablo.millet@adm.gu.se
#

# Where CASAuthenticator validates its CAS ServiceTickets
# Notice: It must be '/validate'. Do NOT use 'serviceValidate'
validateURL=https://my-cas-server.net:8443/serviceValidate

# Some (little) debug info. Set to 'true' or 'false'.
showDebug=false

# OID settings
# Function not yet implemented in production env.
# The idea of having this is to have the plugin "doublecheck" if the
# authenticating user really excists in the OID (the directory used by Oracle-SSO).
# Could be handy if the CAS-server authenticates against different LDAP than the
# one Oracle-SSO is using (OID).
#
# Example:
# 1. User goes to ApplicationX.
# 2. ApplicationX is a CAS-client (SSO-enabled with CAS-server) and redirects the User to CAS-server.
# 3. The User authenticates and CAS-server starts a valid SSO-session for that User.
# 4. CAS-server redirects the User back to ApplicationX with a valid SSO-session.
#
# Comment:
# Now, if User has access to ApplicationX doesn't necessarily mean that User also has access to Oracle Portal
# although they (Oracle Portal and ApplicationX) are using the same CAS-server.
# The CASAuthenticator should in this case 'recheck' if User has access to Oracle Portal.
#
# Not tested. Feel free to do so...
# OIDLogin=cn=userWithReadRightsInOID
# OIDPassword=userWithReadRightsInOID_Password
# OIDServer=my-oid-server.net
# OIDPort=389
# OIDRootContext="cn=users,dc=dept,dc=gu,dc=net"
# OIDSSL=false

6. Restart...

Restart OC4J_SECURITY:
%ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=OC4J_SECURITY

Note; The following logfiles are interesting:

%ORACLE_HOME/opmn/logs/OC4J~OC4J_SECURITY~default_island~1
%ORACLE_HOME/sso/log/ssoServer.log

DONE!

5. Additional information

If you need to change CASAuthenticator you'll need Oracles ipastoolkit.jar andcas-client-java-2.1.1.jar library to compile!
Tomcat:https://apache.tomcat.org
Tomcat SSL:http://tomcat.apache.org/tomcat-4.1-doc/ssl-howto.html
Portecle (great tool for managing keystores, certificatesimport-export, etc.)
http://portecle.sourceforge.net/
CAS:http://www.ja-sig.org/products/cas/
CAS:http://www-128.ibm.com/developerworks/web/library/wa-singlesign/
CAS:http://wiki.case.edu/Central_Authentication_Service
The following logfiles are interesting in your Oracle system:
- %ORACLE_HOME/opmn/logs/OC4J~OC4J_SECURITY~default_island~1
- %ORACLE_HOME/sso/log/ssoServer.log

Central Authentication Service

CASifying Oracle Portal