Security Domain Configuration

The power of the Cams server is unleashed through high-level services that handle user and Cams agent requests. These services are flexibly configured in each security domain's XML-formatted security-domain.xml file. Table 1 summarizes each security domain service.

Table 1 - Cams services

With a few exceptions, most of the default values supplied with Cams in security-domain.xml will work for you. This document will help you understand how to configure security-domain.xml. The most common configuration activities that will interest you within security-domain.xml include:

• Configuring security domain-wide variables
• Configuring a security domain's trace logger
• Configuring transaction loggers for each security domain service
• Configuring custom services managed by a security domain's service manager

Cams Variables

The following global variables are provided by the Cams server and are always available in every security domain:

• cams.home - The fully qualified path to the Cams server installation directory (set based on an environment variable defined within "runcams.bat" or "runcams.sh"). This value is inherited from the Cams server environment and cannot be modified within a security domain.
• cams.server.name - The name assigned to the Cams server installation within configuration file: ${cams.home}/conf/cams.conf. This value is used primarily within the system security domain, which control access to services used by Cams agents and cannot be modified.
• cams.server.port - The TCP/IP port number on which the Cams server listens for connection by agents as configured in ${cams.home}/conf/cams.conf. This value is used primarily within the system security domain, which control access to services used by Cams agents and cannot be modified.
• cams.security-domain.name - The security domain-specific name (set based on the <name> element of a <security-domain> registration), which is inherited from the security domain registry and cannot be modified.
• cams.security-domain.home - The security domain-specific home directory (set based on the <home> element of a <security-domain> registration), which is inherited from the security domain registry and cannot be modified.

Security domains can also define their own local variables, which are inherited by all XML configuration files within the security domain. One such variable is defined within the security-domain.xml files shipped with Cams as shown in Example 1.

<security-domain>
  ...
	<var-list>
		<var name="logPrefix" 
			value="${cams.logs.base.dir}/${cams.security-domain.name}"/>
	</var-list>
  ...
</security-domain>

The logPrefix variable is used to centralize the location of Cams log files while giving them security domain-specific names. This variable is substituted throughout the remainder of security-domain.xml, where various log files are configured.

Cams Logger Types

Cams has two basic types of loggers: trace loggers and transaction loggers.

A trace logger writes information about the runtime state of Cams services and includes five different levels of messages: DEBUG, INFO, WARNING, ERROR, and FATAL which are summarized in Table 2. It enables you to follow (trace) requests made to a Cams server through the services that handle it. In the case of serious errors, it will log a stack trace, which shows the software context of the error. This information can be important to debugging problems, especially for Cafésoft support representatives. All software components hosted within a security domain log to the same trace logger. The Cams server also has it's own trace logger, which contains information from services that are higher-level than Cams security domains. See Configuring Cams Server for more details on the server-level transaction logger.

Transaction loggers are used by services hosted within a security domain to record transaction-specific requests and responses. For example, a security domain's authentication service records authentication requests and responses, which is quite different from the information logged by an access control service. The format of each transaction log type is detailed within it's corresponding service section below.

Table 2 - A summary of Cams message levels

Configuring the Trace Logger

Each Cams security domain configures it's own centralized trace logger, which logs information about the startup, shutdown, warnings, and errors of it's services. If a Cams security domain is misconfigured, fails to load, detects a runtime error, or experiences any other anomaly, a message will be written by this logger. Example 2 shows the XML tag that configures a security domain's trace logger.

<security-domain>
  ...
	<logger 
		className="com.cafesoft.cams.log.CamsTraceLogger"
		filePath="${logPrefix}-trace.log"/>
  ...
</security-domain>

Table 3 shows properties that can be used to customize a trace logger's behaviour.

Table 3 - Properties for configuring a Cams trace logger

Configuring the Authentication Service

The Authentication Service is responsible for validating the identity of a user who accesses protected resources within the security domain.

Login Config Factory

Loads and initializes the security domain's login configuration.

Authentication Pipeline

