Cams Administrator's Guide

Security Domain Tag Reference

The security domain's service configuration is defined by the Cams security-domain.xml file. This document contains reference information for each of the tags that can be used within security-domain.xml. The following table shows the file structure with links to each of the possible elements.

Tag Name	Instances	Description
security-domain	1	declares the security domain
var-list	0 ... 1	an optional list of Cams variables available within all security-domain specific configuration files
[var]	0 ... N	provides an initialization/configuration parameter as a generic name/value pair
logger	1	logs debug, info, warning, error, and fatal messages to a security domain-specific log
auth-service	1	authenticates users and creates new sessions
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
login-config-factory	1	loads and initializes the login configuration
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
auth-pipeline	1	processes authentication requests issued by a qualified Cams agent
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
[auth-value]	0 ... N	a single request processing node within the authentication pipeline
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
access-control-service	1	controls access to the resources protected by a security domain
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
access-control-policy-factory	1	loads and initializes the access control policy for security domain's resources
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
access-control-pipeline	1	processes access control requests issued by a qualified Cams agent
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
[access-control-value]	0 ... N	a single request processing node within an access control pipeline
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
session-manager-service	1	manages the sessions for authenticated users
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
[session-event-handler]	0 ... N	registers a session event handler with the session manager
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
session-access-service	1	enables session information to be queried by qualified Cams agents
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
session-access-pipeline	1	processes session access requests
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
[session-access-valve]	0 ... N	a single request processing node within a session access pipeline
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
session-control-service	1	enables sessions to be closed, touched, updated, etc. by qualified Cams agents
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
session-control-pipeline	1	processes session control requests
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
[session-control-valve]	0 ... N	a single request processing node within a session control pipeline
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
service-manager	1	provides for management of security domain-wide services
param-list	0 ... 1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter
[service]	0 ... N	creates and registers a service implementation with the service manager
service-type	1	declares the type of service being registered
service-class	1	declares the implementation of the service
param-list	1	a list of initialization/configuration parameters
[param]	0 ... N	an initialization/configuration parameter

<security-domain>

The top-level element used to define services within a Cams security domain.

Item

Description

Syntax

<security-domain 
  debug="true|false">
  ...
</security-domain>

Attributes

debug

Opt

Activate debug for the security domain. The default is false.

Data

None

Parent Elements

None

Child Elements

<var-list>	Opt	List of parameters available within all security domain specific configuration files.
<logger>	Req	Logs debug, info, warning, error, and fatal messages to a securty domain-specific log.
<auth-service>	Req	Authentices users and creates new sessions.
<access-control-service>	Req	Controls access to the resources protected by a security domain.
<session-manager-service>	Req	Manages the sessions for authenticated users.
<session-access-service>	Req	Enables session information to be queried by qualified Cams agents.
<session-control-service>	Req	Enables sessions to be closed, touched, updated, etc. by qualified Cams agents.
<service-manager>	Opt	Provides optional security domain-wide services.

Example

<security-domain debug="false">

  <!-- Configure the logger -->
  <logger 
    className="com.cafesoft.cams.log.CamsTraceLogger"
    filePath="${cams.home}/logs/system-trace.log"
    debug="false"/>
	
	<!-- Configure the authorization service -->
	<auth-service
		className="com.cafesoft.security.engine.auth.StandardAuthService"
		debug="false">
    ...
  </auth-service>

  <!-- Configure the access control service -->
  <access-control-service
    className="com.cafesoft.security.engine.access.StandardAccessControlService"
    debug="false">
    ...
  </access-control-service>

  <!-- Configure the session manager service -->
  <session-manager-service
    debug="false">
    ...
  </session-manager-service>

  <!-- Configure the session access service -->
  <session-access-service
    className="com.cafesoft.security.engine.session.access.StandardSessionAccessService"
    debug="false">
    ...
  </session-access-service>

  <!-- Configure the session control service -->
  <session-control-service
    className="com.cafesoft.security.engine.session.control.StandardSessionControlService"
    debug="false">
    ...
  </session-control-service>
 				
  <!-- Register services accessible within this security domain -->
  <service-manager
    className="com.cafesoft.core.service.StandardServiceManager"
    debug="false">
    ...
  </service-manager>

