OpenAM Integration with CA Siteminder

=====================================================================

This README explains the OpenAM Server SSO Integration with Computer Associates (CA) SiteMinder. The README must be read in the context of OpenAM Integration Document where the use cases, possible integrations and configurations are described in detail.

This README explains the custom codes for e.g. Authentication Modules, compilation instructions and the configuration of the auth modules for OpenAM context. The OpenAM custom authentication enables the SSO integration between legacy Siteminder (SM) access server and OpenAM especially when the deployment contains SM for protecting existing applications.

1. Pre-requisites :
==========

1. opensso.zip    - This zip file contains all the integration souce code, configuration files and ofcourse this README file along with regular opensso.war
2. Siteminder server 6.0 SP4 or higer version - The siteminder server must be installed and configured. For more details, check siteminder documentation. For OpenAM
    related configuration, check the OpenAM integration document. There are no trial versions available for Siteminder libraries or for other siteminder components. This
    document assumes that the user has minimal knowledge on Siteminder components and knows how to get them.
3. Siteminder SDK 6.0 SP4 or higher version - The siteminder SDK must be installed and configured. The SDK is required to compile and build Federated
    OpenAM Authentication Modules for Siteminder.
4. Siteminder Agent installed and configured.

2. Brief Description of Contents:
======================

The opensso/integrations directory contains source and configurations to compile and build the custom authentication modules and other plugins. Check the OpenAM integration document for your use case and configure accordingly. This document provides instructions on how to configure authentication modules

The opensso.zip contains "opensso/integrations/siteminder" directory where the source code and configurations are in place..

Readme.html - This file.

build.xml - This file is a build script for building

config - This directory contains auth module configuration files.
          SMAuthService.xml    - This is siteminder auth module configuration file that must be imported into OpenAM
          SMAuthModule.xml   - This file is used for auth module call backs and for Siteminder auth module they are empty. However, the file must be used.
          SMAuth.properties     - This file is a properties file that stores i18n keys for siteminder authentication module configuration lables.

