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

• SSOToken

• SSOTokenListener

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:

• getProperty() is used to get any information about the session, predefined or otherwise (for example, information set by the application).

• setProperty() can be used by the application to set application-specific information in the session.

• addSSOTokenListener() can be used to set a listener to be invoked when the session state has become invalid.

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.