</security-domain>

<logger>

Logs DEBUG, INFO, WARNING, ERROR, and FATAL messages to a security domain-specific log.

Item

Description

Syntax

<logger
  className="fully.qualified.JavaClassName"
  filePath="fully qualified file path"
  append="true|false"
  bufferIO="true|false"
  bufferSize="integer value"
  maxSize="string value"
  maxBackupIndex="integer value"
  enableConsoleDebug="true|false"
  enableDebugFilter="true|false"
  verbose="true|false"
  debug="true|false"/>

Attributes

className	Req	The fully qualified name of the Java logger class that will be instantiated.
filePath	Req	The fully qualified path where the log file is written (the value can use forward or back slashes).
append	Opt	If set to true new log messages will be appended to the current log file. If the value is false the current log file will be deleted and a new log file will be created. The default value is true.
bufferedIO	Opt	If set to true the logger will buffer log messages before writing them to the log file. The default value is true.
bufferSize	Opt	Indicates the size of the buffer to fill before writing to the log file. The default value is "4096".
maxSize	Opt	Indicates the maximum size the log file is allowed to grow before creating a new logfile. Suffixes KB, MB, and GB are recognized. The default value is "4MB".
maxBackupIndex	Opt	The maximum rollover file index. When log files are # rolled over, a numeric index is appended to the name, starting with 1 # and proceeding to this value. The default value is 100.
enableConsoleDebug	Opt	If set to true all log statements that are sent to the log file are also sent to the console. The default value is false.
enableDebugFilter	Opt	If set to true all log statements that have the level "DEBUG" will be filtered out (not logged). If set to false, all DEBUG-level log statements will be logged.
verbose	Opt	If set to true all DEBUG, INFO, WARN, ERROR, FATAL messages logged will contain the following format: [INFO ] Sample log message Class Name: com.cafesoft.cams.log.CamsTraceLogger Method Name: info() Line Number: 121 Timestamp: 25 Jul 2002 11:02:36,339 If set to false ONLY messages with the WARNING, ERROR, and FATAL message level will use the verbose format, while DEBUG and INFO level messages will use the following format: [INFO ] Sample Log Message The default value is false.
debug	Opt	If set to true the logger will output diagnostic debug statements to system.err. The default value is false.

Data

None

Parent Elements

1. <security-domain>

Child Elements

None

Example

<logger
  className="com.cafesoft.cams.log.CamsTraceLogger"
  filePath="${cams.home}/logs/system-trace.log"
  append="true"
  bufferIO="true"
  bufferSize="4096"
  maxSize="1GB"
  maxBackupIndex="10"
  enableConsoleDebug="false"
  enableDebugFilter="false"
  verbose="false"
  debug="false"/>

<auth-service>

Implements a security domain's authentication service, which is responsible for validating the identity of a user who accessess protected resources within the security domain.

Item

Description

Syntax

<auth-service
  className="fully.qualified.JavaClassName"
  debug="true|false">
  <param-list>
    ...
  </param-list>
  <login-config-factory ... />
  <auth-pipeline ... >
    ...
  </auth-pipeline>
</auth-service>

Attributes

className	Req	The fully qualified name of the Java authentication service class that will be instantiated.
debug	Opt	Activate debug for this security domain's authentication service. The default value is false.

Data

None

Parent Elements

1. <security-domain>

Child Elements

<param-list>	Opt	A container for a list of initialization/configuration parameters.
<login-config-factory>	Req	Loads and initializes the login configuration.
<auth-pipeline>	Req	Processes authentication requests issued by a qualified Cams agent.

Example

