Cams Programmer's Guide

Programming Cams Sessions

This document describes the Cams Session API, which enables you to control the sessions created when users are authenticated and customize their attributes for use by Cams-based components, agents, web pages, etc. Some practical uses of this API include:

Sending an e-mail or pager message to an administrator based on the user/role of an authenticated user
Setting user-specific session attributes queried from a database for use in customized web pages

This API contains three main interfaces that may be of interest to Cams programmers: Session, ManagedSession and ManagedSessionEventHandler.

Overview of the Cams Session API

Each Cams security domain has a session manager service, which creates and manages ManagedSession instances as users are authenticated. During it's lifespan, a ManagedSession may have attributes added, updated, and removed. It may also expire due to inactivity or close when the user logs out. Cams ManagedSessionEventHandlers can be registered with a security domain's session manager service. They are notified whenever a ManagedSession is created, expired, or closed. Figure 1 shows the relationship of high-level Cams components to Cams ManagedSessions and ManagedSessionEventHandlers.

Figure 1 - Relationship of ManagedSession and ManagedSessionEventHandler to security domain components

Cams managed session event handlers are registered within the session-manager-service element of security-domain.xml. When the enclosing security domain is loaded, each session event handler registered with a session manager service is loaded. A session event handler is configured via its initialize method and is given a Config Object, which provides access to:

Configuration parameters as name/value pairs
A ServiceFinder for finding and using Cams services
The Logger for the enclosing security domain

Session event handlers must implement the Cams managed session event handler interface defined by class: com.cafesoft.cams.session.ManagedSessionEventHandler.

Cams Session API Reference

See the Cams Session javadocs for information about the important classes and interfaces in the Cams Session API.

Cams ManagedSession API Classes

This section provides an overview of the interfaces and classes within the Cams Session API.

com.cafesoft.cams.session.ManagedSession
com.cafesoft.cams.session.Session
com.cafesoft.cams.session.SessionStatus

A ManagedSession is an extended Cams session with the additional functionality to close, expire, and get the authenticated subject. It is the primary session object used throughout the Cams server. SessionStatus is a type-safe constant that may have any of the following values:

ACTIVE - The session is currenly active
EXPIRED - The session expired and was closed automatically because it was inactive for too long
CLOSED - A session was closed by a user or management application

com.cafesoft.cams.session.ManagedSessionEvent
com.cafesoft.cams.session.ManagedSessionEventType

A ManagedSessionEvent defines an event generated by a security domain's authentication service when:

a subject successfully authenticates and a new ManagedSession is created
a ManagedSession expires
a ManagedSession is closed (the Subject explicitly logs out)

The type of event is specified by type-safe constant: ManagedSessionEventType which may have any of the following values:

SESSION_CREATED - A session was newly created due to a successful user authentication
SESSION_EXPIRED - A session expired and was closed automatically because it was inactive for too long
SESSION_CLOSED - A session was closed by a user or management application

com.cafesoft.cams.session.ManagedSessionEventHandler

The interface that must be implemented by any class that is to be registered as a Cams session event handler. This interface provides a way for Cams to initialize handler instances and to notify the instance of a ManagedSessionEvent.

com.cafesoft.cams.Config
com.cafesoft.cams.Context

com.cafesoft.core.service.ServiceFinder
com.cafesoft.core.log.Logger

A Config object is supplied to a ManagedSessionEventHandler via an initialize() method and provides access to a Context object, which references the Logger used by the enclosing security domain. Your ManagedSessionEventHandler can use this Logger to report DEBUG, INFO, WARNING, ERROR, and FATAL messages that get logged to the security domain's trace logger. The Context object also provides access to a ServiceFinder that enables access to Cams services (See Programming Cams Services).

Figure 2 shows the relationship of various classes and interfaces to ManagedSessionEventHandlers. In summary: you'll create a class that implements interface ManagedSessionEventHandler. This interface extends ManagedSessionEventListener, which provides the method invoked by a session manager to handle a ManagedSessionEvent. Each ManagedSessionEvent has a ManagedSessionEventType (type-safe constant) corresponding to CREATED, EXPIRED, and CLOSED event types. A ManagedSessionEventHandler is initialized with a Config object by which configuration parameters, a ServiceFinder (for finding and using Cams services) and a Logger (for logging trace messages) can be accessed.

Figure 2 - Cams ManagedSessionEventHandler class relationships

