Install SSO Servlet Partner Application using ssosdk902

PURPOSE
-------
Provide step by step instruction for a 'Proof of concept' quick installation
of SSO Servlet Partner Application in Oracle9i Application Server (9iAS)
Release 2 (9.0.2)


SCOPE & APPLICATION
-------------------
Using ssosdk902.zip provided with the 9iAS V2 install, this articles provides
the steps required to install a demo SSO Servlet Partner Application.  Detailed
information is provided in the ReadMe.txt(s) that are included in the ssosdk902.zip.
Since this is a 'Proof of concept' installation only.  Steps taken should be
undone after testing is completed.

If "SSO servlet application" is installed into a non-midtier application server
(eg. 9iAS 1022, etc)
o Replace all references of midtier.acme.com in this article with hostname of
   the non-midtier application server
o Replace all references of midtier.acme.com port 7777 in this article with
   the listen port of the non-midtier application server


Install SSO Servlet Partner Application using ssosdk902
-------------------------------------------------------

Pre-requisites:
---------------
-This applies to both Infrastructure and Mid-tier machines.
-unzip, javac and java must be in PATH environment variable
-Bourne shell syntax used for all Unix commands
-Infrastructure database and Oracle HTTP Server (OHS) are started
-Mid Tier instance is started.
-Mid Tier instance used is for testing only.


Sample setup configuration used in this article:
------------------------------------------------
-You may need to modify certain Sample configuration to suit your environment

Mid-tier Hostname:      midtier.acme.com
Mid-tier listener Port: 7777

Infrastructure Hostname:                          infra.acme.com
Infrastructure Database Name:                     iasdb
SSO Servlet Database schema username/password:    mysso/mysso
Database for storing SSO servlet database schema: iasdb
Database (iasdb) sqlnet listener port:            1521



Table of Contents
-----------------
Section 1 - Install SSO Servlet application on mid-tier install
Section 2 - Creating the Partner Application
Section 3 - Install SSOsdk plsql package on infra.acme.com
Section 4 - Test the application
Section 5 - Troubleshooting
Section 6 - Removing the SSO Servlet Partner Application


###################################################################
# Section 1 - Install SSO Servlet application on mid-tier install #
###################################################################
-On midtier.acme.com do following to create and install the SSO test servlets

1-1. Set ORACLE_HOME, and PATH environment Variables

  ORACLE_HOME=/u90/app/oracle/product/um
  PATH=$ORACLE_HOME:$PATH
  export ORACLE_HOME PATH

1-2. Create a temporary directory for storing the SSO SDK

  mkdir /tmp/ssosdk902

1-3. Copy the provide SSO SDK zip file (ssosdk902.zip) to /tmp/ssosdk902

  cp $ORACLE_HOME/sso/lib/ssosdk902.zip /tmp/ssosdk902

1-4. Unbundle ssosdk902.zip

  cd /tmp/ssosdk902
  unzip ssosdk902.zip

1-5. Copy two SSOEnabler Beans to servlet directory

  cd /tmp/ssosdk902/demo/java
  cp beans/SSOEnablerServletBean.java servlet
  cp beans/SSOEnablerBean.java  servlet

1-6. Grant write permission to the java source files

  cd /tmp/ssosdk902/demo/java/servlet
  chmod 744 *java

1-7. Modify SSOEnablerBean.java, change following section
From:
   m_connCache.setURL("jdbc:oracle:thin:@"
    + p_hostname + ":" + p_port + ":" + p_sid );

   m_connCache.setUser(p_schema);
   m_connCache.setPassword(p_password);

   m_connCache.setMaxLimit(p_dbPoolSize);

To:
   m_connCache.setURL 
    ("jdbc:oracle:thin:@infra.acme.com:1521:iasdb");

   m_connCache.setUser("mysso");
   m_connCache.setPassword("mysso");
   m_connCache.setMaxLimit(3);