<!-- Configure the authorization service -->
<auth-service
  className="com.cafesoft.security.engine.auth.StandardAuthService"
  debug="false">
  <login-config-factory
    className="com.cafesoft.security.engine.auth.login.XmlLoginConfigurationFactory"
    debug="false">
    <param-list>
      <param name="configPath" 
        value="${cams.security-domain.home}/login-config.xml"/>
    </param-list>
  </login-config-factory>
  <auth-pipeline
    className="com.cafesoft.security.engine.auth.StandardAuthPipeline"
    debug="false">
    <auth-valve
      className="com.cafesoft.security.engine.auth.valves.LogAuthRequestValve"
      debug="false">
      <param-list>
        <param name="logPath" 
          value="${cams.home}/logs/system-authentication.log"/>
      </param-list>
    </auth-valve>
  </auth-pipeline>
</auth-service>

<login-config-factory>

Loads and initializes the security domain's login configuration.

Item

Description

Syntax

<login-config-factory
  className="fully.qualified.JavaClassName"
  params="configPath=fully qualified file path"
  debug="true|false"/>

Attributes

className	Req	The fully qualified name of the Java login configuration factory that will be instantiated.
debug	Opt	Activate debug for this security domain's login-config-factory. The default value is false.

Data

None

Parent Elements

1. <auth-service>

Child Elements

<param-list>

Opt

A container for a list of initialization/configuration parameters.

Example

<login-config-factory
  className="com.cafesoft.security.engine.auth.login.XmlLoginConfigurationFactory"
  debug="false">
  <param-list>
    <param name="configPath" 
      value="${cams.security-domain.home}/login-config.xml"/>
  </param-list>
</login-config-factory>

<auth-pipeline>

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

Item

Description

Syntax

<auth-pipeline
  className="com.cafesoft.security.engine.auth.StandardAuthPipeline"
  debug="true|false">
  <param-list>
    <param name="parameter name" value="parameter value"/>
  </param-list>
  <auth-valve ... />
  ...
</auth-pipeline>

Attributes

className	Req	The fully qualified name of the Java authentication pipeline class that will be instantiated.
debug	Opt	Activate debug for this security domain's authentication pipeline. The default value is false.

Data

None

Parent Elements

1. <auth-service>

Child Elements

<param-list>	Opt	A container for a list of initialization/configuration parameters.
<auth-valve>	Opt	Represents a single node within an auth-pipeline.

Example

<auth-pipeline
  className="com.cafesoft.security.engine.auth.StandardAuthPipeline"
  debug="false">
  <auth-valve
    className="com.cafesoft.security.engine.auth.valves.LogAuthRequestValve"
    debug="false"/>
    <param-list>
      <param name="logPath" 
        value="${cams.home}/logs/system-authentication.log"/>
    </param-list>
  </auth-valve>
</auth-pipeline>

<auth-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 auth-valve in the chain.

Item

Description

Syntax

<auth-valve
  className="fully.qualified.JavaClassName"
  debug="true|false">
  <param-list>
    ...
  </param-list>
</auth-valve>

Attributes

className	Req	The fully qualified name of the Java authenticatoin valve class that will be instantiated.
debug	Opt	Activate debug for this valve node of this security domain. The default value is false.

Data

None

Parent Elements

1. <auth-pipeline>

Child Elements

<param-list>

Opt

A container for a list of initialization/configuration parameters.

Example

<auth-valve
  className="com.cafesoft.security.engine.auth.valves.LogAuthRequestValve"
  debug="false">
  <param-list>
    <param name="logPath" 
      value="${cams.home}/logs/system-authentication.log"/>
  </param-list>
</auth-valve>

<access-control-service>

Specifies the Java class that controls access to the resources protected by a security domain. This element
specifies the Java class that implements the access control service.

Item

Description

Syntax

<access-control-service
  className="fully.qualifed.JavaClassName"
  debug="true|false">
  <access-control-policy-factory>
    ...
  </access-control-policy-factory>
  <access-control-pipeline ... >
    ...
  </access-control-pipeline>
