OpenSSO Integration with Oracle OpenSSO

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

This README explains the OpenSSO SSO Integration with Oracle Access Manager (OAM) previously known as Oblix. The README must be read in the context of OpenSSO 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 OpenSSO context. The OpenSSO custom authentication enables the SSO integration between legacy OAM and OpenSSO especially when the deployment contains OAM 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. Oracle Access Manager 10g (10.1.4.0.1)   - The Oracle Access Manager must be installed and configured. For more details, check the
    Oracle Access Manager Documenation. You can download from Oracle Web site for evaluation.
3. Oracle Access Manager SDK 10g(10.1.4.0.1) - The Oracle Access Manager SDK must be installed and configured. The SDK is required to compile and
    build OpenSSO Authentication Modules for Oracle Access Manager.
4. Oracle Web Gate installed and configured.
5. OpenSSO C-SDK 2.2


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 OpenSSO 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/oracle" 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.
          OblixAuthService.xml    -  This is OAM  auth module configuration file that must be imported into OpenSSO
          OblixAuthModule.xml   -  This file is used for auth module call backs for theOAM Auth module it is empty. However, the file must be used.
          OblixAuth.properties     -  This file is a properties file that stores i18n keys for OAM 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:
         jobaccess.jar (Oracle OpenSSO SDK jar file)
         openfedlib.jar, amserver.jar, opensso-sharedlib.jar (OpenSSO 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/oblix/OAMAuthModule.java
         com/sun/identity/authentication/oblix/OAMPrincipal.java
         The above java source files are the custom authentication module classes that would be plugged into OpenSSO for generating OpenSSO Session by
          using OAM session.

          com/sun/identity/saml2/plugins/OAMAdapter.java  - This class is a SAML2 Plugin Adapter for SAML service providers to do the remote authentication to
          Oracle OpenSSO using OpenSSO Session. Essentially these java files are used for usecase2 in OpenSSO integration document.

oamauth- This directory contains source files for  OAM Auth Scheme for OpenSSO. This is a C-based auth module and leverages OpenSSO C-SDK for validation.
      oam/solaris/authn_api.c-  This file implements OAM custom authentication for OpenSSO.
      oam/solaris/include/*.h -  All the header files that are required to compile auth scheme.
      oam/solaris/AMAgent.properties  - Sample OpenSSO Agent Configuration file. This is required for the auth scheme to validate OpenSSO session.

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

1.  Make sure all the Oracle Access Manager libraries and OpenSSO 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/oracle and type ant. This should build all the source files and generates fam_oam_integration.jar under
         $openssozipdir/integrations/oracle/dist directory.

For building OAM authentication scheme, you must customize the makefile. Also since this is C-based auth module, it is OS dependent.

1.  The auth scheme files are located under $openssozipdir/integrations/oracle/oamauth/solaris

2. Download and configure OpenSSO C-SDK 2.2 version. The authn_api.c contains a reference to AMAgent.propeties file , so modify accordingly.

3. Customize makefile for your environment for e.g. gcc compile location. Also edit the LDFLAGS to point to your OpenSSO C-SDK lib directory.

4.  make command should result in authn_api.so file.

4. OpenSSO Installation and Configuration with OAM 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/oracle/dist/fam_oam_integration.jar to $WAR_DIR/WEB-INF/lib

3. Copy $openssozipdir/integrations/oracle/config/OblixAuth.properties to $WAR_DIR/WEB-INF/classes

4. Copy $openssozipdir/integrations/oracle/config/OAMAuthModule.xml to $WAR_DIR/config/auth/default and also to the directory
                                                        $WAR_DIR/config/auth/default_en

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

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

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

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

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

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

5. OAM Auth module configuration:
========================

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

1. Login into OpenSSO 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/oracle/config/OblixAuthService.xml and Submit
This will load the auth module service into OpenSSO 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.oblix.OAMAuthModule" 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 "OblixAuth" and choose OblixAuthModule

7. Click on OblixAuth auth module

8. Most of the Oblix Auth params are self explanatory. This requires OAM SDK directory and make sure that  ObAccessClient.xml (located under $OAMSDK/
    oblix/lib) is configured properly. For details on Oracle OpenSSO SDK, check the Oracle Documentation



6. OAM Auth Module Testing:
====================

The testing of OAM auth module assumes that Oracle Access Manager SDK is already installed and configured.

1. Set the LD_LIBRARY_PATH for loading Oblix  SDK libraries.They are located under $OAM_SDK_INSTALL/oblix/lib

2. Restart the OpenSSO web container with LD_LIBRARY_PATH set and make sure that container is loaded with these Oblix  SDK shared libs.

3. Now access the Oblix protected application and login with Oblix configured user to establish ObSessionCookie. The configuration
of  oblix policy and authentication schemes are outside scope of this documentation and please check Oracle Access Manager documentation for more
information.  Also, check the OpenSSO integration guide for sample configuration.

4. By default OpenSSO 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 Oblix's user repository. Check the OpenSSO documentation for more info
about ignoreProfile/dynamic profile creation option.

Admin Console -> Configuration -> Global -> Authentication -> Core -> User Profile required : Change it to dynamic or ignored option
if the repository of Oracle Access Manager is not same as OpenSSO.

5. After successful authentication at Oracle OpenSSO, access the OpenSSO auth module url as follows:

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

This should provide a valid OpenSSO session.

Note: Assumption here is that OAM and OpenSSO are in the same physical domain.

By default OpenSSO 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 Oracle Access Manager's user repository. Check the OpenSSO documentation
for more info about ignoreProfile option.

7. Installation of  OAM AuthScheme into Oracle OpenSSO:
=========================================

This section is for a use case where the OAM session needs to be generated upon validating OpenSSO session.  Check the integration document for
use case descriptions. The OAM Auth Schemes are exposed as C Auth modules and this auth scheme uses OpenSSO C-SDK 2.2 version to validate
OpenSSO Session.

The OpenSSO Auth Scheme in OAM uses a configuration OpenSSO client side configuration in AMAgent.properties and this must need to be customized
before configuring the auth module. The build instructions specify the location of this file.

The compiled authn_api.so and other C-SDK libraries must need to be copied to $OAM_INSTALL_DIR/access/oblix/lib before configuring the
 Auth Scheme. The integration guide shows a sample screen shot how to configure the Oracle Auth Scheme.