$Id: README.txt,v 1.7 2014/04/10 09:37:38 jah Exp $

This is the README for OpenAM connector for Computer Associates (CA) SiteMinder.

The OpenAM SiteMinder connector can be used to integrate OpenAM with
SiteMinder. It can create OpenAM sessions from a user's SiteMinder session
and vice versa, making it possible to have single signon between these systems.
This functionality is useful when adding OpenAM based features into an existing
SiteMinder infrastructure, using OpenAM federation with SiteMinder or when
migrating between these systems.

Note that this README is not complete documentation for the connector and
it should be used together with OpenAM and SiteMinder documentation.

This README describes the components of the connector and how to build, install and configure it.

Components
==========

The SiteMinder connector has these main components:
* OpenAM authentication scheme for SiteMinder policy server.
  This allows user to authenticate to SiteMinder with their OpenAM session.

* SiteMinder authentication module for OpenAM.
  This allows user to authenticate to OpenAM with their SiteMinder session.

* OpenAM Post-authentication plugin for creating a SiteMinder session.
  This will create a SiteMinder session on succesful OpenAM login.

* OpenAM SAML2 SP plugin for creating a SiteMinder session.
  This will create a SiteMinder session on succesful SAML2 SSO.

* Utility class for SiteMinder session management.
  This is a utility class used by other components.

Building the connector
======================

See lib/readme_lib.txt for libraries needed for building the connector.
Some of the libraries can be simply copied from existing OpenAM installation,
others need to be copied from SiteMinder SDK or the servlet container used
for running OpenAM.

The connector is built using Apache ant. A succesful build results in file
dist/fam_sm_integration.jar that contains all the connector code. This
same jar file needs to be installed on OpenAM and SiteMinder policy servers.

The tools/create-overlay.sh script can be used to create an overlay directory
structure that can simply be copied over an existing OpenAM installation
in order to install the connector.

Installing the connector
========================

The connector need to be installed on all OpenAM servers and all SiteMinder
policy servers that you intend to use with it.

Any OpenAM server host running the connector needs to have either SiteMinder
SDK or Web Agent installed. The SiteMinder agent has to be configured and
registered as trusted host on the SiteMinder policy server. Generally the
easiest way to do this is to install the web agent and run its configuration
script to do the necessary trusted host registration. Note that it is not
necessary to configure any web servers with the web agent, just doing the
trusted host registration is enough. Refer to SiteMinder documentation for
more information.

For installing the connector on OpenAM server the easiest option is to use
the create-overlay.sh script and copy the resulting file structure over an
already installed OpenAM server (webapp). You can also zip up the overlay file
structure and just unzip the package on the target server to make deploying
to multiple servers easier.

For installing the connector on SiteMinder policy server there are multiple
steps to do:

1) Install and configure OpenAM client SDK on the SiteMinder policy server
   host. Refer to OpenAM documentation for more information. The CommandLineSSO
   script can be used to verify that users can be authenticated with the
   installed client SDK.

2) Add the connector library (fam_sm_integration.jar) to the client SDK.
   This can be done by simply copying the fam_sm_integration.jar to the
   lib directory of the client SDK installation.

2) Change Java security settings.
   The SiteMinder policy server seems to do something that breaks SSL
   connections using the normal Java security settings. To work around this
   the Java security provider list needs to be changed so that
   sun.security.pkcs11.SunPKCS11 is not used. Edit the
   $JAVA_HOME/jre/lib/security/java.security file and remove the SunPKCS11
   provider from the list of configured providers. Remember to re-number the
   remaining providers.

3) Change SiteMinder JVM classpath to include the connector and
   OpenAM client SDK libraries. This is done by editing the file
   <siteminder_install_directory>/config/JVMOptions.txt. Add the following
   libraries to the classpath in JVMOptions.txt:
   <openam_clientsdk_directory>/lib/fam_sm_integration.jar
   <openam_clientsdk_directory>/lib/openssoclientsdk.jar
   <openam_clientsdk_directory>/lib/j2ee.jar
   <openam_clientsdk_directory>/lib/opensso-sharedlib.jar
   <openam_clientsdk_directory>/resources

4) Restart the SiteMinder policy server.

Configuring the connector
=========================