</access-control-service>

Attributes

className	Req	The fully qualified Java class name of the access control service that will be instantiated.
debug	Opt	Activate debug for this security domain's access control service. The default value is false.

Data

None

Parent Elements

1. <security-domain>

Child Elements

<param-list>	Opt	A container for a list of initialization/configuration parameters.
<access-control-policy-factory>	Req	Loads and initializes the access control policy.
<access-control-pipeline>	Req	Processes access control requests issued locally or remotely by a Cams agent.

Example

<!-- Configure the access control service -->
<access-control-service
  className="com.cafesoft.security.engine.access.StandardAccessControlService"
  debug="false">
  <access-control-policy-factory
    className="com.cafesoft.security.engine.access.XmlAccessControlPolicyFactory"
    debug="false"/>
  <access-control-pipeline
    className="com.cafesoft.security.engine.access.StandardAccessControlPipeline"
    debug="false">
    <access-control-valve
      className="com.cafesoft.security.engine.access.valves.LogAccessControlRequestValve"
      debug="false"/>
      <param-list>
        <param name="logPath" value="${cams.home}/logs/system-access-control.log"/>
      </param-list>
    </access-control-valve>
  </access-control-pipeline>
</access-control-service>

<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.

Item

Description

Syntax

<access-control-policy-factory
  className="fully.qualified.JavaClassName"
  debug="true|false"/>

Attributes

className	Req	The fully qualified Java class name of the access control policy factory that will be instantiated.
debug	Opt	Activate debug for this security domain's access control policy factory. The default value is false.

Data

None

Parent Elements

1. <access-control-service>

Child Elements

<param-list>

Opt

A container for a list of initialization/configuration parameters.

Example

<access-control-policy-factory
  className="com.cafesoft.security.engine.access.XmlAccessControlPolicyFactory"
  debug="false"/>

<access-control-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.

Item

Description

Syntax

<access-control-pipeline
  className="fully.qualified.JavaClassName"
  debug="true|false"/>
  <access-control-valve>
    <param-list>
      ...
    </param-list>
  </access-control-valve>
  ...
</access-control-pipeline>

Attributes

className	Req	The fully qualified Java class name of the access control pipeline that will be instantiated.
debug	Opt	Activate debug for this security domain's access control pipeline. The default value is false.

Data

None

Parent Elements

1. <auth-service>

Child Elements

<param-list>	Opt	A container for a list of initialization/configuration parameters.
<access-control-valve>	Opt	Represents a single node within an access control pipeline.

Example

<access-control-pipeline
  className="com.cafesoft.security.engine.access.StandardAccessControlPipeline"
  params=""
  debug="false">
  <access-control-valve
    className="com.cafesoft.security.engine.access.valves.LogAccessControlRequestValve"
    debug="false">
    <param-list>
      <param name="logPath" value="${cams.home}/logs/system-access-control.log"/>
    </param-list>
  <access-control-valve>
</access-control-pipeline>

<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.

Item

Description

Syntax

<access-control-valve
  className="fully.qualified.JavaClassName"
  debug="true|false"/>

Attributes

className	Req	The fully qualified Java class name of the access control valve that will be instantiated.
debug	Opt	Activate debug for this valve node of this security domain. The default value is false.

Data

None

Parent Elements

1. <auth-pipeline>

Child Elements

<param-list>

Opt

A container for a list of initialization/configuration parameters.

Example

<access-control-valve
  className="com.cafesoft.security.engine.access.valves.LogAccessControlRequestValve"
  debug="false">
  <param-list>
    <param name="logPath" value="${cams.home}/logs/system-access-control.log"/>
  </param-list>
</access-control-valve>

<session-manager-service>

Specifies the Java class that manages authenticated user sessions.

Item

Description

Syntax