Figure 3 summarizes the relationships of various Cams interfaces and classes to a Cams ManagedSession, which extends interface Session. Each Cams session corresponds to an authenticated user which is represented by a javax.security.auth.Subject. The subject contains one or more java.security.Principals, usually corresponding to usernames, roles, groups, etc. Each session also has a status represented by type-safe constant: SessionStatus.

Figure 3 - Cams ManagedSession class relationships

Cams Session Attributes

In addition to referencing the authenticated Subject, creation time, last touched time, etc, Cams Sessions are also a container for attributes. Session attributes provide a way to associate values that can be accessed by: session event handlers, access control rules, services, agents, and applications. One common use for session attributes is to store user profile information at authentication time, then access the stored values from a web application on a web server protected using a Cams agent.

To help avoid naming conflicts, session attributes are organized into namespaces. You might decide to segregate all user profile information into a namespace called userinfo. You might also use a namespace called webapp1 to store attributes that are specific to a particular web application. By convention, the namepace cams is reserved for use by Cams so avoid inserting attributes there.

Setting/Getting Cams Session Attributes

Example 1 shows how you can set and get Cams Session attributes. The code assumes you've got access to a Session via the Cams Access Control Rule API or a ManagedSessionEventHandler within this API. Attributes are added to two different namespaces: userinfo and webapp1.

...

import com.cafesoft.cams.session.ManagedSession;

...


ManagedSession session = ...;  // Obtained via Cams API-specific method 
                               // (See examples 2-3)

// Add session attributes
session.putAttribute("userinfo", "first-name", "Fred");
session.putAttribute("userinfo", "last-name", "Flintstone");
session.putAttribute("userinfo", "gender", "M");
session.putAttribute("webapp1", "admin-email", "admin@mycompany.com");

// Get specific session attributes
String firstName = session.getAttribute("userinfo", "first-name");
String lastName = session.getAttribute("userinfo", "lastName");
String gender = session.getAttribute("userinfo", "gender");
String adminEmail = session.getAttribute("webapp1", "admin-email");

// If an attribute is not defined, null is returned
String nullValue = session.getAttribute("webapp1", "undefined attribute");

// Print out all attributes
String[] namespace = session.getNamespaces();
for (int i = 0; i < namespace.length; i++)
{
   String[] attrName = session.getAttributeNames(namespace[i]);
   for (int j = 0; j < attrName.length; j++)
   {
      String attrValue = (String)session.getAttribute(namespace[i], attrName[j]);
      System.out.println("Namespace: " + namespace[i] + ", " + 
          attrName[j] + "=" + attrValue);
   }
}

Example 1 - Setting and Getting Session Attributes

Accessing a Cams Session from a ManagedSessionEventHandler

In ManagedSessionEventHandlers, a Cams ManagedSession is accessible from a ManagedSessionEvent as shown in Example 2.

...

import com.cafesoft.cams.session.ManagedSession;
import com.cafesoft.cams.session.ManagedSessionEvent;

...


   public void handleManagedSessionEvent(ManagedSessionEvent event)

   {
      ManagedSession session = event.getManagedSession();

      ...
   }

Example 2 - Accessing a ManagedSession from a ManagedSessionEventHandler

Accessing a Cams Session from an AccessControlRule

In AccessControlRules, a Cams ManagedSession is accessible from an AccessRequest as shown in Example 3. If the value is null, then no session is associated with the request, meaning the user has not authenticated.

...

import com.cafesoft.cams.session.ManagedSession;

import com.cafesoft.cams.access.AccessRequest;
import com.cafesoft.cams.access.AccessResponse;
import com.cafesoft.cams.access.EvaluationException;

...

   /**
    * Evaluate the "Ladies Only" AccessControlRule.
    *
    * @param accessRequest the access request.
    * @param accessResponse the access response.
    * @return true if the authenticated user's is a lady (female) according to
    *   session attribute: namespace=userinfo, gender=F 
    * @exception EvaluationException if the user is not authenticated or some other
    *   error when attempting to evaluate the rule.
    */
   public boolean evaluate(AccessControlRequest accessRequest,
      AccessControlResponse accessResponse) throws EvaluationException
   {
      ManagedSession session = accessRequest.getSession();
      if (session == null)
      {
         // A session is required for this access control rule, so
         // throw an EvaluationException that will force authentication.
         throw new EvaluationException("authentication required",
            AccessControlResponse.RC_ACCESS_DENIED_AUTHENTICATION_REQUIRED);
      }

      // Return true if a session attribute indicates the user is female
      return "F".equalsIgnoreCase(session.getAttribute("userinfo", "gender"));
   }

