Security Domain Configuration

The power of the Cams policy server is unleashed through high-level services that handle Cams web 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 Substitution Values

The following substitution values are available in every security domain:

• cams.server.name - The name assigned to the Cams policy server via its registration file: ${cams.home}/conf/cams-reg-default.conf or cams-reg-<IP address>.
• cams.cluster.name - The name of the Cams cluster to which a given Cams policy server is assigned. Every Cams policy server runs in a cluster, even if it's just a cluster of one server. The default Cams cluster name is MyCamsCluster
• cams.home - The fully qualified path to the Cams installation directory (set based on an environment variable defined within runcams.bat or runcams.sh).
• cams.cluster.home - The path to the Cams cluster configuration home directory. By default this is the same as cams.home.
• cams.server.home - The path to the Cams policy server configuration directory. This may or may not be the same as cams.home depending on whether or not a cluster-specific and server-specific configuration directory has been created. By default, cams.server.home will be the same as cams.home.
• cams.server.port - The TCP/IP port number on which the Cams policy server listens for connection by Cams web agents as configured in ${cams.home}/conf/cams.conf.
• cams.security-domain.name - The name of a given security domain (set based on the <name> element of a <security-domain> registration).
• cams.security-domain.home - The home directory for a security domain (set based on the <home> element of a <security-domain> registration).

Substitution values defined in the security domain registry are inherited for use within security-domain.xml and other configuration files. You can also define values that are specific to a security domain configuration file (or that overrides a variable set in security-domain-registry.xml). One such value is defined within the security-domain.xml files included with Cams as shown in example 1.

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

The logPrefix value is used to centralize the location of Cams log files while giving them security domain-specific names. This value is substituted throughout security-domain.xml, where 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 policy server services and includes five different levels of messages: DEBUG, INFO, WARNING, ERROR, and FATAL which are summarized in Table 2. Trace loggers enable you to follow (trace) requests made to a Cams policy server through the services that handle it. In the case of serious errors, the trace logger 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 policy 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 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 is responsible for controlling 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 web 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 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 web 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 used to customize the contents of sessions or trigger business processes based on session events.

Example 5 shows the default configuration of the the 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 session manager log file contains information about the sessions created, closed, and expired. (A session is associated with an authenticated subject within a security domain). Example 6 shows the standard 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 session access service enables session information to be queried by qualified Cams web agents.

Session Access Pipeline

The session access pipeline processes session access requests by a Cams web 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 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 session control service enables sessions to be updated, closed, expired, etc. by authorized Cams web agents.

Session Control Pipeline

The session control pipeline processes session control requests by a Cams web 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 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:

• Cams Access Control Policy Monitor Service - Monitors a security domain's access-control-policy.xml file and triggers the access control service to reload it when appropriately modified.
• Cams JDBC Connection Pooling Service - Shares database connections to an SQL database
• 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 <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 service within the scope of the enclosing security domain. A service 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 creates 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 messages to be sent to a pager, then 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.

Access Control Policy Monitor Service

Rather than requiring a Cams policy server restart to load a modified access control policy, this service monitors the access control policy and triggers the access control service to reload it automatically. Because the default Cams access control policy is stored in a security domain-specific access-control-policy.xml file, that file is monitored for updates. If the file is modified, then the access control service is triggered to reload it.

The access control service will require that the reloaded access control policy's "lastModifiedTime" date/time be greater than the "lastModifiedTime" date/time for the currently loaded access control policy. If it is not, then reloading will fail. If access control policy reloading fails for any reason, this service will not trigger reloading again until the access-control-policy.xml file is updated.

The access control policy monitor service logs messages, including reload notifications, errors, and debugging information to the enclosing security domain's trace log. For more information on managing access-control-policy.xml files in a Cams policy server and policy server cluster, see Managing an Access Control Policy. Example 11 shows the recommended values for this service.

<service-manager className="com.cafesoft.core.service.StandardServiceManager">
 ...
 <!-- Register a service to monitor the access-control-policy.xml file and trigger reloading -->
 <service id="access-control-policy-monitor-service" enabled="true" debug="false">
  <service-type>com.cafesoft.security.engine.service.AccessControlPolicyMonitor</service-type>
  <service-class>com.cafesoft.security.engine.service.XmlAccessControlPolicyMonitor</service-class>
  <param-list>
   <param name="check.seconds" value="5"/>
  </param-list>
 </service>
 ...
</service-manager>

The <service> tag parameter values are:

1. id - The identity of this service for this security domain.
   
2. enable - Set to true if this service is enabled, false if it is not. If disabled, the automatic access-control-policy.xml reloading will be disabled.
3. debug - Enable DEBUG-level log messages written to the security domain trace log.

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

The <param-list> parameters are:

1. check.seconds - the number of seconds between access-control-policy.xml modification checks. The minimum is 1, maximum is 120, and default value is 5 seconds.

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 12 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 usernames, 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-2004 Cafésoft LLC. All rights reserved.