The authentication pipeline processes authentication requests issued locally or remotely by a Cams agent. This pipeline implements a chain of responsibility pattern that provides strong, configureable control over who can issue authentication requests, and how the response to authentication requests is created.

Authentication Valve

The authentication valve represents a single node within an authentication pipeline. The valve receives an authentication request and can handle the authentication completely, modify or add to the authentication request, or pass the authentication request to the next authentication valve in the chain.

Authentication Log

The Cams authentication log file contains information about successful and unsuccessful authentication requests within a security domain. Example 3 shows how an authentication valve is configured for logging authentication transactions.

<auth-valve
   className="com.cafesoft.security.engine.auth.valves.LogAuthRequestValve">
   <param-list>
      <param name="logPath" value="${logPrefix}-authentication.log"/>
      <param name="maxSize" value="10MB"/>
      <param name="logOnAuthFailure" value="http=username"/>
   </param-list>
   ...
</auth-valve>

Table 4 shows the configuration parameters that can be used to customize this logger.

Table 4 - Properties for configuring a Cams authentication transaction logger

The authentication transaction log is a comma-delimited text file. Each line corresponds to an authentication request/response pair. Table 5 shows the fields (left to right) defined within this file. If an optional field does not apply, it's value is written as "-" (a dash character).

Table 5 - The Cams authentication transaction log fields

Configuring the Access Control Service

The access control service defines the Java classes that control access to the resources protected by a security domain.

Access Control Policy Factory

The access control policy factory specifies the Java class that creates the access control policy that declares the resources protected within a security domain along with the rules for accessing them. Loads and initializes the access control policy. The factory will usually be specific to the persistence format for the configured access control policy. For example, the access control policy might be stored in an XML file, a relational database, an LDAP server, or some other data storage facility.

Access Request Pipeline

The access control pipeline specifies the Java class that processes access requests issued locally or remotely by a Cams agent. This pipeline is composed of a sequence of access control valves, which handle the request using the chain of responsibility design pattern. This enables each access control valve to handle the request altogether or modulate the request for processing by a subsequent valve.

Access Control Value

The access control valve represents a single node within an access control pipeline for handling access requests. The valve receives an access request and can handle the request completely, modify or add to it, or pass the request to the next valve in the chain.

Access Control Log

The Cams access control log file contains information about access control requests made by remote agents on behalf a client wishing to access resources protected by a security domain. Example 4 shows how an access control valve is configured for logging access control transactions.

<access-control-valve
   className="com.cafesoft.security.engine.access.valves.LogAccessControlRequestValve">
   <param-list>
      <param> name="logPath" value="${logPrefix}-access-control.log"/>
   </param-list>
   ...
</access-control-valve>

Table 6 shows the configuration parameters that can be used to customize this logger. Additional name=value pairs can be appended to the value of the params attribute (like this: params="logPath=${cams.home}/logs/system-authentication.log,append=true").

Table 6 - Properties for configuring the Cams access control transaction logger

The access control transaction log is a comma-delimited text file. Each line corresponds to an access control request/response pair. Table 7 shows the fields (left to right) defined within this file. If an optional field does not apply, it's value is written as "-" (a dash character).

Table 7 - The Cams access control transaction log fields

Configuring the Session Manager Service

The session manager service manages authenticated user sessions. A session is created on successful user authentication, may be closed explicitly by authorized Cams agents, and expires if inactive for a configurable period. The session manager transaction log records session creation, update, and closure events. The session manager also supports registration of application-specific session event handlers, that can be use to customize the contents of sessions or trigger business processes based on session events.

Example 5 shows the default configuration of the the Cams session manager service.

<session-manager-service
    className="com.cafesoft.security.engine.session.StandardSessionManager">
    <param-list>
        <param name="maxActiveSessions" value="-1"/>
        <param name="inactiveSessionTimeout" value="30"/>
        <param name="sessionCleanupInterval" value="1"/>
        <param name="sessionIdIPAddrValidationMask" value="255.255.255.255"/>
        <param name="sessionIdAlgorithm" value="SHA"/>
        <param name="sessionIdKey" value="secret-key"/>
    </param-list>
    ...