<session-manager-service
  className="fully.qualifed.JavaClassName"
  debug="true|false">
  <param-list>
    <param name="maxActiveSessions" value="-1"/>
    <param name="inactiveSessionTimeout" value="30"/>
    <param name="sessionCleanupInterval" value="1"/>
    <param name="sessionIdKey" value="secret-key"/>
  </param-list>
  <session-event-handler ... />
</session-manager-service>

Attributes

className	Req	The fully qualified Java class name of the session manager service that will be instantiated.
debug	Opt	Activate debug for this security domain's session manager service. The default value is false.

Data

None

Parent Elements

1. <security-domain>

Child Elements

<param-list>

Opt

A list of initialization/configuration parameters.

For example:

<param-list>
<param name="maxActiveSessions" value="-1"/>
<param name="inactiveSessionTimeout" value="30"/>
<param name="sessionCleanupInterval" value="1"/>
<param name="sessionIdAlgorithm" value="SHA"/>
<param name="sessionIdIPAddrValidationMask"
value="255.255.255.255"/>
<param name="sessionIdKey" value="secret-key"/>
</param-list>

maxActiveSession is the maximum number of concurrent authenticated user sessions that can be managed by the session manager within the enclosing security domain. The value -1 specifies unlimited sessions.

inactiveSessionTimeout is the number of a minutes a user session can be inactive before it will be expired by the session manager. Whener an access control check is done on a session, its "last touched" time is updated.

sessionCleanupInterval is the frequency (in minutes) that the session manager service will check for and expire inactive sessions.

sessionIdAlgorithm is the message digest algorithm to be used for encrypting the Cams session identifier associated with an authenticated user. Valid values include: SHA or MD5. If not specified, SHA is used.

sessionIdIPAddrValidationMask A bit mask used to detect possible hijacked Cams session identifers by validating the associated IP address.

When the session is created (at authentication time) the IP address of the remote client is associated with the session. For every subsequent access control, session access, and session control request, the IP address associated with the request is validated against the original authentication IP address using the mask to indicate which bits to compare. For example, a mask value of: 255.255.255.255 indicates that the entire IP address must match. A value of 255.255.255.0 validates the first three triplets of the IP address.

When supporting web clients accessing resources via the general internet, it may be necessary to loosen IP address validation to support proxy servers or gateway routers that cause subsequent HTTP requests to arrive via different client IP addresses. For example, some commercial ISPs will route HTTP traffic via one network and HTTPS traffic via another causing subsequent requests arriving at a Cams web agent from the same web browser have different remote client IP addresses.

The default value is: 255.255.255.255, the most restrictive IP address validation.

sessionIdKey is a password used to encode the session id for the security domain. Using a unique value for this key keeps other security domains and malicious users from guessing the parameters used to construct a session identifier.

<session-event-handler>

Opt

Registers a session event handler with the session manager.

Example

<!-- Configure 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="sessionIdKey" value="secret-key"/>
  </param-list>
  <session-event-handler
    className="com.cafesoft.security.engine.session.SessionManagerEventLogger">
    <param-list>
      <param name="logPath" 
        value="${cams.home}/logs/system-session-manager.log,append=false"/>
    </param-list>
  </session-event-handler>
</session-manager-service>

<session-event-handler>

Registers a session event handler with the session manager.

Item

Description

Syntax

<session-event-handler
  className="fully.qualifed.JavaClassName"
  debug="false"/>

Attributes

className	Req	The fully qualified Java class name of the access control policy factory that will be instantiated.
debug	Opt	Activate debug for this security domain's session event handler. The default value is false.

Data

None

Parent Elements

1. <session-manager-service>

Child Elements

<param-list>

Opt

A container for a list of initialization/configuration parameters.

Example

<session-event-handler
  className="com.cafesoft.security.engine.session.SessionManagerEventLogger"
  debug="false">
  <param-list>
    <param name="logPath" 
      value="${cams.home}/logs/system-session-manager.log,append=false"/>
  </param-list>
</session-event-handler>

<session-access-service>

Enables session information to be queried by qualified Cams agents.