1-8. Modify SSOEnablerServletBean.java, change following section
  From:
   // Partner application  session cookie name
   private static String m_cookieName     = "SSO_PAPP_SERVLET_ID";

   // Host name of the database
   private static String m_dbHostName     = "wwssosvr.us.oracle.com";
   // Port for database
   private static int    m_dbPort         = 9521;
   // Sehema name
   private static String m_dbSchemaName   = "papp";
   // Schema password
   private static String m_dbSchemaPasswd = "papp";
   // Database SID name
   private static String m_dbSID          = "orcl9i";

To:
   // Partner application  session cookie name
   private static String m_cookieName     = "v1.2";

   // Host name of the database
   private static String m_dbHostName     = infra.acme.com";
   // Port for database
   private static int    m_dbPort         = 1521;
   // Sehema name
   private static String m_dbSchemaName   = "mysso";
   // Schema password
   private static String m_dbSchemaPasswd = "mysso";
   // Database SID name
   private static String m_dbSID          = "iasdb";

1-9. Set CLASSPATH
CLASSPATH=.:$ORACLE_HOME/lib/servlet.jar:/
$ORACLE_HOME/jlib/jndi.jar:/
$ORACLE_HOME/lib/jndi.jar:/
$ORACLE_HOME/jdbc/lib/classes12.zip:/
$ORACLE_HOME/jdbc/lib/nls_charset12.zip:/
/tmp/ssosdk902/jlib/ssosdk902.jar

export CLASSPATH

1-10. Compile the five java programs in /tmp/ssosdk902/demo/java/servlet

  cd /tmp/ssosdk902/demo/java/servlet
  javac *java

1-11. Will be using dcmctl commands, first shutdown EM, this is a restriction in
      9.0.2, check with future releases to see if this restriction has been removed

  emctl stop