</session-manager-service>

Table 8 shows the configuration parameters that can be used to configure the session manager service.

Table 8 - Properties for configuring the Cams access control transaction logger

Session Event Handler

Registers a session event handler with the session manager to handle session events.

Session Manager Log

The Cams session manager log file contains information about the sessions created, closed, and expired. (A session is associated with an authenticated subject within a Cams security domain). Example 6 shows the standard Cams session event handler registered to log session events.

<session-event-handler
   className="com.cafesoft.security.engine.session.SessionManagerEventLogger">
   <param-list>
      <param name="logPath" value="${logPrefix}-session-manager.log"/>
   </param-list>
   ...
</session-event-handler>

Table 9 shows the configuration parameters that can be used to customize this logger.

Table 9 - Properties for defining a Cams session manager transaction logger

Table 10 shows the fields defined within this file.

Table 10 - The Cams session manager log fields

Configuring the Session Access Service

The Cams session access service enables session information to be queried by qualified Cams agents.

Session Access Pipeline

The session access pipeline processes session access requests by a Cams agent. This pipeline is composed of a sequence of session access valves, which handle the request using the chain of responsibility design pattern. This enables each session access valve to handle the request altogether or modulate the request for processing by a subsequent valve.

Session Access Valve

The session access valve represents a single node within a session access pipeline for handling access requests. The valve receives a session access request and can handle the request completely, modify or add to it, or pass the request to the next valve in the chain.

Session Access Log

The Cams session access log file contains information about requests for remote access to an authenticated users session. Example 7 shows how a session-access-valve is configured for logging session access transactions.

<session-access-value
   className="com.cafesoft.security.engine.session.access.valves.LogSessionAccessRequestValve">
   <param-list>
      <param> name="logPath" value="${logPrefix}-session-access.log"/>
   </param-list>
   ...
</session-access-valve>

Table 11 shows the configuration parameters that can be used to customize this logger.

Table 11 - Properties for configuring the session access transaction logger

Table 12 shows the fields defined within this file.

Table 12 - The Cams session access log fields

Configuring the Session Control Service

The Cams session control service enables sessions to be updated, closed, expired, etc. by qualified Cams agents.

Session Control Pipeline

The session control pipeline processes session control requests by a Cams agent. Existing sessions can be updated, closed, or expired. This pipeline is composed of a sequence of session control valves, which handle requests using the chain of responsibility design pattern. This enables each session control valve to handle the request altogether, modify the request for processing by a subsequent valve, or ignore it completely.

Session Control Valve

Represents a single node within a session control pipeline for handling session control requests. The valve receives a session control request and can handle the request completely, modify or add to it, or pass the request to the next valve in the chain.

Session Control Log

The Cams session control log file contains information about requests to update, close or expire sessions managed by the security domain's session manager service. A common use for these transactions is to logout an authenticated user by closing the associated session. Example 8 shows how a session-control-valve is configured for logging session-control transactions.

<session-control-value
   className="com.cafesoft.security.engine.session.access.valves.LogSessionControlRequestValve">
   <param-list>
      <param> name="logPath" value="${logPrefix}-session-control.log"/>
   </param-list>
   ...
</session-control-valve>

Table 13 shows the configuration parameters that can be used to customize this logger.

Table 13 - Properties for configuring the Cams session control transaction logger

Table 14 shows the fields defined within this file.

Table 14 - The Cams session control log fields

Configuring Service Manager Services

Cams includes predefined services that you configure for use with a security domain. Programmers can also use the Cams Services API to create new services for use by other custom components, like session event handlers, access control rules, etc. This section provides information on how to configure the standard services that ship with Cams and those that might be created by your development staff. See the Cams Programmer's Guide for more details on creating custom Cams services.

By default, the following services are available to each Cams security domain:

• LDAP Connection Pool Service - Provides connection pooling for the LDAP login module (required to use the LDAP login module)
• Cams XML User Repository Service - Loads and manages the Cams XML user repository file (required to use the XML login module)

You can have any number of services, each nested within the security-domain.xml <service-manager> tag, which has has three attributes:

className="com.cafesoft.core.service.StandardServiceManager"
params=""
debug="false"

You should not need to change the Java class value. However, if you are having difficulty configuring the service, you might set the debug value to true to provide for more verbose log output. There are no parameters.

Services

The <service> tag starts the registration of a Cams service within the scope of the enclosing security domain. It has the following atributes:

• id - The unique textual identifier or name by which this service will be referenced.
• enabled - A flag to specify if a service is enabled
• debug - If set to true, turns debug on for this service

In addition, a service has three required elements:

• service-type - Declares the type of service being registered. This value is the fully qualified name of the Java interface class implemented by the service. (See examples 7 and 8 to see how this attribute is used)
• service-class - Declares the Java class that implements the Cams service. This value is the fully qualified Java class name which implements the service type)
• param-list - A container for a list of service-specific configuration parameters

For example, suppose a developer at your site has created a custom Cams service called EmailNotifier that can send a short textual messages to an e-mail address. Perhaps the service will be used by a session event handler to notify administrators whenever somebody with the admin role successfully authenticates. The same service might be used to notify a customer at logout time of their account status.

Suppose the programmer created the Cams service by writing two classes:

1. com.myco.message.TextNotifier (a Java interface that extends com.cafesoft.core.service.Service)
2. com.myco.message.EmailTextNotifier (a Java class that implements interface com.myco.message.TextNotifier and uses SMTP to send a brief text message to an e-mail address)

Example 9 shows how you might register and configure this service for use by other custom components (or other services) within a security domain. This service can be looked up by it's identifier: "email-text-notifier-service" or by it's type: com.myco.message.TextNotifier.

<service id="email-text-notifier-service" enabled="true">
	<service-type>com.myco.message.TextNotifier</service-type>
	<service-class>com.myco.message.EmailTextNotifier</service-class>
	<param-list>
		<param name="smtp.host" value="mail.myco.com">
		<param name="smtp.port" value="25">
		<param name="smtp.from" value="cams@myco.com">
  </param-list>
</service>

If need arises for message to be sent to a pager, Java class: com.myco.message.PagerTextNotifier could be written and the Cams service registration shown in Example 10 could be added to make both e-mail and pager text notification available to components.

<service id="pager-text-notifier-service" enabled="true">
	<service-type>com.myco.message.TextNotifier</service-type>
	<service-class>com.myco.message.PagerTextNotifier</service-class>
	<param-list>
    <param name="phone.from" value="800-555-9191">
  </param-list>
</service>

The next sections describes the required configuration values for each standard service supplied with Cams.

JDBC Connection Pool Service

The overhead of opening and closing database connections can be quite high. In production or high-volume environments, you can dramatically improve performance by using pooling to share database connections. When a connection is needed, it is borrowed from the pool. When done with the connection, it is returned to the pool for reuse later.

Cams provides a JDBC driver that implements connection pooling. After configuring a connection pool using a service provided by Cams, login modules (and other components that you can plug into Cams) can then obtain pooled connections from the Cams JDBC driver. The pooling JDBC driver does the work of expanding and shrinking the pool of connections within the parameters you configure. It also verifies a connection is still open before returning it. In addition, it also destroys broken connections. Example 11 shows the values you'll need to configure for your site.

