Sun Java System Access Manager version 6 2005Q1
Sample
 

Main Page

Single Sign On Samples


1. Introduction

This file explains how to compile and run a sample Single Sign on (SSO) application for Solaris & Windows installations.


2. Instructions for Solaris

  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. 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>
           
  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. Open a browser and visit "<protocol>://<host>:<port>/<deploy-uri>/SSOTokenSampleServlet"

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 SUNWamsdk Solaris package and perform the following steps:

  • Add am_sdk.jar, jaas.jar, /usr/share/lib/mps/jss3.jar, jaxp.jar, dom.jar and 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 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 installed in /iws directory and the Access Manager remote client was installed in /sso

  1. Append SSOSample.jar, am_sdk.jar, jaas.jar, /usr/share/lib/mps/jss3.jar, jaxp.jar, dom.jar, xercesImpl.jar, locale and lib to the 'serverclasspath' attribute of <JAVA> XML tag in server.xml. (Note: Include jaas.jar in your classpath only if you are using JDK version less than JDK1.4)
  2. 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:/usr/share/lib/mps/jss3.jar.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>
           
  3. You may also add the /sso/SUNWam/samples/sso directory above if you wish to run the samples.
  4. 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 /sso/SUNWam/samples/sso
  2. gmake
  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 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 SUNWamsdk Solaris package and perform the following steps:

  1. Add /sso/SUNWam/lib/sparc/solaris to your LD_LIBRARY_PATH
  2. Add am_sdk.jar, jaas.jar, /usr/share/lib/mps/jss3.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 JDK1.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)
           


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 IS2005Q1_sdk.zip and perform the following steps:

  • Copy jss3.dll to a directory in the web server's Path
  • Add am_sdk.jar, jaas.jar, jss3.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 IS2005Q1 remote client was installed in C:\sso\IS2005Q1_sdk\

  1. Copy C:\sso\IS2005Q1_sdk\lib\jss3.dll to /iws/bin/https/lib
  2. Append SSOSample.jar, am_sdk.jar, jaas.jar, jss3.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/jss3.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\IS2005Q1_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\IS2005Q1_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 IS2005Q1_sdk.zip and perform the following steps:

  1. Add c:\sso\IS2005Q1_sdk\lib to your PATH
  2. Add am_sdk.jar, jaas.jar, /usr/share/lib/mps/jss3.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 2005Q1 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/jss3.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 libjss3.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