1-12. Copy the class files to J2EE home instance.
      Note: This is proof of concept sample only.  The proper way to deploy the
            application would be using either WAR or EAR file. Following steps
            to be used against test J2EE instance only

  cd $ORACLE_HOME/j2ee/home/default-web-app/WEB-INF/classes
  cp  /tmp/ssosdk902/demo/java/servlet/*class .

1-13. Make jdbc and ssosdk jar files available for use by the SSO Servlet application.
      If clases12.jar or ssosdk902.jar already exist, please verify if they can
      be overwritten

  cd $ORACLE_HOME/j2ee/home/default-web-app/WEB-INF/lib
  cp $ORACLE_HOME/jdbc/lib/classes12.jar  .
  cp /tmp/ssosdk902/jlib/ssosdk902.jar .

1-14. Restart J2EE Home instance

  dcmctl restart -co home



################################################
# Section 2 - Creating the Partner Application #
################################################

2-1. Connect to SSO Admin Page from browser

http://infra.acme.com:7777/pls/orasso

2-2. Click on 'Login'
Username: orcladmin
Password: same password as ias_admin

2-3. Click on 'SSO Server Administration' -> 'Administer Partner Applications'
     -> 'Add Partner Application'

2-4. Enter following to add a Partner Application
Name: SSO SDK Test
Home URL: http://midtier.acme.com:7777/j2ee/servlet/SSOPartnerServlet
Success URL: http://midtier.acme.com:7777/j2ee/servlet/SSOSignOnServlet
Logout URL: http://midtier.acme.com:7777/j2ee/servlet/SSOPartnerLogoutServlet
End Date: Leave this field blank
Administrator Email: Leave this field blank
Administrator Information: Leave this field blank

2-5. Click on 'Apply'.  The screen should now display information such as ID,
     Token, etc.  Keep this screen open for steps to be performed in next section.


##############################################################
# Section 3 - Install SSOsdk plsql package on infra.acme.com #
##############################################################

-Install SSOsdk plsql applications on infra.acme.com, using database iasdb
-Run following steps from infra.acme.com
-ORACLE_HOME, ORACLE_SID and PATH must be set to Infrastructure and iasdb

3-1. Create a temporary directory for storing the SSO SDK

  mkdir /tmp/ssosdk902

3-2. Copy ssosdk902.zip to a /tmp/ssosdk902

  cp $ORACLE_HOME/sso/lib/ssosdk902.zip /tmp/ssosdk902

3-3. Unbundle ssosdk902.zip

  cd /tmp/ssosdk902
  unzip ssosdk902.zip

3-4. cd to SSO SDK plsql packages directory. Connect to iasdb as sys, create
     mysso user, and run loadsdk.sql

  cd /tmp/ssosdk902/packages  
  sqlplus '/ as sysdba'
   create user mysso identified by mysso;
   grant resource, connect to mysso;
   connect mysso/mysso
   @loadsdk
   --Need to exit sqlplus here to reset sqlplus settings for next step
   exit 

3-5. Connect to iasdb as mysso user, run regapp.sql to register 'SSO SDK Test'
     Partner application.  Enter values using information from step 2-5. 
     Below are sample values only.

   sqlplus mysso/mysso
   @regapp
    Enter value for listener_token: midtier.acme.com:7777
    Enter value for site_id: 1332
    Enter value for site_token: 1LF8K6CG1332
    Enter value for login_url: http://infra.acme.com:7777/pls/orasso/orasso.wwsso_app_admin.ls_login
    Enter value for encryption_key: 4C2DBA45C75377D5
    Enter value for ip_check: N (Note: The 'N' must be uppercase)



####################################
# Section 4 - Test the application #
####################################


4-1. Start a new browser and connect to the SSO SDK test application
http://midtier.acme.com:7777/j2ee/servlet/SSOPartnerServlet


4-2. If everything is configured properly.  The 'Single Sign-On' page will be
     displayed.  Enter a single sign-on username/password.  Or you can use 'orcladmin'.

4-3. After a successful login, the following will be displayed
      "Servlet based SSO Partner Application
       User Information: ORCLADMIN/DEFAULT COMPANY"

4-4. Click on 'Logout, the 'Single Sign-off' page will be displayed.  For each
     Application that has been successfully logged out, the will be a check mark
     under 'Logout Status'


###############################
# Section 5 - Troubleshooting #
###############################

5-1. Display registration information.  Connect to iasdb as mysso and run
     following sql statement

    sqlplus> select * from wwsec_enabler_config_info$;

5-2.  See error log for debugging.  Connect to iasdb as mysso and run following
      sql statement

   cd /tmp/ssosdk902/packages
   sqlplus mysso/mysso
   @secdbg.sql
   --Run servlet again to reproduce error.  Then run following sql statement.
   select * from wwsec_sso_log$;


############################################################
# Section 6 - Removing the SSO Servlet Partner Application #
############################################################
-Steps 6-1 to 6-3 to be performed against the midtier install
-ORACLE_HOME must be set to midtier install

6-1. Stop J2EE Home instance on midtier.acme.com
  emctl stop
  dcmctl stop -co home

6-2. Remove the 5 SSO demo class files installed in step 1-12
     o SSOPartnerLogoutServlet.class
     o SSOEnablerBean.class
     o SSOPartnerServlet.class
     o SSOEnablerServletBean.class  
     o SSOSignOnServlet.class

  cd $ORACLE_HOME/j2ee/home/default-web-app/WEB-INF/classes
  -Move or delete the above 5 files.

6-3. Remove the jdbc and ssosdk jar files installed in step 1-13
     o classes12.jar
     o ssosdk902.jar

cd $ORACLE_HOME/j2ee/home/default-web-app/WEB-INF/lib
-Move or delete the above 2 files. See Note below.

Note: If file(s) already exist before start of this demo install. 
       Do not remove the file(s), file(s) may be used by another application.

6-4. Remove 'SSO SDK Test' Partner Application. Connect to SSO Admin Page from browser

http://infra.acme.com:7777/pls/orasso

6-5. Click on 'Login'

Username: orcladmin
Password: same password as ias_admin

6-6. Click on 'SSO Server Administration' -> 'Administer Partner Applications'
     -> Click on 'X' to delete 'SSO SDK Test' Application.