Sun Java System Access Manager 7.1 Developer's Guide

Using the SSO Code Samples

Access Manager provides the following code samples that demonstrate how you can use the Single Sign-On APIs. These samples are in the form of either standalone Java application or Java servlets.

SDKCommandLineSSO.java

Standalone Java program.

Creates a new SSO token given a valid SSO token id.

Input: Token id.

Output: Basic SSO token information.

CommandLineSSO.java

Standalone Java program.

Demonstrates the usage of retrieving the user profile given the correct user credentials.

Input: Organization name (in DN format).

Output: User profile attributes.

SSOTokenSample.java

Standalone Java program.

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.

Input: Token id.

Output: Basic SSO token information and session properties.

SDKSampleServlet.java

Java Servlet.

Demonstrates the usage of retrieving the user profile given the valid cookie set in the browser.

Input: None, but require AM session cookie set in the browser.

Output: SSO token information and user profile attributes.

SSOTokenSampleServlet.java  SampleTokenListener.java

Java Servlet.

Given the valid cookie sent in the browser, these serve as the basis for using the SSO API. Demonstrates use of the of Session Notification Service as well as getting and setting session properties.

Input: None. Requires Access Manager session cookie set in the browser.

Output: Basic SSO token information and session properties.

Running SSO Code Samples on Solaris

On the Solaris platform, you can run the sample programs in one of the following ways:

ProcedureTo Run a Sample Program from the Access Manager Server

  1. Set the environment variables.

    The following environment variables are used to run the make command. You can also set these variables in the Makefile which is in the same directory as the sample files.

    BASE

    Specify the directory where the Access Manager Server is installed.

    CLASSPATH

    Specify the directory where all the .JAR files are installed. Example: AccessManager-base/SUNWam/lib

    JAVA_HOME

    Specify the JDK version your are using. The version must be JDK 1.3.1 or higher.

    BASE_CLASS_DIR

    Specify the directory where you will keep the sample compiled classes.

    JAR_DIR

    Specify the directory where the .JAR of the sample classes will be created. The default is the current directory.

  2. In the directory AccessManager-base/SUNWam/samples/sso, run the gmake command.

  3. From the directory JAR_DIR, copy the file SSOSample.jar to the directory AccessManager-base/SUNWam/lib.

  4. Update the web container classpath.

    1. Create a web server admin password file.


      echo "wadm_password=<WS_ADMINPASSWD>" > /tmp/ws70adminpasswd
    2. Use wadm get-jvm-prop to retrieve the current classpath for the Web Server instance.


      ORIGCLASSPATH=`$WADM get-jvm-prop --user=$WS_ADMIN 
      --password-file=/tmp/ws70adminpasswd--host=$WS_HOST --port=$WS_ADMINPORT 
      --config=$WS_CONFIG class-path-suffix`
    3. Use wadm set-jvm-prop to add the SSOSample.jar to the Web Server instance's classpath.


      $WADM set-jvm-prop --user=$WS_ADMIN --password-file=/tmp/ws70adminpasswd 
      --host=$WS_HOST --port=$WS_ADMINPORT --config=$WS_CONFIG class-path-suffix=
      "$ORIGCLASSPATH:AccessManager-base/SUNWam/lib/SSOSample.jar"
  5. Register the Sample servlet.

    1. In the file WebContainer-base/https-host.domain/web-app/SERVICES_DEPLOY_URI/WEB-INF/web.xml, insert the following lines immediately after the last </servlet> tag:

      <servlet>
      		 <servlet-name>SSOTokenSampleServlet</servlet-name>
             <description>SSOTokenSampleServlet</description>
             <servlet-class>SSOTokenSampleServlet</servlet-class>
             </servlet>       
             
      
    2. Insert the following lines immediately after the last </servlet-mapping> tag.

      <servlet-mapping>
             <servlet-name>SSOTokenSampleServlet</servlet-name>
             <url-pattern>/SSOTokenSampleServlet</url-pattern>
             </servlet-mapping>
      
  6. Restart the Access Manager server.

  7. Log in to the Access Manager console.

    To execute SSOTokenSampleServlet, you must be authorized to access that resource. If you do not have authorization, the request will be denied. See the instructions for setting policy in the Administration Guide.

  8. Use a browser to access the following URL:

    protocol://host:port/SERVICES-DEPLOY-URI/SSOTokenSampleServlet

    The default value of SERVICES-DEPLOY-URI is amserver.

    The host name must be a fully qualified name. Your sample program should display the output in the browser.

ProcedureTo Run a Sample Program on a Remote Client

Before You Begin

