test

Sun OpenSSO Enterprise 8.0 Developer's Guide

Chapter 3 Using the Session Service API

The OpenSSO Enterprise Session Service maintains information about an authenticated user's session across all web applications in a single sign-on environment. This chapter describes the interfaces used to track session data for purposes of single sign-on and related sample code. It includes the following sections:

For a comprehensive listing of all Java interfaces and their usage, see the Sun OpenSSO Enterprise 8.0 Java API Reference.

OpenSSO Enterprise also includes an API for session management in C applications. For information see Chapter 4, Single Sign-On Data Types and Functions, in Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers.

A Simple Single Sign-On Scenario

In a single sign-on scenario, a user logs in to access a protected resource. Once the user has successfully authenticated to OpenSSO Enterprise, a user session is created and stored in OpenSSO Enterprise memory. The user uses browser cookies or URL query parameters to carry a session identifier. Each time the user requests access to another protected resource, the new application must verify the user's identity. It does not ask the user to present credentials. Instead, the application uses the session identifier and the Session Service interfaces to retrieve the user's session information from OpenSSO Enterprise. If it is determined from the session information that the user has already been authenticated and the session is still valid, the new application allows the user access to its data and operations. If the user is not authenticated, or if the session is no longer valid, the requested application prompts the user to present credentials a second time. Until logging out, this scenario is played out every time the user accesses a protected resource in the single sign-on environment. For more detailed information about user sessions and single sign-on, see Chapter 6, Models of the User Session and Single Sign-On Processes, in Sun OpenSSO Enterprise 8.0 Technical Overview.

Inside a User Session

A user session is, more specifically, a data structure created by the Session Service to store information about a user session. Cookies are used to store a token that uniquely identifies the session data structure. A session data structure contains attributes and properties that define the user's identity and time-dependent behaviors. One example is the maximum time before the session expires.

The values of most of these attributes and properties are set by services other than the Session Service (primarily, the Authentication Service). The Session Service only provides storage for session information and enforces some of the time-dependent behavior. An example of such enforcement is invalidating and destroying sessions which exceed their maximum idle time or maximum session time.

A session data structure may contain the following:

Session Attributes

The session data structure contains the following fixed attributes:

sun.am.universalIdentifier

This universal, unique session identifier is an opaque, global string that programmatically identifies a specific session data structure. With this identifier, a resource is able to retrieve session information.

Type

This is specifies the type of client: USER or APPLICATION.

State

This is the state of the session: VALID, INVALID, DESTROYED or INACTIVE.

maxIdleTime

This is the maximum time in minutes without activity before the session will expire and the user must reauthenticate.

maxSessionTime

This is the maximum time in minutes before the session expires and the user must reauthenticate.

maxCachingTime.

This is the maximum time in minutes before the client contacts Identity Server to refresh cached session information

latestAccessTime

This refers to the last time the user accessed the resource.

creationTime

This is the time at which the session token was set to a valid state.

Protected Properties

The session data structure also contains an extensible set of protected (or core) properties. The following protected properties are set by OpenSSO Enterprise and can only be modified by OpenSSO Enterprise (primarily the Authentication Service).

Organization

This is the DN of the organization to which the user belongs.

Principal

This is the DN of the user.

Principals

This is a list of names to which the user has authenticated. (This property may have more then one value defined as a pipe separated list.)

UserId

This is the user's DN as returned by the module, or in the case of modules other than LDAP or Membership, the user name. (All Principals must map to the same user. The UserId is the user DN to which they map.)

UserToken

This is a user name. (All Principals must map to the same user. The UserToken is the user name to which they map.)

Host

This is the host name or IP address for the client.

authLevel

This is the highest level to which the user has authenticated.

AuthType

This is a pipe separated list of authentication modules to which the user has authenticated (for example, module1|module2|module3).

Service

Applicable for service-based authentication only, this is the service to which the user belongs.

loginURL

This is the client's login URL.

Hostname

This is the host name of the client.

cookieSupport

This attribute contains a value of true if the client browser supports cookies.

authInstant

This is a string that specifies the time at which the authentication took place.

SessionTimedOut

This attribute contains a value of true if the session has timed out.

About the Session Service Interfaces

All OpenSSO Enterprise services (except for the Authentication Service) require a valid session identifier (programmatically referred to as SSOToken) to process an HTTP request. External applications developed using the Session Service interfaces and protected by a policy agent also require an SSOToken to determine access privileges. The SSOToken is an encrypted, unique string that identifies a specific session data structure stored by OpenSSO Enterprise. If the SSOToken is known to a OpenSSO Enterprise service or an external protected resource such as an application, the service or application can access all user information and session data stored in the session data structure it identifies. After successful authentication, the SSOToken is transported using cookies or URL parameters, allowing participation in single sign-on.

The Session Service provides Java interfaces to allow OpenSSO Enterprise services and external applications to participate in the single sign-on functionality. The com.iplanet.sso package contains the tools for creating, destroying, retrieving, validating and managing session data structures. All external applications designed to participate in the single sign-on solution must be developed using this API. In the case of a remote application, the invocation is forwarded to OpenSSO Enterprise by the client libraries using XML messages over HTTP(S).

