| 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
     & Windowsinstallations.	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:
 
 
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.
 
 
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.
 
 
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.
 
 
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.
 
 
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
    
 
Set these environment variables. These environment variables will be
       used the run the make command. You can also set these variables in the
 Makefilewhich can be found in the same directory as samplefiles.
 
       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.
       Go to the directory "<INSTALL_DIR>/SUNWam/samples/sso".
       Rungmake.Go to the the directory JAR_DIR. copy theSSOSample.jarfile to the
 "<INSTALL_DIR>/SUNWam/lib"directory.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).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>
       Restart the server and login to the Access Manager console.
    The user executing SSOTokenSampleServletmust have authorization to
       access that resource.Otherwise the request will be denied. Refer to the
       policy setting instructions in the Administration Guide.
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 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/iwsdirectory and the Access Manager remote client was installed in/opt.
 
Go to the directory "<INSTALL_DIR>/SUNWam/samples/sso".
	Rungmake.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.jarand/opt/SUNWam/lib/xercesImpl.jarto 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/localeand/opt/SUNWam/libdirectories to the web server's classpathAdd (it it's not there) java.protocol.handler.pkgs=com.iplanet.services.commto as an
       argument to be passed into theVMof the web serverRestart Sun Java System Web Server.
     
    NOTE: If the Access Manager is running SSLyou may need to add the
    following line toAMConfig.propertiesfor testing purposes
    (com.iplanet.am.jssproxy.trustAllServerCerts=true). This property tells
    theSSLclient in theSDKto trust all certificates presented
    from the servers. This allows you to testSSLwithout having
    them rootCAfor your test cert installed on the this client. Otherwise,
    you would need to installSSLServer'srootCAcertificate in client's
    trust database and make sure that the following properties inAMConfig.propertiesare 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
     
 
cd /opt/SUNWam/samples/ssoIt 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>
       Restart the web container where the AM SDK is installed.
    Login to Access Manager (on separate web constainer instance) and then invoke the servlet with
       http://amsdk-server.sub.domain/servlet/SSOTokenSampleServletThis servlet validates the session and prints out all relevant
       session information. You may have to reload the URL to see updated
       information.
    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 lineCommand lineSSOassumes your application is not running in a web container, but does have accessto 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
 createSSOTokenmethod.Notifications are are only supported in a web container.
 
    Install the Access Manager Client SDK and perform the following steps:
     
 
Go to the directory "<INSTALL_DIR>/SUNWam/samples/sso".
       Rungmake.Modify "<INSTALL_DIR>/SUNWam/samples/sso/run"script to execute the sample programthat you want to test. For example, to run
 SDKCommandLineSSO.java,replace
 CommandLineSSOwithSDKCommandLineSSOat the last line
 "${JAVA_EXEC} -Xbootclasspath ...SDKCommandLineSSO $@"in the script.
Add /opt/SUNWam/lib/jaas.jarto your classpath if you are using JDK version less than JDK1.4).When the server is running SSLyou will need to add the followingVMargumentin 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 
 cookievalueand pass it in as thetokenvalue.
    Example: 
 
Access servlet
        http://test-server.red.iplanet.com:58080/amserver/SSOTokenSampleServletYou 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
       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
 
 
Set these environment variables. These environment variables will be
       used the run the makecommand. You can also set these variables in theMakefile. ThisMakefileis 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.
       Go to the directory <INSTALL_DIR>\samples\ssoand do
       make
       Go to the the directory JAR_DIR. copy theSSOSample.jarfile to
       the"<INSTALL_DIR>\lib"directory.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>
       Restart the server and login to the Access Manager console.
    The user executing SSOTokenSampleServletmust have authorization to
       access that resource. Otherwise the request will be denied. Refer to the
       policy setting instructions in the Administration Guide.Type in the browser
       <protocol>://<host>:<port>/<deploy-uri>/SSOTokenSampleServletYour sample program should display the output in the browser. Here
       host must be a fully qualified name.
     
    
 To Install the Install theSSOSDK on a remote client for use within a web container:IS2005Q4_sdk.zipand perform the following steps:
 