Install the Access Manager Client APIs in a web container and perform the following steps. In the following example, Sun Java System Web Server is installed in a directory named iws, and the Access Manager client APIs are installed in a directory named opt. For information on installing the Client APIs, see Chapter 1, Using the Client SDK.

  1. In the directory AccessManager-base/SUNWam/samples/sso, run the gmake command.

  2. Be sure that the following are included in the Web Server classpath in the server.xml file:

    • /opt/SUNWam/samples/sso/SSOSample.jar

    • /opt/SUNWam/lib/am_sdk.jar

    • /usr/share/lib/mps/secv1/jss4.jar

    • /opt/SUNWam/lib/jaxp.jar

    • /opt/SUNWam/lib/dom.jar

    • /opt/SUNWam/lib/xercesImpl.jar

    • /opt/SUNWam/lib/jaas.jar (Add this only if you are using a JDK version lower than JDK1.4)

    • /opt/SUNWam/localeand /opt/SUNWam/lib directories

  3. Include java.protocol.handler.pkgs=com.iplanet.services.comm as an argument to be passed into the Web Server virtual machine (VM).


    $WADM create-jvm-options --user=$WS_ADMIN --password-file=/tmp/ws70adminpasswd
    --host=$WS_HOST --port=$WS_ADMINPORT --config=$WS_CONFIG -- 
    -Djava.protocol.handler.pkgs=com.iplanet.services.comm
  4. Restart Sun Java System Web Server.

    If the Access Manager server is running with the Secure Socket Layer (SSL) protocol enabled, you may need to add the following line to the AMConfig.properties file for testing purposes:

    com.iplanet.am.jssproxy.trustAllServerCerts=true

    This property tells the SSL client in the Client APIs to trust all certificates presented by the servers. Adding this property enables you test the SSL connection without having the root CA for your test certificate installed on the this client. Without this property configured, you must install the SSL server rootCA certificate in client trust database, and then make sure that the following properties in AMConfig.properties are set to the same values:

    • com.iplanet.am.admin.cli.certdb.dir

    • com.iplanet.am.admin.cli.certdb.prefix

    • com.iplanet.am.admin.cli.certdb.passfile

ProcedureTo Run the Sample Code

  1. In the /opt/SUNWam/samples/sso directory, run the gmake command.

    This compiles the samples and creates the necessary JAR files.

  2. Register the sample servlet.

    1. In the file WebServer-base/https-hostName.domainName.com/is-web-apps/services/WEB-INF/web.xml,insert the following lines immediately after the last </servlet> tag.

             
             
      <servlet>
             <servlet-name>SSOTokenSampleServlet</servlet-name>
             <description>SSOTokenSampleServlet</description>
             <servlet-class>SSOTokenSampleServlet</servlet-class>
             </servlet>
      
    2. Insert the following lines immediately 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 Access Manager Client APIs are installed.

  4. Log in to the Access Manager server.

  5. To Invoke the servlet, use a browser to go to the following URL:

    http://amsdk-server.sub.domain/servlet/SSOTokenSampleServlet

    The SSOTokenSampleServlet servlet validates the session and prints out all relevant session information. You may have to reload the URL (Shift + Reload Button) to see updated information.

  6. Log out of the Access Manager server.

    Because no log out link exists in the sample servlet, you must use a browser to access the Access Manager server log out URL. Example: https://hostName.domainName.com/amserver/UI/Logout

  7. To verify that the client SSOtoken is no longer valid, invoke the servlet a second time.

    Use a browser to go to the following URL:

    http://amsdk-server.sub.domain/servlet/SSOTokenSampleServlet

    This time, a session exception occurs. Reload the URL to see the updated information.

ProcedureTo Run a Sample Program on the Remote Client Command Line

Before You Begin

You must install the Access Manager Client APIs before you can run a sample program on the remote client command line. For more information on using the Client APIs, see Chapter 1, Using the Client SDK.

When you run a single sign-on (SSO) program from the command line, your application is not running in a web container, but your application must have access to the cookies from the web container HTTP requests. Your application must extract the Access Manager cookie from the request, and then pass the string value of the cookie into the createSSOToken method. Because notifications are only supported in a web container, and because your application is not running in a web container, notifications are not supported in this sample.

  1. In the directory AccessManager-base/SUNWam/samples/sso, run the gmake command.

  2. Modify the script AccessManager-base/SUNWam/samples/sso/run to specify the sample program that you want to test.

    For example, to run SDKCommandLineSSO.java, in the last line in the script, replace CommandLineSSO with SDKCommandLineSSO. The result looks like this:

    ${JAVA_EXEC} -Xbootclasspath ...SDKCommandLineSSO $@

  3. If you are using a JDK version lower than JDK1.4, add the following to the classpath:

    /opt/SUNWam/lib/jaas.jar

  4. If SSL is enabled, in the script AccessManager-base/SUNWam/samples/sso/run , add the following VM argument when executing your Java code:

    java.protocol.handler.pkgs=com.iplanet.services.comm

ProcedureTo Test the Command Line

To test the command line you can run the servlet test above, cut and paste the cookie value and pass it in as the token value.

  1. Use a browser to access the following URL:

    http://test-server.sun.com:80/amserver/SSOTokenSampleServlet

    The following output is displayed:

    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
    
  2. In the AccessManager-base/SUNWam/samples/sso directory, execute the run command:

    run AQIC5wM2LY4Sfcwbdp3gWuB38NA26klnTJlLPknN8t0fPVY=

    The following result is displayed:

    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)