<service-manager className="com.cafesoft.core.service.StandardServiceManager">
 ...
 <!-- Register a Jdbc ConnectionPool with the server -->
 <service id="myusersdb-connection-pool" enabled="true">
 <service-type>com.cafesoft.cams.service.JdbcConnectionPoolService</service-type>
 <service-class>com.cafesoft.security.engine.service.JdbcConnectionPoolServiceImpl</service-class>
  <param-list>
   <param name="debug" value="false"/>
   <param name="poolName" value="example-jdbc-pool"/>
   <param name="driver" value="org.hsqldb.jdbcDriver"/>
   <param name="url" value="jdbc:hsqldb:/tmp/example_db"/>
   <param name="user" value="sa"/>
   <param name="password" value=""/>
   <param name="poolUser" value="pool-username"/>
   <param name="poolPassword" value="pool-password"/>
   <param name="initialCapacity" value="1"/>
   <param name="maximumCapacity" value="5"/>
   <param name="minimumCapacity" value="1"/>
   <param name="poolIncrement" value="1"/>
   <param name="allowShrink" value="false"/>
   <param name="shrinkPeriod" value="10"/>
   <param name="refreshPeriod" value="15"/></param-list>
 </service>
 ...
</service-manager>

The <service> tag parameter values are:

1. id - The identity of this service for this security domain. WARNING: The id must match the corresponding serviceId value in the JDBC client or login module configuration file.
2. enable - Set to true if this service is enabled, false if it is not.

The values <service-type> and <service-class> should not change unless you have created a custom LDAP service.

The <param-list> parameters are:

1. poolName - the name of the connection pool. The JDBC URL configured with a client such as the JDBC login module will contain this value.
2. driver - JDBC driver class used to connect with your SQL database. The one shown (org.hsqldb.jdbcDriver) is for the Hypersonic SQL database. If you're using DB2, MySql, Oracle, MSSQL or some other database, substitute this parameter with the appropriate JDBC Driver class.
3. url - the JDBC URL appropriate the driver configured in step 5.
4. user and password - credentials authorized to create connections to your SQL database.
5. initialCapacity - the number of connections created for the pool when this service is started.
6. maximumCapacity - the maximum number of simultaneous connections that can be managed by the pool.
7. minimumCapacity - the minimum number of connections that should be managed by the pool.
8. poolIncrement - the number of connections the pool will be expanded (up to maxCapacity) if all connections are in use.
9. allowShrink- boolean value that enables to the pool to shrink back to the number of in-use connections or minimumCapacity, which ever is greatest.
10. shrinkPeriod - the number of minutes between pool shrink attempts.
11. refreshPeriod - the number of minutes between attempts to verify that connections are still open.
12. poolUser and poolPassword are the credentials that must be provided by a JDBC client to the Cams pooling JDBC driver to get a connection.

Cams XML User Repository Service

The Cams XML user repository service is intended for use with the XML login module. This service loads a Cams user repository file into memory, and provides methods to lookup user passwords and roles. The service also detects if the Cams user repository file is changed, and reloads if necessary. Example 13 shows the configuration values. Except for the repositoryFilePath, the default values should not change for your site.

<Service id="cams-user-repository" enabled="true">
 <service-type>com.cafesoft.cams.service.UserRepositoryService</service-type>
 <service-class>com.cafesoft.security.engine.service.UserRepositoryServiceImpl</service-class>
 <param-list>
  <param name="repositoryFilePath" value="${cams.home}/conf/domains/system/cams-users.xml"/>
  <param name="repositoryFactoryClass" 
   value="com.cafesoft.security.engine.auth.login.userrepository.XmlUserRepositoryFactory"/>
  <param name="handlerClass" 
   value="com.cafesoft.security.engine.auth.login.userrepository.CamsXmlUserRepositoryHandler"/>
 </param-list>
</service>

The <service> tag parameter values are:

• id - The identity of this service for this security domain. WARNING: The id must match the corresponding serviceId value in the XmlLoginModule configuration file.
• Enable - Set to true if this service is enabled, false if it is not.

The values <service-type> and <service-class> should not change unless you create a custom XML service.

The <param-list> parameters are:

• repositoryFilePath - The fully qualified file path to the user repository file
• handlerClass - The fully qualified class name of the Java class that parses the XML user repository file
• repositoryFactoryClass - The fully qualified Java class name of the user repository factory

Back | Next | Contents

© Copyright 1996-2003 Cafésoft LLC. All rights reserved.