Item

Description

Syntax

<session-access-service
  className="fully.qualifed.JavaClassName"
  debug="true|false">
  <session-access-pipeline ... >
    ...
  </session-access-pipeline>
</session-access-service>

Attributes

className	Req	The fully qualified Java class name of the session access service that will be instantiated.
debug	Opt	Activate debug for this security domain's session access service. The default value is false.

Data

None

Parent Elements

1. <security-domain>

Child Elements

<param-list>	Opt	A container for a list of initialization/configuration parameters.
<session-access-pipeline>	Req	Processes session access requests from qualified Cams agent.

Example

<!--  Configure the session access service -->
<session-access-service
  className="com.cafesoft.security.engine.session.access.StandardSessionAccessService"
  debug="false">
  <session-access-pipeline
    className="com.cafesoft.security.engine.session.access.StandardSessionAccessPipeline"
    debug="false">
    <session-access-valve
      className="com.cafesoft.security.engine.session.access.valves.LogSessionAccessRequestValve"
      debug="false">
      <param-list>
        <param name="logPath" value="${cams.home}/logs/system-session-access.log">
      </param-list>
    </session-access-valve
  </session-access-pipeline>
</session-access-service>

<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.

Item

Description

Syntax

<session-access-pipeline
  className="fully.qualifed.JavaClassName"
  debug="true|false">
  <session-access-valve ... />
  ...
</session-access-pipeline>

Attributes

className	Req	The fully qualified Java class name of the session access pipeline that will be instantiated.
debug	Opt	Activate debug for this security domain's session access pipeline. The default value is false.

Data

None

Parent Elements

1. <session-access-service>

Child Elements

<param-list>	Opt	A container for a list of initialization/configuration parameters.
<session-access-valve>	Opt	Represents a single node within a session access pipeline.

Example

<session-access-pipeline
  className="com.cafesoft.security.engine.session.access.StandardSessionAccessPipeline"
  debug="false">
  <session-access-valve
    className="com.cafesoft.security.engine.session.access.valves.LogSessionAccessRequestValve"
    debug="false"/>
    <param-list>
      <param name="logPath" value="${cams.home}/logs/system-session-access.log">
    </param-list>
  </session-access-valve>
</session-access-pipeline>

<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.

Item

Description

Syntax

<session-access-valve
  className="fully.qualified.JavaClassName"
  debug="true|false"/>

Attributes

className	Req	The fully qualified Java class name of the session access valve that will be instantiated.
debug	Opt	Activate debug for this valve node of this security domain. The default value is false.

Data

None

Parent Elements

1. <session-access-pipeline>

Child Elements

<param-list>

Opt

A container for a list of initialization/configuration parameters.

Example

<session-access-valve
  className="com.cafesoft.security.engine.session.access.valves.LogSessionAccessRequestValve"
  debug="false">
  <param-list>
    <param name="logPath" value="${cams.home}/logs/system-session-access.log">
  </param-list>
</session-access-valve>

<session-control-service>

Enables sessions to be closed, touched, updated, etc. by qualified Cams agents.

Item

Description

Syntax

<session-control-service
  className="fully.qualifed.JavaClassName"
  debug="true|false">
  <session-control-pipeline ... >
    ...
  </session-control-pipeline>
</session-control-service>

Attributes

className	Req	The fully qualified Java class name of the session control service that will be instantiated.
debug	Opt	Activate debug for this security domain's session control service. The default value is false.

Data

None

Parent Elements

1. <security-domain>

Child Elements

<param-list>	Opt	A container for a list of initialization/configuration parameters.
<session-control-pipeline>	Req	Processes session control requests from qualified Cams agent.

Example

