Sun Java System Access Manager version 7 2005Q4
Sample
 

Main Page

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