The connector requires configuration in both SiteMinder and OpenAM.

* Creating SiteMinder sessions from OpenAM (logging users into SiteMinder with
  their OpenAM session) requires appropriate custom login scheme and realm
  configuration within SiteMinder. Since the SiteMinder sessions are created
  by simply accessing a web resource protected by SiteMinder the configuration
  needed is similar to any SiteMinder protected website. The only major
  difference is that the protected resource must be configured to use OpenAM
  custom authentication scheme. On OpenAM side you need to configure the
  appropriate post-authentication plugins.

* Creating OpenAM sessions from SiteMinder (logging users into OpenAM with
  their SiteMinder session) requires the SMAuthModule to be configured
  in OpenAM and a working SiteMinder web agent installation on the OpenAM
  server host.

* IMPORTANT: The user accounts are looked up in both OpenAM and SiteMinder
  using the username (the login ID the user would normally type into
  a login prompt). Make sure that the SiteMinder user directory configuration
  and OpenAM realm datastore configuration is such that the username
  lookups return the same account.

SiteMinder configuration

1) Create OpenAM custom authentication scheme. The parameters should be:
   Name: OpenAM
   Authentication Scheme Type: Custom Template
   Library: smjavaapi
   Parameter: com.sun.identity.authentication.siteminder.OpenAMAuthScheme debug
   (The "debug" parameter enables debug logging and should be removed for
   production installations.)

2) Create OpenAM domain, realm, rule and policy for session management:
   * Create domain OpenAM and add the user directory.
   * Create realm OpenAM SiteMinder and add the configuration for a resource
     on a SiteMinder protected web server. The server and URL don't really
     matter, the important thing is that the resource is configured to use
     OpenAM custom authentication scheme.
   * Create rule getOpenAMLogin and assign the resource to a file/URL on the
     SiteMinder protected web server, for example "/login.html*". Note that
     you need to add wildcard "*" at the end of the filename because
     SiteMinder adds session query string to the URL when accessing it. Assign
     web agent action GET to this rule.
   * Create policy OpenAM Login Policy and assign users from the directory and
     rule "getOpenAMLogin".

OpenAM configuration

There are multiple modules for different tasks:
   * SiteMinder authentication module that authenticates a user to OpenAM
     using the existing SiteMinder session.
   * SiteMinder session creation plugin that creates a SiteMinder session
     when user successfully logs into OpenAM.
   * SAML2 Adapter for creating a SiteMinder session on succesful federation.

1) SiteMinder authentication module configuration.
   * Add the SiteMinder agent/SDK library directories to LD_LIBRARY_PATH
     of the web container running OpenAM.
   * Create the SiteMinder authentication service:
      ssoadm create-svc -X SMAuthService.xml
   * Register the authentication module:
      ssoadm register-auth-module -a \
      com.sun.identity.authentication.siteminder.SMAuthModule
   * Add the authentication module SMAuthModule to the realm you want to
     use with SiteMinder. Most of the configuration parameters are the same
     as for any SiteMinder agent so see SiteMinder documentation for
     further information.

2) SiteMinder session creation plugin configuration.
   * Edit WEB-INF/classes/SMCreateSessionPlugin.properties to set
     the login URL (see SiteMinder configuration instructions above for
     information about setting up this login URL) and SiteMinder
     session cookie name.
   * Add com.sun.identity.authentication.siteminder.SMCreateSessionPlugin
     to the authentication post processing classes in OpenAM realm
     authentication configuration.

3) SAML2 SP adapter configuration.
   * Add adapter class com.sun.identity.saml2.plugins.SMAdapter to
     the local SAML2 SP properties.
   * Add these parameters to the adapter environment:
     SMLoginURL=<SiteMinder login URL>
     SMCookieName=<SiteMinder cookie name> (Optional, defaults to SMSESSION)

Troubleshooting
===============

The connector uses OpenAM debug logging facility and logs its actions
into "SiteMinder" debug log.

The setsmauthdebug.jsp JSP script can be used to view or change the log
level while the OpenAM server is running. To change the log level you need
to supply the new log level to the JSP as a query string parameter
debugLevel=<debug_level> where the debug level can be message, warning
or error.

NOTE! The setsmauthdebug.jsp does not require any authentication!