<!-- Configure the session control service -->
<session-control-service
  className="com.cafesoft.security.engine.session.control.StandardSessionControlService"
  debug="false">
  <session-control-pipeline
    className="com.cafesoft.security.engine.session.control.StandardSessionControlPipeline"
    debug="false">
    <session-control-valve
      className="com.cafesoft.security.engine.session.control.valves.LogSessionControlRequestValve"
      debug="false">
      <param-list>
        <param name="logPath" value="${cams.home}/logs/system-session-control.log">
      </param-list>
    </session-control-valve
  </session-control-pipeline>
</session-control-service>

<session-control-pipeline>

Processes session control requests by a Cams agent. 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 or modulate the request for processing by a subsequent valve.

Item

Description

Syntax

<session-control-pipeline
  className="fully.qualifed.JavaClassName"
  debug="true|false">
  <session-control-valve ... />
  ...
</session-control-pipeline>

Attributes

className	Req	The fully qualified Java class name of the session control pipeline that will be instantiated.
debug	Opt	Activate debug for this security domain's session control pipeline. The default value is false.

Data

None

Parent Elements

1. <session-control-service>

Child Elements

<param-list>	Opt	A container for a list of initialization/configuration parameters.
<session-control-valve>	Opt	Represents a single node within a session control pipeline.

Example

<session-control-pipeline
  className="com.cafesoft.security.engine.session.control.StandardSessionControlPipeline"
  debug="false">
  <session-control-valve
    className="com.cafesoft.security.engine.session.control.valves.LogSessionControlRequestValve"
    debug="false">
      <param-list>
        <param name="logPath" value="${cams.home}/logs/system-session-control.log">
      </param-list>
  </session-control-valve>
</session-control-pipeline>

<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.

Item

Description

Syntax

<session-control-valve
  className="fully.qualified.JavaClassName"
  debug="true|false"/>

Attributes

className	Req	The fully qualified Java class name of the ession control valve that will be instantiated.
debug	Opt	Activate debug for this valve node of this security domain. The default value is false.

Data

None

Parent Elements

1. <session-control-pipeline>

Child Elements

<param-list>

Opt

A container for a list of initialization/configuration parameters.

Example

<session-control-valve
  className="com.cafesoft.security.engine.session.control.valves.LogSessionControlRequestValve"
  debug="false">
  <param-list>
    <param name="logPath" value="${cams.home}/logs/system-session-control.log">
  </param-list>
</session-control-valve>

<service-manager>

Provides for management of security domain-wide services.

Item

Description

Syntax

<service-manager
  className="fully.qualifed.JavaClassName"
  debug="true|false">
  <service ... >
    ...
  </service>
  ...
</service-manager>

Attributes

className	Req	The fully qualified name of the Java service manager class that will be instantiated.
debug	Opt	Activate debug for this security domain's service manager. The default value is false.

Data

None

Parent Elements

1. <security-domain>

Child Elements

<param-list>	Opt	A container for a list of initialization/configuration parameters.
<service>	Req	Creates and registers a service implementation with the service manager.

Example

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

  <!-- Register a user repository service for cams-users.xml -->
  <service id="cams-user-repository" enabled="true">
    <service-type>com.cafesoft.security.engine.service.UserRepositoryService</service-type>
    <service-class>com.cafesoft.security.engine.service.UserRepositoryService</service-class>
    <param-list>
      <param name="repositoryFilePath"
        value="${cams.security-domain.home}/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 name="debug" value="false"/>
    </param-list>
  </service>
</service-manager>

<service>

Creates and registers a service implementation with the service manager.

Item

Description

Syntax

<service 
  id="textual identifier"
  enabled="true|false""
  debug="true|false">
  <service-type>fully.qualified.JavaClassName</service-type>
  <service-class>fully.qualified.JavaClassName</service-class>
  <param-list>
    ...
  </param-list>
</service>

Attributes

id	Req	The unique textual identifier or name by which this service will be referenced.
enabled	Req	If true, initializes and make this service available. The default is true.
debug	Opt	Activate debug for this security domain's session control pipeline. The default value is false.

Data

None

Parent Elements

1. <service-manager>

Child Elements