Example 3 - Accessing a ManagedSession from an AccessControlRule

Example Cams ManagedSessionEventHandler

This section describes how to create your own Cams managed session event handler. The example will use JDBC to lookup a user specific attribute at session creation time.

Register the Session Event Handler

Example 4 shows how to register and configure the example: UserAttributeManagedSessionEventHandler by adding the <session-event-handler> element and attributes to the <session-manager-service> in security-domain.xml.

<!-- Configure the session manager service -->
<session-manager-service
	className="com.cafesoft.security.engine.session.StandardSessionManager">

...

<session-event-handler
    className="examples.session.UserAttributeManagedSessionEventHandler">
    <param-list>
      <param name="jdbcDriver" value="com.cafesoft.core.jdbc.PoolingConnectionDriver"/>
      <param name="url" value="jdbc:cafesoft:pool:usersdb_pool"/>
      <param name="user" value="examples_admin"/>
      <param name="password" value="examples_admin_password"/>
      <param name="sql" value="SELECT BALANCE FROM USERS WHERE USER LIKE ?"/>
      <param name="nameSpace" value="userinfo"/>
      <param name="attributeName" value="balance"/>
    </param-list>
  </session-event-handler>
</session-manager-service>

Example 4 - Register the UserAttributeManagedSessionEventHandler example within a security domain

The parameters for this example are:

jdbcDriver - the fully qualified class name of the JDBC driver to use
url - the JDBC database connection URL
user - the user account to connect to the database
password - the password for the user
sql - the SQL for the prepared statement that will be used to query the attribute value, the login user name will be substituted for the question mark ("?")
nameSpace - the session attribute's namespace. If null or an empty string, then the default namespace: "default:namespace" is used.
attributeName - the session attribute name

NOTE: Example 4 shows use of a JDBC Driver provided by Cams that pools JDBC Connections and can dramatically improve performance and scalability for Session Event Handlers. Cams provides a service that can be used to configure JDBC Connection pooling for use by Session Event Handlers, Login Modules, and any other components that you can plug into Cams. For more information, see section: Using Jdbc Connection Pooling in the Cams Administrator's Guide.

Cams prepends the HTTP request header value with CAMS-HTTP-. In the example the HTTP header request value to be fetched by the application code would be CAMS-HTTP-USERINFO-BALANCE.

NOTE: Some web servers such as Apache and IIS convert dashes to underscores and prepend HTTP_. For example, and ASP.NET, PERL, PHP, or shell programmer could expect to find the value for CAMS-HTTP-USERINFO-BALANCE using the name HTTP_CAMS_HTTP_USERINFO_BALANCE.

The comments found in examples.session.UserAttributeManagedSessionEventHandler explain the work being done.

Another example ManagedSessionEventHandler is: examples.service.RoleLoginNotifier, which sends an e-mail message whenever a user with the specified role authenticates. Example 5 shows the security-domain.xml configuration. This example makes use of the Cams Services API to implement the text notifier service that send the email.

<!-- Configure the session manager service -->
<session-manager-service
	className="com.cafesoft.security.engine.session.StandardSessionManager">

  ...

  <!-- Configure the login notifier event manager -->
  <session-event-handler
    className="examples.service.RoleLoginNotifier">
    <param-list>
      <param name="fromAddress" value="user@mycompany.com"/>
      <param name="msgSubject" value="Security Domain Login"/>
      <param name="roleName" value="myrole"/>
    </param-list>
  </session-event-handler>

</session-manager-service>

...

<!-- Register services accessible within this security domain -->
<service-manager className="com.cafesoft.core.service.StandardServiceManager">

  ...

  <!-- Register a text notifier service -->
  <service id="email-text-notifier-service" enabled="true" debug="false">
    <service-type>examples.service.TextNotifierService</service-type>
    <service-class>examples.service.SmtpTextNotifierService</service-class>
    <param-list>
      <param name="smtp.host" value="mymailhost.mycompany.com"/>
      <param name="smtp.to" value="user@mycompany.com"/>
    </param-list>
  </service>

</service-manager>

Example 5 - Register the RoleLoginNotifier and TextNotifierService example within a security domain

Back | Next | Contents