lib - This directory is by default empty . However, this lib directory must contain all the necessary libraries to compile the source libraries. They are:
         smjavaagentapi.jar, SmJavaApi.jar (Siteminder jar files)
         openfedlib.jar, amserver.jar, opensso-sharedlib.jar (OpenAM jar files)
         servlet .jar file (If it's Glassfish, it is javaee.jar)

source - This directory contains all the source files

   com/sun/identity/authentication/siteminder/SMAuthModule.java
         com/sun/identity/authentication/siteminder/SMPrincipal.java
         The above java source files are the custom authentication module classes that would be plugged into OpenAM for generating OpenAM Session by
using Siteminder session.

      com /sun/identity/authentication/siteminder/FAMAuthScheme.java   - This class provides codes for Siteminder AuthScheme Plugin class for generating
          Siteminder session using OpenAM session.
          com/sun/identity/saml2/plugins/SMAdapter.java - This class is a SAML2 Plugin Adapter for SAML service providers to do the remote authentication to
      Siteminder using OpenAM Session. Essentially these java files are used for usecase2 in OpenAM integration document.


3: How to build:
===========

1. Make sure all the siteminder libraries and OpenAM libraries present in lib directory as mentioned above.

2. Use "ant" script to build the source files. A compatible ant must be installed and configured in the PATH.

3. cd $openssozipdir/integrations/siteminder and type ant. This should build all the source files and generates fam_sm_integration.jar under
   $openssozipdir/integrations/siteminder/dist directory.


4. OpenAM Installation and Configuration with Siteminder AuthModule:
=================================================

1. Create a temporary directory for e.g. /export/tmp and unwar the opensso.war using jar -xvf opensso.war.
    From now on, /export/tmp is called as a war staging area and is represented with a marco $WAR_DIR

2. Copy $openssozipdir/integrations/siteminder/dist/fam_sm_integration.jar to $WAR_DIR/WEB-INF/lib

3. Copy Siteminder jar files smjavaagentapi.jar and SmJavaApi.jar to $WAR_DIR/WEB-INF/lib

4. Copy $openssozipdir/integrations/siteminder/config/SMAuth.properties to $WAR_DIR/WEB-INF/classes

5. Copy $openssozipdir/integrations/siteminder/config/SMAuthModule.xml to $WAR_DIR/config/auth/default and also to the directory
$WAR_DIR/config/auth/default_en

6. Re-war opensso.war using jar cvf opensso.war from $WAR_DIR

7. Deploy opensso.war onto OpenAM web container. The deployment is self explanatory. Please check the web container documentation for war
deployment.

8. Access the deployed opensso directory
          http://<host>:<port>/opensso

9. Accessing deployed application redirects to opensso configurator. Choose custom configuration. By default OpenAM uses embedded directory
server for configuration, however, you could choose to use existing or a new directory server instance for configuration.

Note: The OpenAM can be configured to use various user repository for validating the user existance, however, you could also choose to ignore profile.

10. After successful configuration, the configuration redirects to a user login and verify your administrator credentials.

5. Siteminder Auth module configuration:
===========================

Now we have to load the Siteminder authentication module service into Open SSO and configure for the SSO integration. The auth module service
is loaded from a OpenAM command line utility called as "ssoadm". For OpenAM, the ssoadm utitily is exposed in both console mode and browser based
interfaces. Here we will use use browser based ssoadm for OpenAM configuration changes.

1. Login into OpenAM using amadmin

2. Now access the following URL
http://<host>:<port>/opensso/ssoadm.jsp

3. Choose create-service option.

4. Copy and paste the xml file from $openssozipdir/integrations/siteminder/config/SMAuthService.xml and Submit
This will load the auth module service into OpenAM configuration.

5. Register the auth module into the authentication core framework.

http://<host>:<port>/opensso/ssoadm.jsp
Choose register-auth-module option.
Enter "com.sun.identity.authentication.siteminder.SMAuthModule" as the auth module class name.

6. Now verify that the auth module is registered to the default realm. http://<host>:<port>/opensso, click on default realm, and click on
"authentication" tab, create new AuthModule as "SMAuth" and choose SMAuthModule

7. Click on SMAuth auth module

8. Most of the SM Auth params are self explanatory and does not need to be changed.

Shared Secret: is a secret password between siteminder SDK and siteminder policy server. For more information, check the siteminder
documentation. If you have agent installed, you can use agent's shared secret here which is available from SmHost.Conf
Policy Server IP Address: IP Address of Site minder policy server
Trusted host name: Agent/SDK host name
HTTPHeaders: If you have configured SMPolicyServer/SMAgent to send HTTPHeaders to the applications, enter the same
HTTP Header names here so that they could be uploaded to the OpenAM session. Also, the same could be sent to SAML Assertion
by using SAML Attribute configuration mapper. For details on SAML Attribute mapping, check the OpenAM integration documentation.

Configure as appropriate and save the configuration.

If you have configured to use HTTP headers, go to step 9.

9. Configure POST Authentication SPI plugin.
Go to Configuration->Authentication->Core->Ream Attributes and under Authentication Post Processing classes add
    "com.sun.identity.authentication.siteminder.SMPostAuthPlugin".

6. Siteminder Auth Module Testing:
=======================

The testing of site minder assumes that siteminder SDK is already installed and configured. Please check the siteminder documentation
for siteminder SDK installation.

1. Set the LD_LIBRARY_PATH for loading siteminder SDK libraries.They are located under $SM_SDK_INSTALL/sdk/bin

2. Restart the OpenAM web container with LD_LIBRARY_PATH set and make sure that container is loaded with these site minder SDK shared libs.

3. Now access the siteminder protected application and login with siteminder configured user to establish SMSESSION. The configuration
of siteminder policy and authentication schemes are outside scope of this documentation and please check siteminder documentation for more
information.

4. After successful authentication at siteminder server, access the OpenAM auth module url as follows:

http://<host>:<port>/opensso/UI/Login?module=SMAuth

This should provide a valid OpenAM session.

Note: Assumption here is that siteminder and OpenAM are in the same physical domain.

By default OpenAM authentication framework looks for user profile existance in it's known data repositories. However, you could use ignoreProfile
option if your integration does not require a user to be searched from siteminder's user repository. Check the OpenAM documentation for more info
about ignoreProfile option.

7. Installation of FAMAuthScheme into Siteminder:
==================================

This section is for a use case where the siteminder session needs to be generated upon validating OpenAM session. The FAMAuthScheme class
implements Siteminder java SPI to configure a custom authentication module. The integration dcoumentation guide describes in detail how to
configure the custom OpenAM Authentication Scheme in Siteminder.