The com.iplanet.sso package includes the following:

SSOTokenManager

The SSOTokenManager class contains the methods needed to get, validate, destroy and refresh the session identifiers that are programmatically referred to as the SSOToken. To obtain an instance of SSOTokenManager, call the getInstance() method. The SSOTokenManager instance can be used to create an SSOToken object using one of the forms of the createSSOToken() method. The destroyToken() method is called to invalidate and delete a token to end the session. Either the isValidToken() and validateToken() methods can be called to verify whether a token is valid (asserting successful authentication). isValidToken() returns true or false depending on whether the token is valid or invalid, respectively. validateToken() throws an exception only when the token is invalid; nothing happens if the token is valid. The refreshSession() method resets the idle time of the session. The following code sample illustrates how to use SSOTokenManager to validate a user session.

Example 3–1 Code Sample for Validating a User Session


try {

		/* get an instance of the SSOTokenManager */

SSOTokenManager ssoManager = SSOTokenManager.getInstance();

		/* The request here is the HttpServletRequest. Get
		/* SSOToken for session associated with this request. 
		/* If the request doe not have a valid session cookie,
		/* a Session Exception would be thrown.*/

SSOToken ssoToken = ssoManager.createSSOToken(request);

		/* use isValid method to check if token is valid or not.
		/* This method returns true for valid token, false otherwise. */

if (ssoManager.isValidToken(ssoToken)) {

		/* If token is valid, this information may be enough for
		/* some applications to grant access to the requested
		/* resource. A valid user represents a user who is
		/* already authenticated. An application can further
		/* utilize user identity information to apply
		/* personalization logic .*/

} else {

		/* Token is not valid, redirect the user login page. */

}

		/* Alternative: use of validateToken method to check
		/* if token is valid */

try {
ssoManager.validateToken(ssoToken);

		/* handle token is valid */

} catch (SSOException e) {

		/* handle token is invalid */

}

		/*refresh session. idle time should be 0 after refresh. */

ssoManager.refreshSession(ssoToken);

} catch (SSOException e) {

		/* An error has occurred. Do error handling here. */

}

SSOToken

The SSOToken interface represents the session identifier returned from the createSSOToken() method, and is used to retrieve session data such as the authenticated principal name, authentication method, and other session information (for example, session idle time and maximum session time). The SSOToken interface has methods to get predefined session information such as:

Caution – Caution –

The methods getTimeLeft() and getIdleTime() return values in seconds while the methods getMaxSessionTime() and getMaxIdleTime() return values in minutes.

The following code sample illustrates how to use SSOToken to print session properties.

Example 3–2 Using SSOToken to Print Session Properties


		/* get http request output stream for output */

PrintWriter out = response.getWriter();

		/* get the sso token from http request */

SSOTokenManager ssoManager = SSOTokenManager.getInstance();
SSOToken ssoToken = ssoManager.createSSOToken(request);

		/* get the sso token ID from the sso token */

SSOTokenID ssoTokenID = ssoToken.getTokenID();
out.println("The SSO Token ID is "+ssoTokenID.toString());

		/* use validate method to check if the token is valid */

try {
ssoManager.validateToken(ssoToken);
out.println("The SSO Token validated.");

} catch (SSOException e) {
out.println("The SSO Token failed to validate.");
}

		/* use isValid method to check if the token is valid */

if (!ssoManager.isValidToken(token)) {
out.println("The SSO Token is not valid.");
} else {

		/* get some values from the SSO Token */

java.security.Principal principal = ssoToken.getPrincipal();
out.println("Principal name is "+principal.getName());

String authType = ssoToken.getAuthType();
out.println("Authentication type is "+authType);

int authLevel = ssoToken.getAuthLevel();
out.println("Authentication level is "+authLevel);

long idleTime = ssoToken.getIdleTime();
out.println("Idle time is "+idleTime);

long maxIdleTime = ssoToken.getMaxIdleTime();
out.println("Max idle time is "+maxIdleTime);

long maxTime = token.getMaxSessionTime();
out.println("Max session time is "+maxTime);

String host = ssoToken.getHostName();
out.println("Host name is "+host);

		/* host name is a predefined information of the session,
		/* and can also be obtained the following way */

String hostProperty = ssoToken.getProperty("HOST");
out.println("Host property is "+hostProperty);

		/* set application specific information in session */

String appPropertyName = "app1propA";
String appPropertyValue = "appValue";
ssoToken.setProperty(appPropertyName, appPropertyValue);

		/* now get the app specific information back */

String appValue = ssoToken.getProperty(appPropertyName);
if (appValue.equals(appPropertyValue)) {
out.println("Property "+appPropertyName+", 
 value "+appPropertyValue+" verified to be set.");
} else {
out.println("ALERT: Setting property "+appPropertyName+" failed!");

}

}

SSOTokenListener

The SSOTokenListener class allows the application to be notified when a SSOToken has become invalid — for example, when a session has timed out.