Copy jss4.dllto a directory in the web server's PathAdd am_sdk.jar,jaas.jar,jss4.jar,jaxp.jar,dom.jarandxercesImpl.jarto the web server's classpath.(Note:
       Includejaas.jarin your classpath if you are using JDK version less
       than JDK 1.4)Add the localeandlibdirectories to the web server's classpathAdd java.protocol.handler.pkgs=com.iplanet.services.commto as an
       argument to be passed into theVMof the web server. 
    The following steps assume Sun Java System Web Server is install in \iwsand theIS2005Q4remote client was installed inC:\sso\IS2005Q4_sdk\ 
 
Copy C:\sso\IS2005Q4_sdk\lib\jss4.dllto/iws/bin/https/libAppend SSOSample.jar,am_sdk.jar,jaas.jar,jss4.jar,jaxp.jar,dom.jar,xercesImpl.jar,localeandlibto the'serverclasspath'attribute of<JAVA>XML tag iserver.xml(Note: Include jaas.jar in your classpath if you are using
       JDK version less than JDK 1.4)Add java.protocol.handler.pkgs=com.iplanet.services.commto<JVMOPTIONS>XML tag inserver.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>
       You may also add the C:\sso\IS2005Q4_sdk\samples\ssodirectory above if
       you wish to run the samplesRestart Sun Java System Web Server.
     
    NOTE: If the Access Manager server is running SSLyou may need to add
    the following line toAMConfig.propertiesfor testing purpose
    (com.iplanet.am.jssproxy.trustAllServerCerts=true). This line tells theSSLclient in the SDK to trust all certificates presented from the
    servers. This allows you to testSSLwithout having the rootCAfor your
    test cert installed on the this client. Otherwise, you would need to
    installSSLServer'srootCAcertificate in client's trust database
    and make sure that the following properties inAMConfig.propertiesare 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
 
cd C:\sso\IS2005Q4_sdk\samples\sso
makeLogin to Access Manager and then invoke the servlet with
        http://server.sub.domain/servlet/SSOTokenSampleServletThis servlet validates the session and prints out all relevant
       session information. You may have to reload the URL to see updated
       information.
    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 commandlineCommand lineSSOassumes 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 thecreateSSOTokenmethod.
    Notifications are are only supported in a web container.
    Install the IS2005Q4_sdk.zipand perform the following steps: 
 
Add c:\sso\IS2005Q4_sdk\libto your PATHAdd am_sdk.jar,jaas.jar,/usr/share/lib/mps/jss4.jar,jaxp.jar,dom.jarandxercesImpl.jarto your classpath. (Note: Includejaas.jarin your classpath if you are using JDK version less than JDK 1.4)Add the localeandlibdirectories to your classpath.When the server is running SSLyou will need to add the followingVMargument when executing your java code.
       java.protocol.handler.pkgs=com.iplanet.services.commSee 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 cookievalueand pass it in as thetokenvalue.Example:
 
 
Access servlet
       "http://test-server.red.iplanet.com:58080/amserver/SSOTokenSampleServlet"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
       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 SSOToken and validate from the remote JVM (web server)
 
Get the SessionIDString (either by decoding cookie or from the session
       debug file) by login into Access Manager 2005Q4 and replacesidstringinSSOTokenFromRemoteServlet.javaCompile SSOTokenFromRemoteServlet.javaby includingam_sdk.jarin your classpathCopy am_sdk.jar,/usr/share/lib/mps/jss4.jar,jaas.jarandAMConfig.properties,SSOConfig.properties(Note: Includejaas.jarin your classpath if you are using JDK version less than
       JDK 1.4)Copy libjss4.soto your web serverlibdirectory (You can find
       this under your web server lib directory i.e.$PRODUCT_DIR/servers/bin/https/libRestart your web server and access
       http://<localhost:port>/servlet/SSOTokenSampleServlet |