Skip to ContentSun and Oracle Channel Sun How to Buy Log In

Sun Java System Access Manager 7 2005Q4 Developer's Guide

Contidos dentro

Sun Java System Access Manager 7 2005Q4

Localizar Mais Documentação

Destaques de Recursos de Suporte

Fazer download desta apostila em PDF (1251 KB)

Chapter 3 Using Session Service APIs

The Session Service component of the Sun Java^TM System Access Manager 7 2005Q4 enables single sign-on (SSO) functionality. In a single sign-on session, a user authenticates or logs in to a protected resource once. Until the user logs out, the user can access a number of other protected resources without having to present credentials again. For detailed information about how the Session Service and SSO work, see Chapter 2, User Session Management and Single Sign-On, in Sun Java System Access Manager 7 2005Q4 Technical Overview.

This chapter describes the Session Service Java APIs, and related sample code that comes with Access Manager. Topics included in this chapter are:

For information about using the Session Service C APIs, see About the C Library for Single Sign-On

About the Single Sign-On Java APIs

Once a user has successfully authenticated to Access Manager, the user object uses browser cookies or URL query parameters to carry a Session ID from one application to the next. Each time the user requests access to a protected application, the new application must verify the user's identity. For example, a user successfully authenticates to the application at http://orgA.company.com/Store, and then later tries to access http://orgA.company.com/UpdateInfo, a service that is SSO-enabled. The UpdateInfo application does not ask for the user to present credentials. Instead, the application uses the Session APIs and the user session to determine if the user is already authenticated. If the Session methods determine that the user has already been authenticated and that the session is still valid, then the UpdateInfo application allows the user access to its data and operations. If the user is not already authenticated, or if the session is no longer valid, then the UpdateInfo application prompts the user to present credentials a second time. The SSO APIs can also be used to create or destroy a SSOToken, or to listen for SSOToken events.

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:

To Run a Sample Program from the Access Manager Server

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.

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

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

Add AccessManager-base/SUNWam/lib/SSOSample.jar to web container classpath.

Example: WebContainer-base/https-machine.domain.name/config/server.xml

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>

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>

Restart the Access Manager server.

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.

Use a browser to access the following URL:

protocol://host:port/ deploy-uri/SSOTokenSampleServlet

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

To 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. The Sun Java System Web Server must be installed in a directory named iws, and the Access Manager client APIs must be installed in a directory named opt. For information on installing the Client APIs, see Chapter 1, Using the Client SDK.

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

Be sure that the following are included in the Web Server class path 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)
- All /opt/SUNWam/locale and /opt/SUNWam/lib directories

Be sure that java.protocol.handler.pkgs=com.iplanet.services.comm is included as an argument to be passed into the Web Server virtual machine (VM).

In the server.xml file, the following JVM option should be specified:

-Djava.protocol.handler.pkgs=com.iplanet.services.comm

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

To Run the Sample Code

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

This compiles the samples and creates the necessary JAR files.

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>

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>

Restart the web container where the Access Manager Client APIs are installed.

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.

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

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.

To 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.

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

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 $@

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

/opt/SUNWam/lib/jaas.jar

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

To 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.

Use a browser to access the following URL:

http://test-server.red.iplanet.com:58080/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

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)

Developing Non-Web Based Applications

Access Manager provides the SSO APIs primarily for web-based applications although the APIs can be extended to any non-web-based applications with limitations. When developing non-web-based applications, you can use the SSO APIs in one of two ways:

The application must obtain the Access Manager cookie value and pass it into the SSO client methods to get to the session token. The method used for this process is application-specific.
You can use command-line applications such as amadmin. In this case, session tokens can be created to access the Directory Server directly. There is no session created, making the Access Manager access valid only within that process or VM.