Sun Java System Access Manager version 7 2005Q4

Single Sign On Samples

    1. Introduction

    This Readme file explains how to compile and run a sample Single Sign on
	(SSO) application for Solaris
     & Windows installations.	These samples are in the form of either standalone Java application or Java servlets. Below is the list of all the SSO sample programs and their descriptions:
    
    1. CommandLineSSO.java
       Description: This sample creates a new sso token given a valid sso token id.
       Type: Standalone Java program.
       Input: Token id.
       Output: Basic SSO token information.
       
		
    2. SDKCommandLineSSO.java
       Description: This sample demonstrates the usage of retrieving the user profile given the correct user credetials.
       Type: Standalone Java program.
       Input: Organization name (in DN format).
       Output: User profile attributes.
       
		
    3. SSOTokenSample.java
       Description: This sample serves as a basis for using SSO API. It demonstrates creating an SSO token and calling various methods from the token including getting/setting the session properties.
       Type: Standalone Java program. 
       Input: Token id.
       Output: Basic SSO token information and session properties.
       
		
    4. SDKSampleServlet.java
       Description: This sample demonstrates the usage of retrieving the user profile given the valid cookie set in the browser.
       Type: Java Servlet.
       Input: None, but require AM session cookie set in the browser.
       Output: SSO token information and user profile attributes.
       
		
    5. SSOTokenSampleServlet.java/SampleTokenListener.java
       Description: This sample serves as a basis for using SSO API given the valid cookie set in the browser. It also demonstrates the functionality of Session Notification as well as getting/setting the session properties. 
       Type: Java Servlet. 
       Input: None, but require AM session cookie set in the browser.
       Output: Basic SSO token information and session properties.
       
		



    2. Instructions for Solaris

    2.1 Run the SSO sample programs from the Access Manager server
    
    1. Set these environment variables. These environment variables will be
       used the run the make command. You can also set these variables in the
       Makefile which can be found in the same directory as sample
       files.
       
       BASE - Set this variable to install directory
       CLASSPATH - Reference to all the jars found in directory
          <INSTALL_DIR>/SUNWam/lib
       JAVA_HOME - Set this variable to your installation of JDK. It should be
          newer than JDK 1.3.1
       BASE_CLASS_DIR - Directory where all the Sample compiled classes will
          be kept.
       JAR_DIR - Directory where the jar of the sample classes will be created.
          Default is the current directory.
       
    
    2. Go to the directory "<INSTALL_DIR>/SUNWam/samples/sso".
       Run gmake.
    
    3. Go to the the directory JAR_DIR. copy the SSOSample.jar
       file to the "<INSTALL_DIR>/SUNWam/lib" directory.
    
    4. Add "<INSTALL_DIR>/SUNWam/lib/SSOSample.jar" to web
       container's classpath (e.g. 
       "<WEB_SERVER_INSTALL_DIR>/https-machine.domain.name/config/server.xml).
    
    5. Now it is required to register the Sample servlet. Insert these lines
       (as described below) in the file
       "<WEB_SERVER_INSTALL_DIR>/https-machine.domain.name/is-web-apps/services/WEB-INF/web.xml".
       These lines should be put just after the last "</servlet>" tag.
       
       <servlet>
       <servlet-name>SSOTokenSampleServlet</servlet-name>
       <description>SSOTokenSampleServlet</description>
       <servlet-class>SSOTokenSampleServlet</servlet-class>
       </servlet>
       
       These lines should be put just after the last </servlet-mapping> tag.
       
       <servlet-mapping>
       <servlet-name>SSOTokenSampleServlet</servlet-name>
       <url-pattern>/SSOTokenSampleServlet</url-pattern>
       </servlet-mapping>
       
    
    6. Restart the server and login to the Access Manager console.
    
    7. The user executing SSOTokenSampleServlet must have authorization to
       access that resource. Otherwise the request will be denied. Refer to the
       policy setting instructions in the Administration Guide.
    
    8. Open a browser and visit
       "<protocol>://<host>:<port>/<deploy-uri>/SSOTokenSampleServlet"
    
    9. Your sample program should display the output in the browser. Here host
    must be a fully qualified name.
    


	To run another sample servlet (SDKSampleServlet), follow the same steps as described above.
    
    2.2 Run the SSO sample programs on the remote client within a web container.
     Install the Access Manager Client SDK in web container and perform the following steps. The following steps assume Sun Java System Web Server is installed in
    /iws directory and the Access Manager remote client was installed in
    /opt.
    
    * Go to the directory "<INSTALL_DIR>/SUNWam/samples/sso".
	Run gmake.
	
    * Add (it it's not there) /opt/SUNWam/samples/sso/SSOSample.jar /opt/SUNWam/lib/am_sdk.jar, /opt/SUNWam/lib/jaas.jar, /usr/share/lib/mps/secv1/jss4.jar,
       /opt/SUNWam/lib/jaxp.jar, /opt/SUNWam/lib/dom.jar and /opt/SUNWam/lib/xercesImpl.jar to the web
       server's classpath. (Note: Include jaas.jar in your classpath only if
       you are using JDK version less than JDK1.4).
    
    * Add (it it's not there) /opt/SUNWam/locale and /opt/SUNWam/lib directories to the web server's classpath
    
    * Add (it it's not there) java.protocol.handler.pkgs=com.iplanet.services.comm to as an
       argument to be passed into the VM of the web server
    
    * Restart Sun Java System Web Server.
    


    NOTE: If the Access Manager is running SSL you may need to add the
    following line to AMConfig.properties for testing purposes
    (com.iplanet.am.jssproxy.trustAllServerCerts=true). This property tells
    the SSL client in the SDK to trust all certificates presented
    from the servers. This allows you to test SSL without having
    them root CA for your test cert installed on the this client. Otherwise,
    you would need to install SSL Server's rootCA certificate in client's
    trust database and make sure that the following properties in
    AMConfig.properties are set to the same.
    
    com.iplanet.am.admin.cli.certdb.dir
    com.iplanet.am.admin.cli.certdb.prefix
    com.iplanet.am.admin.cli.certdb.passfile
    
    
    Running the sample
    
    1. cd /opt/SUNWam/samples/sso
    
    2. It is required to register the Sample servlet. Insert these lines
       (as described below) in the file
       "<WEB_SERVER_INSTALL_DIR>/https-machine.domain.name/is-web-apps/services/WEB-INF/web.xml".
       These lines should be put just after the last "</servlet>" tag.
       
       <servlet>
       <servlet-name>SSOTokenSampleServlet</servlet-name>
       <description>SSOTokenSampleServlet</description>
       <servlet-class>SSOTokenSampleServlet</servlet-class>
       </servlet>
       
       These lines should be put just after the last </servlet-mapping> tag.
       
       <servlet-mapping>
       <servlet-name>SSOTokenSampleServlet</servlet-name>
       <url-pattern>/SSOTokenSampleServlet</url-pattern>
       </servlet-mapping>
       
    
    3. Restart the web container where the AM SDK is installed.
    
    4. Login to Access Manager (on separate web constainer instance) and then invoke the servlet with
       http://amsdk-server.sub.domain/servlet/SSOTokenSampleServlet
    
    5. This servlet validates the session and prints out all relevant
       session information. You may have to reload the URL to see updated
       information.
    
    6. Now logout from Access Manager and invoke the servlet again. You
       will see a session exception. Again you may have to reload the URL.
    


    2.3 Run the SSO sample programs on the remote client in command line
    Command line SSO assumes your application is not running in a web container, but does have access to the cookies from the HTTP requests. Your application will have to extract the Access Manager cookie from the request and pass the string value of the cookie into the createSSOToken method. Notifications are are only supported in a web container.
    
    Install the Access Manager Client SDK and perform the following steps:
    
    1. Go to the directory "<INSTALL_DIR>/SUNWam/samples/sso".
       Run gmake.
    
    2. Modify "<INSTALL_DIR>/SUNWam/samples/sso/run" script to execute the sample program that you want to test. For example, to run SDKCommandLineSSO.java, replace CommandLineSSO with SDKCommandLineSSO at the last line "${JAVA_EXEC} -Xbootclasspath ...SDKCommandLineSSO $@"in the script.

    
    3. Add /opt/SUNWam/lib/jaas.jar to your classpath if you are using JDK version less than JDK1.4).
    
    4. When the server is running SSL you will need to add the following
       VM argument in the "<INSTALL_DIR>/SUNWam/samples/sso/run" script when executing your java code.
       
       java.protocol.handler.pkgs=com.iplanet.services.comm
    


    To test the command line you can run the servlet test above, cut and paste
    the cookievalue and pass it in as the tokenvalue.
    Example:
    
    1. Access servlet
        http://test-server.red.iplanet.com:58080/amserver/SSOTokenSampleServlet
    
    2. You will get following output:
       
       SSOToken host name: 123.123.123.123 (Your server's ip address)
       SSOToken Principal name: uid=amAdmin,ou=People,dc=example,dc=com
       Authentication type used: LDAP
       IPAddress of the host: 123.123.123.123 (Your server's ip address)
       The token id is AQIC5wM2LY4Sfcwbdp3gWuB38NA26klnTJlLPknN8t0fPVY=
       Property: Company is - Sun Microsystems
       Property: Country is - USA
       SSO Token Validation test Succeeded
       
    
    3. Run command with (in "<INSTALL_DIR>/SUNWam/samples/sso" directory)
       run "AQIC5wM2LY4Sfcwbdp3gWuB38NA26klnTJlLPknN8t0fPVY="
       And the result will be the followings:
       
       SSO "AQIC5wM2LY4Sfcwbdp3gWuB38NA26klnTJlLPknN8t0fPVY="
       SSOToken host name: 123.123.123.123 (Your server's ip address)
       SSOToken Principal name: uid=amAdmin,ou=People,dc=example,dc=com
       Authentication type used: LDAP
       IPAddress of the host: 123.123.123.123 (Your server's ip address)
       
    



    3. Instructions for Windows

    1. Set these environment variables. These environment variables will be
       used the run the make command. You can also set these variables in the
       Makefile. This Makefile is in the same directory as sample files.
       
       BASE - Set this Variable to install directory <INSTALL_DIR>
       CLASSPATH - Reference to all the jars found in directory
          <INSTALL_DIR>\lib
       JAVA_HOME - Set this variable to your installation of JDK. It should be
          newer than JDK 1.3.1.
       BASE_CLASS_DIR - Directory where all the Sample compiled classes will be
          kept.
       JAR_DIR - Directory where the jar of the sample classes will be created.
          Default is the current directory.
       
    
    2. Go to the directory <INSTALL_DIR>\samples\sso and do
       
       make
       
    
    3. Go to the the directory JAR_DIR. copy the SSOSample.jar file to
       the "<INSTALL_DIR>\lib" directory.
    
    4. Now it is required to register the Sample servlet. Insert these lines
       (as described below) in the file
       "<WEB_SERVER_INSTALL_DIR>\https-machine.domain.name\is-web-apps\services\WEB-INF\web.xml". 
       These lines should be put just after the last "</servlet>" tag.
       
       <servlet-name>SSOTokenSampleServlet</servlet-name>
       <description>SSOTokenSampleServlet</description>
       <servlet-class>SSOTokenSampleServlet</servlet-class>
       </servlet>
       
       These lines should be put just after the last "</servlet-mapping>" tag.
       
       <servlet-mapping>
       <servlet-name>SSOTokenSampleServlet</servlet-name>
       <url-pattern>/SSOTokenSampleServlet</url-pattern>
       </servlet-mapping>
       
    
    5. Restart the server and login to the Access Manager console.
    
    6. The user executing SSOTokenSampleServlet must have authorization to
       access that resource. Otherwise the request will be denied. Refer to the
       policy setting instructions in the Administration Guide.
    
    7. Type in the browser
       <protocol>://<host>:<port>/<deploy-uri>/SSOTokenSampleServlet
    
    8. Your sample program should display the output in the browser. Here
       host must be a fully qualified name.
    


    To Install the SSO SDK on a remote client for use within a web container:
    Install the IS2005Q4_sdk.zip and perform the following steps:
    
    * Copy jss4.dll to a directory in the web server's Path
    
    * Add am_sdk.jar, jaas.jar, jss4.jar, jaxp.jar,
       dom.jar and xercesImpl.jar to the web server's classpath.(Note:
       Include jaas.jar in your classpath if you are using JDK version less
       than JDK 1.4)
    
    * Add the locale and lib directories to the web server's classpath
    
    * Add java.protocol.handler.pkgs=com.iplanet.services.comm to as an
       argument to be passed into the VM of the web server.
    


    The following steps assume Sun Java System Web Server is install in \iws
    and the IS2005Q4 remote client was installed in C:\sso\IS2005Q4_sdk\
    
    1. Copy C:\sso\IS2005Q4_sdk\lib\jss4.dll to /iws/bin/https/lib
    
    2. Append SSOSample.jar, am_sdk.jar, jaas.jar, jss4.jar,
       jaxp.jar, dom.jar, xercesImpl.jar, locale and lib
       to the 'serverclasspath' attribute of <JAVA> XML tag i
       server.xml (Note: Include jaas.jar in your classpath if you are using
       JDK version less than JDK 1.4)
    
    3. Add java.protocol.handler.pkgs=com.iplanet.services.comm to
       <JVMOPTIONS>XML tag in server.xml
       
       serverclasspath=/iws/plugins/servlets/examples/legacy/beans.10/SDKBeans10.jar;
       /sso/SUNWam/lib/am_sdk.jar;/sso/SUNWam/lib/jss4.jar;/sso/SUNWam/locale;
       /sso/SUNWam/lib;/sso/SUNWam/lib/jaas.jar;/sso/SUNWam/samples/sso;
       /sso/SUNWam/lib/jaxp.jar;/sso/SUNWam/lib/dom.jar;/sso/SUNWam/lib/xercesImpl.jar
       <JVMOPTIONS>-Djava.protocol.handler.pkgs=com.iplanet.services.comm</JVMOPTIONS>
       
    
    4. You may also add the C:\sso\IS2005Q4_sdk\samples\sso directory above if
       you wish to run the samples
    
    5. Restart Sun Java System Web Server.
    


    NOTE: If the Access Manager server is running SSL you may need to add
    the following line to AMConfig.properties for testing purpose
    (com.iplanet.am.jssproxy.trustAllServerCerts=true). This line tells the
    SSL client in the SDK to trust all certificates presented from the
    servers. This allows you to test SSL without having the root CA for your
    test cert installed on the this client. Otherwise, you would need to
    install SSL Server's rootCA certificate in client's trust database
    and make sure that the following properties in AMConfig.properties are set to
    the same.
    
    com.iplanet.am.admin.cli.certdb.dir
    com.iplanet.am.admin.cli.certdb.prefix
    com.iplanet.am.admin.cli.certdb.passfile
    
    
    Running the sample
    
    1. cd C:\sso\IS2005Q4_sdk\samples\sso
    
    2. make
    
    3. Login to Access Manager and then invoke the servlet with
        http://server.sub.domain/servlet/SSOTokenSampleServlet
    
    4. This servlet validates the session and prints out all relevant
       session information. You may have to reload the URL to see updated
       information.
    
    5. Now logout from Access Manager and invoke the servlet again. You
        will see a session exception. Again you may have to reload the URL.
    


    Installing the remote client for use in commandline
    Command line SSO assumes your application is not running in a web container,
    but does have access to the cookies from the HTTP requests. Your
    application will have to extract the Access Manager cookie from the request
    and pass the string value of the cookie into the createSSOToken method.
    Notifications are are only supported in a web container.
    
    Install the IS2005Q4_sdk.zip and perform the following steps:
    
    1. Add c:\sso\IS2005Q4_sdk\lib to your PATH
    
    2. Add am_sdk.jar, jaas.jar, /usr/share/lib/mps/jss4.jar, jaxp.jar,
       dom.jar and xercesImpl.jar to your classpath. (Note: Include
       jaas.jar in your classpath if you are using JDK version less than JDK 1.4)
    
    3. Add the locale and lib directories to your classpath.
    
    4. When the server is running SSL you will need to add the following
       VM argument when executing your java code.
       
       java.protocol.handler.pkgs=com.iplanet.services.comm
    
    5. See NOTE above when running with SSL
    


    To execute the sample:
    
    java -D"java.protocol.handler.pkgs=com.iplanet.services.comm"
       CommandLineSSO tokenvalue
    
    To test the command line you can run the servlet test above, cut and paste
    the cookievalue and pass it in as the tokenvalue.
    Example:
    
    1. Access servlet
       "http://test-server.red.iplanet.com:58080/amserver/SSOTokenSampleServlet"
     
    2. You will get following output:
       
       SSOToken host name: 123.123.123.123 (Your server's ip address)
       SSOToken Principal name: uid=amAdmin,ou=People,dc=example,dc=com
       Authentication type used: LDAP
       IPAddress of the host: 123.123.123.123 (Your server's ip address)
       The token id is AQIC5wM2LY4Sfcwbdp3gWuB38NA26klnTJlLPknN8t0fPVY=
       Property: Company is - Sun Microsystems
       Property: Country is - USA
       SSO Token Validation test Succeeded
       
     
    3. Run command with sid "AQIC5wM2LY4Sfcwbdp3gWuB38NA26klnTJlLPknN8t0fPVY=".
       And will followings:
       
       SSO "AQIC5wM2LY4Sfcwbdp3gWuB38NA26klnTJlLPknN8t0fPVY="
       SSOToken host name: 123.123.123.123 (Your server's ip address)
       SSOToken Principal name: uid=amAdmin,ou=People,dc=example,dc=com
       Authentication type used: LDAP
       IPAddress of the host: 123.123.123.123 (Your server's ip address)
       
    


    To Create SSO Token and validate from the remote JVM (web server)
    
    * Get the SessionID String (either by decoding cookie or from the session
       debug file) by login into Access Manager 2005Q4 and replace sidstring
       in SSOTokenFromRemoteServlet.java
    
    * Compile SSOTokenFromRemoteServlet.java by including am_sdk.jar
       in your classpath
    
    * Copy am_sdk.jar, /usr/share/lib/mps/jss4.jar, jaas.jar and
       AMConfig.properties, SSOConfig.properties (Note: Include
       jaas.jar in your classpath if you are using JDK version less than
       JDK 1.4)
    
    * Copy libjss4.so to your web server lib directory (You can find
       this under your web server lib directory i.e.
       $PRODUCT_DIR/servers/bin/https/lib
    
    * Restart your web server and access
       http://<localhost:port>/servlet/SSOTokenSampleServlet
    



End of Sample