<service-type>	Req	Declares the type of service being registered.
<service-class>	Req	Declares the implementation of the service.
<param-list>	Req	A container for a list of initialization/configuration parameters.

Example

<!-- Register a user repository service for cams-users.xml -->
<service 
  id="cams-user-repository" 
  enabled="true"
  debug="false">
  <service-type>com.cafesoft.security.engine.service.UserRepositoryService</service-type>
  <service-class>com.cafesoft.security.engine.service.UserRepositoryService</service-class>
  <param-list>
    <param name="repositoryFilePath"
      value="${cams.security-domain.home}/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 name="debug" value="false"/>
  </param-list>
</service>

<service-type>

Declares the type of service being registered (a Java interface).

Item	Description
Syntax	<service-type>fully.qualified.JavaClassName</service-type>
Attributes	None
Data	None
Parent Elements	1. <service>
Child Elements	None
Example	<!-- Register a user repository service for cams-users.xml --> <service id="cams-user-repository" enabled="true" debug="false"> <service-type>com.cafesoft.security.engine.service.UserRepositoryService</service-type> <service-class>com.cafesoft.security.engine.service.UserRepositoryService</service-class> <param-list> ... </param-list> </service>

<service-class>

Declares the Java class that implements the service.

Item	Description
Syntax	<service-class>fully.qualified.JavaClassName</service-class>
Attributes	None
Data	None
Parent Elements	1. <service>
Child Elements	None
Example	<!-- Register a user repository service for cams-users.xml --> <service id="cams-user-repository" enabled="true" debug="false"> <service-type>com.cafesoft.security.engine.service.UserRepositoryService</service-type> <service-class>com.cafesoft.security.engine.service.UserRepositoryService</service-class> <param-list> ... </param-list> </service>

<var-list>

An optional list of Cams variables that can be used to set security domain substitution values. These variables are useful in defining values that are frequently used in security domain configuration files.

Item

Description

Syntax

<var-list>
  <var ... />
  ...
</var-list>

Attributes

None

Data

None

Parent Elements

1. <security-domain>

Child Elements

<var>

Opt

An initialization/configuration parameter as a generic name/value pair.

Example

<var-list>
  <var name="name1" value="value1"/>
</var-list>

<var>

A Cams variable is used to set a global substitution value. These values are useful in working with a security domains configuration files, especially where test and production deployments are on distinct hosts.

Item

Description

Syntax

<var name="textual name" value="value"/>

Attributes

name	Req	The textual param name.
value	Req	The param value.

Data

None

Parent Elements

1. <var-list>

Child Elements

None

Example

<var-list>
  <var name="name1" value="value1"/>
  <var name="name2" value="value2"/>
  <var name="${name1}_substituted" value="${name1} and ${name2}"/>
</var-list>

<param-list>

A list of parameters that can be used to set initialization or configuration values.

Item

Description

Syntax

<param-list>
  <param ... />
  ...
</param-list>

Attributes

None

Data

None

Parent Elements

1. <auth-service>
2. <login-config-factory>
3. <auth-pipeline>
4. <auth-valve>
5. <access-control-service>
6. <access-control-policy-factory>
7. <access-control-pipeline>
8. <access-control-valve>
9. <session-manager-service>
10. <session-event-handler>
11. <session-access-service>
12. <session-access-pipeline>
13. <session-access-valve>
14. <session-control-service>
15. <session-control-pipeline>
16. <session-control-valve>
17. <service-manager>
18. <service>

Child Elements

<param>

Opt

An initialization/configuration parameter as a generic name/value pair.

Example

<param-list>
  <param name="textual name" value="value">
</param-list>

<param>

A parameter used to set a single initialization or configuration value.

Item

Description

Syntax

<param name="textual name" value="value"/>

Attributes

name	Req	The textual param name.
value	Req	The param value.

Data

None

Parent Elements

1. <param-list>

Child Elements

None

Example

<param-list>
  <param name="textual name" value="value">
</param-list>

Back | Next | Contents