Cams Administrator's Guide

Security Domain Configuration

Cams uses security domains to logically partition the management of access control, authentication, service configuration and logging. Each Cams policy server may have one or more security domains, each of which must be declared in the security domain registry found in the CAMS_HOME/conf/domains/security-domain-registry.xml file. Only the system security domain is required. All security domains defined within the security domain registry are be configured using these files:

access-control-policy.xml - Configures the access control policy
cams-users.xml - (optional) Declares a Cams XML user repository
login-config.xml - Configures authentication
login-exception.properties - Configure authentication error messages
security-domain.xml - Configures security domain services

This document describes how you configure the Cams security domain registry in security-domain-registry.xml and security domains services in security-domain.xml. See the Security Domain Registry Tag Reference and Security Domain Tag Reference for information on all the XML tags used in the security-domain-registry.xml and security-domain.xml files.

Configuring the Cams Security Domain Registry

The Cams security domain registry maintains basic information about each security domain, including security domain names and the location of configuration files. You can also define global substitution values that can be referenced within all security domain configuration files. The default Cams policy server security-domain-registry.xml file defines two security domains as shown in Example 1:

system - always required and enabled, may delegate to user security domains
mydomain - a template user security domain (disabled by default)

To disable a security domain, set the enabled flag to false. To completely remove a security domain, delete the references in security-domain-registry.xml and remove the corresponding directory and configuration files. To add a new security domain, create a reference to it in security-domain-registry.xml similar to those shown in Example 1 but using the new name. Then, create a new subdirectory with the corresponding security domain name and copy the template XML files from mydomain to the new security domain directory.

<security-domain-registry>

  <!-- User-defined variables that apply across all security domains. -->
  <var-list>
    <var name="cams.logs.base.dir" value="${cams.home}/logs"/>
  </var-list>

  <!-- The system security domain (required) -->
  <security-domain enable="true">
    <name>system</name>
    <home>${cams.home}/conf/domains/system</home>
  </security-domain>

  <!-- The mydomain security domain (template) -->
 	<security-domain enable="false">
    <name>mydomain</name>
    <home>${cams.home}/conf/domains/mydomain</home>
  </security-domain>

</security-domain-registry>

Example 1 - A Cams security domain registry configuration

The system security domain should never be deleted or disabled. By default, it protects all HTTP/HTTPS resources, is used for Cams web agent authentication and is always the initial point of permission delegation to other security domains you may define. You can create and nest as many additional security domains as required for administrative purposes.

Most Cams sites use only the system security domain. You might consider creating and nesting security domains when:

You are managing different user communities from the same Cams policy server. For example, a company may want to manage its intranet and extranet users and resources separately. Or, an ISP may have multiple customers each with their own user communities and resources.
You have auditing or other configuration needs that are facilitated by partitioning resources. For example, you might want to log all Cams web agent authentications within a particular security domain and user authentication and access control events in another.

NOTE: Single sign-on is not supported across security domains. If you delegate resources to more than one security domain, users must authenticate with each security domain separately.

Substitution Values

Example 1 shows use of the intrinsic ${cams.home} security domain substitution value to create a new ${cams.logs.base.dir} substitution value. You can create your own substitution values in any security domain configuration file using the syntax shown. Substitution values are hierarchically inherited from the security domain registry by other security domain configuration files. You can also define values that are specific to a security domain configuration file (or that override those set in security-domain-registry.xml). In addition to values you define, the following intrinsic values are available:

cams.cluster.home - The fully-qualified path to the Cams policy server cluster home directory (the same as ${cams.home} by default).
cams.cluster.name - The name of the Cams cluster to which a given Cams policy server is assigned. Every Cams policy server is in a cluster, even if it's just a cluster of one server.
cams.home - The fully-qualified path to the Cams policy server base directory.
cams.security-domain.home - The security domain home directory as declared by the <home> element of a security domain registration.
cams.security-domain.name - The security domain name as declared by the <name> element of a security domain registration.
cams.server.home - The fully-qualified path to the Cams policy server configuration directory. This will be the same as ${cams.home} unless a cluster and server-specific configuration directory is used.
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.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.

The substitution value ${cams.logs.base.dir} is defined within security-domain-registry.xml and used in security-domain.xml to centralize the location where each security domain writes its log files. If you want security domain log files to be written to security domain-specific directories, you can change or override the value of this value within security-domain.xml. See Security Domain Configuration for more information.

Configuring Cams Security Domains

The Cams policy server's service oriented architecture makes a set of highly flexible services available within each security domain to handle authentication, access control, session management and more. These services are configured and custom services can be deployed through configuration in each security domain's security-domain.xml file. Table 1 summarizes the top-level security domain services.

Service	Description
Authentication Service	Authenticates users according to the security domain's login configuration. Authorized Cams web agents submit authentication requests and receive authentication responses.
Access Control Service	Hosts the security domain-specific access control policy that controls access to the resources protected by a security domain. Authorized Cams web agents submit access control requests and receive access control reponses.
Session Manager Service	Manages sessions corresponding to authenticated users. Sessions keep track of who, when, where and how users authenticated. Sessions may also contain application-specific data that can be accessed via the session access service.
Session Access Service	Provides the information available within an authenticated user's session to an authorized Cams web agent. The session information can be used to customize application behaviour and/or user presentation. It can also be used by access control rules within the access control service to grant or deny access based on business rules.
Session Control Service	Enables authorized Cams web agents to update, close or expire sessions managed within a Cams policy server. A common use for this service is to logout a user by closing the associated session.
Service Manager Service	Manages a set of services conforming to the Cams service API, which are available to components within a security domain. Cams ships with some standard services used by login modules to share pooled JDBC connections and access users, passwords and roles stored within an XML file. Using the Cams service API, you can create reusable services that maintains business state or assist other components hosted within a security domain.

Table 1 - Cams policy server services available within each security domain

Most of the default values supplied with Cams in security-domain.xml will work for most sites as is. This document helps you to understand how to configuresecurity-domain.xml.

Cams Loggers

Because all Cams policy server services write to logs, sometimes to service specific logs, that are configured in security-domain.xml, it is helpful to understand Cams policy service loggers. Cams has two logger types:

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

Message Level	Description
DEBUG	Intended primarily for administrators and developers that need to see low-level details while Cams services execute and components are invoked. During normal Cams policy server production deployments, DEBUG-level messages are disabled.
INFO	Higher-level messages that help an administrator confirm that Cams services are running as expected. When Cams services start, they log a few INFO-level messages to show the startup status.
WARNING	Indicate a condition that should not have occurred and may need attention, but are not crucial to the continued, normal operation of Cams.
ERROR	Indicate a condition that was not expected and threatens the continued operation of Cams. The corresponding condition should be investigated and fixed.
FATAL	The most serious of error conditions in which Cams cannot start or cannot continue running. FATAL conditions must be fixed as Cams will either not startup or will shutdown as gracefully as possible.

Table 2 - A summary of Cams trace log message levels

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. During normal operation, the transactions logs are extremely useful as they contain the audit information you can use to analyze use of the resources on your Cams protected site. The format of each transaction log type is detailed within it's corresponding service section below.

By default, all logs are written to security domain-specific files in the CAMS_HOME/logs directory. The location and names are these files are configurable with security-domain.xml services. Substitution values defined in security-domain-registry.xml are inherited for use within security-domain.xml (and other security domain XML configuration files). You can also define values that are specific to security-domain.xml (or that overrides a variable set in security-domain-registry.xml). One such value, logPrefix, is defined at the top of security-domain.xml and used throughout the file as shown in Example 2.

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

Example 2 - The logPrefix value as defined within the default security-domain.xml file

The logPrefix value centralizes 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.

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

Example 3 - The Cams security domain trace-logger configuration

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

Property	Req/Opt	Description
className	Req	The fully qualified name of the Logger class that will be instantiated.
filePath	Req	The fully qualified log file path.
append	Opt	If true new log messages will be appended to the current log file. If false the current log file will be deleted and a new log file will be created. The default value is true.
bufferedIO	Opt	If true the logger will buffer log messages before writing them to the log file. This can significantly improve logging performance. 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	The maximum size the logfile is allowed to grow before creating a new logfile. Suffixes KB, MB, and GB are recognized. When log files are rolled over, the file name is appended with an numeric digit: 1, 2, 3, etc. The default maxSize value is 4MB.
enableConsole	Opt	If 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 true all log statements that have the level DEBUG will not be logged. The default value is false.
verbose	Opt	If true all DEBUG, INFO, WARN, ERROR, and 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 false ONLY 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 true the logger will output diagnostic debug statements to the System.err stream. The default value is false.

Table 3 - Properties for configuring a Cams trace logger

Configuring the Authentication Service

The Cams policy server authentication service is responsible for validating the identity of a user who accesses protected resources within the security domain. A <login-config-factory> loads and initializes the login configuration as defined in a security domain's login-config.xml file.

An authentication pipeline processes authentication requests issued by a Cams web 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.

An 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. The Cams Authentication Transaction Logger is implemented as an authentication valve. Other useful authentication valves included with Cams are used to configure Cams Automatic HTTP User Login and Cams Cross DNS Domain Web Single Sign-on.

Authentication Log

The authentication log file contains information about successful and unsuccessful authentication requests within a security domain. Example 4 shows how an authentication valve is configured to log 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>
...

Example 4 - Configuring the security domain's authentication transaction logger

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

Field	Req/Opt	Description
logPath	Req	The path to the authentication transaction log file.
append	Opt	If true, then append new records to an existing log file. If false, then overwrite an existing transaction log when the security domain is started. The default value is true.
maxSize	Opt	The maximum size the log file is allowed to grow before creating a new log file. Suffixes KB, MB, and GB are recognized. When log files are rolled over, the log file name is appended with an numeric digit. The default value is 4MB.
logOnAuthFailure	Opt	A mapping of <login-config-entry> names to callback value names. On failed authentication, the callback value corresponding to the <login-config-entry> and callback name is logged. This feature can be used to log the username (if supplied) associated with the failed login. The actual callback value name can depend on the <login-config-entry> and login module(s) configured for that entry. This value is optional, but if not supplied a WARNING is logged to the security domain trace log. The following example shows how security domains containing multiple <login-config-entry> specifications can be configured: <param name="logOnAuthFailure" value="http=username,ws=x509"/>

Table 4 - Properties for configuring an 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 "-" (dash).

Field	Req/Opt	Description
date-time	Req	The local date/time of the authentication attempt at the Cams policy server. Example format: [10/Oct/2000:13:55:36 -0700]. The last value "-0700" represents the offset from universal time (GMT), which enables time comparisons based on absolute time.
remote-address	Req	The IP address of the client requesting authentication.
app-name	Opt	The name of the application attempting authentication. This value must match a login configuration entry within the security domain's login-config.xml. If this value is not specified, then the default application name other is used.
status	Req	The status code of the authentication response: 1 = success, 2 = failed.
reason	Opt	A code indicating the reason authentication failed. See Log and Error Codes for a complete list of codes.
session-id	Opt	The ID of the authenticated subject's session.
subject	Opt	The name of the authenticated subject (e.g. a user name).

Table 5 - The Cams policy server authentication service transaction log fields

Configuring the Access Control Service

The Cams policy server access control service is responsible for controlling access to the resources protected by a security domain. A <access-control-policy-factory> loads and initializes the access control policy that declares the resources protected within a security domain along with the rules for accessing them as defined in a security domain's access-control-policy.xml file.

An access control pipeline processes access requests issued 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.

An 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 Cams web agents on behalf a client wishing to access resources protected by a security domain. Example 5 shows how an access control valve is configured to log 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 name="maxSize" value="10MB"/>
 </param-list>
</access-control-valve>
...

Example 5 - The security domain access control transaction logger

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

Field	Req/Opt	Description
logPath	Req	The path to the access control transaction log file.
append	Opt	If true, then append new records to an existing log file. If false, then overwrite an existing transaction log when the security domain is started. The default value is true.
maxSize	Opt	The maximum size the log file is allowed to grow before creating a new log file. Suffixes KB, MB, and GB are recognized. When log files are rolled over, the log file name is appended with an numeric digit. The default value is 4MB.

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 "-" (dash).

Field	Req/Opt	Description
date-time	Req	The local date/time of the authentication attempt at the Cams policy server. Example format: [10/Oct/2000:13:55:36 -0700]. The last value "-0700" represents the offset from universal time (GMT), which enables time comparisons based on absolute time.
remote-address	Req	The IP address of the client requesting access to the resource.
session-id	Opt	The ID of the authenticated subject's session.
subject	Opt	The name of the authenticated subject (e.g. user name).
resource-type	Req	The type of the resource the client is attempting to access.
resource-id	Req	The identifier of the resource.
resource-actions	Req	The action(s) being requested on the resource. If multiple actions, they are separated by the and character (&).
status	Req	The status code of the access response: 1 = success, 2 = failed
reason	Opt	A code indicating the reason access was granted or denied. See Log and Error Codes for a complete list of codes.

Table 7 - The Cams policy server access control service transaction log fields

Configuring the Session Manager Service

The Cams policy server 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 or closure events. The session manager also supports registration of session event handlers, that can be used to customize the contents of sessions or trigger business processes based on session events. The Examples appendix shows how to configure a number of useful session event handlers included with Cams that enable you to fetch user specific values from SQL databases or LDAP servers to include in a user session at session creation time. You can then make these values available to your web applications for peronalization and fine-grained access control.

Example 6 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-event-handler className="fully-qualified.java.class.name">
    ...
  </session-event-handler>
  ...
</session-manager-service>
...

Example 6 - The session manager service configuration

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

Field	Req/Opt	Description
maxActiveSessions	Opt	The maximum number of concurrent active sessions allowed for this security domain. To specify no maximum use the default value -1.
inactiveSessionTimeout	Opt	The maximum interval (in minutes) an active session is allowed to be inactive before it is expired and removed from the session manager. Value must be greater than 0. The default value is 30 minutes.
sessionCleanupInterval	Opt	The interval (in minutes) the session manager checks and removes expired sessions. Value must be greater than 0. The default value is 1 minute.
sessionIdIPAddrValidationMask	Opt	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 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. If not specified, the default value is 255.255.255.255, the most restrictive IP address validation. The value 0.0.0.0 effectively disables IP address validation.
sessionIdAlgorithm	Opt	The message digest algorithm to be used for encrypting the session identifier. Valid values include SHA or MD5. If not specified, SHA is used.
sessionIdKey	Req	The key used to encrypt session id's. The default value is secret-key. It is highly recommended this value be changed to unique value.

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

Session Manager Log

The session manager log file contains transaction information about security domain sessions as they are created, closed and expired. Example 7 shows the standard session event handler that logs session events, which is disabled (commented out) by default. This logger is generally only used for testing and debug and not in production environments. Uncomment to enable.

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

Example 7 - The Cams session manager transaction logger

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

Field	Req/Opt	Description
logPath	Req	The path to the session manager transaction log file.
append	Opt	If true, then append new records to an existing log file. If false, then overwrite an existing transaction log when the security domain is started. The default value is true.
maxSize	Opt	The maximum size the log file is allowed to grow before creating a new log file. Suffixes KB, MB, and GB are recognized. When log files are rolled over, the log file name is appended with an numeric digit. The default value is 4MB.

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

The session manager transaction log is a comma-delimited text file. Each line corresponds to a session create, close or expire event. Table 10 shows the fields (left to right) defined within this file. If an optional field does not apply, it's value is written as "-" (dash).

Field	Req/Opt	Description
session-id	Req	The ID of the authenticated subject's session.
subject	Req	The name of the subject associated with the session (e.g. user name).
remote-address	Req	The IP address of the client associated with the session.
remote-hostname	Req	The name of the host if it's address has been resolved by DNS or the remote IP address if not.
date-time	Req	The local date/time of the session management event at the Cams policy server. Example format: [10/Oct/2000:13:55:36 -0700] . The last value "-0700" represents the offset from universal time (GMT), which enables time comparisons based on absolute time.
authentication-time	Req	The local date/time at which authentication occured (which may be slightly different than the time at which the session management event is logged). Example format: [10/Oct/2000:13:55:36 -0700]. The last value "-0700" represents the offset from universal time (GMT), which enables time comparisons based on absolute time.
event-type	Req	The type of event associated with session. Values may include: CREATED - a new session was created due to successful authentication CLOSED - an existing session was closed due to explicit logout EXPIRED - an existing session expired for lack of activity
auth-methods	Opt	If the event type is CREATED, then a list of authentication methods separated by the and character (&). Values may include: urn:oasis:names:tc:SAML:1.0:am:password - password urn:ietf:rfc:1510 - kerberos urn:ietf:rfc:2945 - secure remote password urn:oasis:names:tc:SAML:1.0:am:HardwareToken - hardware token urn:ietf:rfc:2246 - SSL/TLS Certificate-based client authentication urn:oasis:names:tc:SAML:1.0:am:X509-PKI - X.509 Public Key urn:oasis:names:tc:SAML:1.0:am:PGP - PGP Public Key urn:oasis:names:tc:SAML:1.0:am:SPKI - SPKI Public Key urn:oasis:names:tc:SAML:1.0:am:XKMS - XKMS Public Key urn:ietf:rfc:3075 - XML Digital Signature

Table 10 - The Cams session manager service transaction log fields

Configuring the Session Access Service

The session access service enables session information to be queried by qualified Cams web agents and made available to your web applications using secure Cams HTTP request headers.

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

A 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 by Cams web agents. Example 8 shows how a session-access-valve is configured for logging session access transactions, which is disabled (commented out) by default. This logger is generally only used for testing and debug and not in production environments. Uncomment to enable.

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

Example 8 - The security domain session access transaction logger

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

Field	Req/Opt	Description
logPath	Req	The path to the session access transaction log file.
append	Opt	If true, then append new records to an existing log file. If false, then overwrite an existing transaction log when the security domain is started. The default value is true.
maxSize	Opt	The maximum size the log file is allowed to grow before creating a new log file. Suffixes KB, MB, and GB are recognized. When log files are rolled over, the log file name is appended with an numeric digit. The default value is 4MB.

Table 11 - Properties for configuring the session access transaction logger

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

Field	Req/Opt	Description
session-id	Req	The ID of the authenticated subject's session.
subject	Req	The name of the subject associated with the session (e.g. user name).
remote-address	Req	The IP address of the client associated with the session.
remote-hostname	Req	The name of the host requesting access to the session if it's address has been resolved by DNS or the remote IP address if not.
date-time	Req	The local date/time of the session access event at the Cams policy server. Example format [10/Oct/2000:13:55:36 -0700]. The last value "-0700" represents the offset from universal time (GMT), which enables time comparisons based on absolute time.
status	Req	The status code of the session access response: 1 = success, 2 = failed
reason	Opt	If status = 2 (session access failed), a code indicating the reason session access failed: 0 = not applicable 1 = general server error 2 = invalid remote IP address 3 = invalid remote host name 4 = unauthorized agent 5 = unknown security domain 6 = unknown session 7 = unknown subject

Table 12 - The Cams policy server session access service transaction log fields

Configuring the Session Control Service

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

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

A 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. A common use for these transactions is to logout an authenticated user by closing the associated session. Example 9 shows how a <session-control-valve> is configured for logging session control transactions, which is disabled (commented out) by default. This logger is generally only used for testing and debug and not in production environments. Uncomment to enable.

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

Example 9 - The Cams security domain session control transaction logger

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

Field	Req/Opt	Description
logPath	Req	The path to the session control transaction log file.
append	Opt	If true, then append new records to an existing log file. If false, then overwrite an existing transaction log when the security domain is started. The default value is true.
maxSize	Opt	The maximum size the log file is allowed to grow before creating a new log file. Suffixes KB, MB, and GB are recognized. When log files are rolled over, the log file name is appended with an numeric digit. The default value is 4MB.

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

Table 14 shows the fields defined within this file.

Field	Req/Opt	Description
date-time	Req	The local date/time of the session control request at the Cams policy server. Example format: [10/Oct/2000:13:55:36 -0700]. The last value "-0700" represents the offset from universal time (GMT), which enables time comparisons based on absolute time.
security-domain-name	Req	The name of the security domain name.
subject	Req	The name of the subject (e.g. user name).
action	Req	The requested action, which may be: CLOSE or EXPIRE.
session-id	Req	The ID of the session being asserted by the remote host.
status	Req	The status code of the session control response: 1 = success, 2 = failed
reason	Opt	If status = 2 (session access failed), a code indicating the reason session control failed: 0 = not applicable 1 = general server error 2 = unknown security domain 3 = invalid session id 4 = invalid subject 5 = poisoned session 6 = session does not exist 7 = null session id

Table 14 - The Cams policy server session control service transaction log fields

Configuring Service Manager Services

The Cams policy server service manager enables deployment of additional security domain services supplied with Cams and custom services that you create using the Cams services API. This section provides information on how to configure services provided 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.

The following services are available to each Cams security domain:

Cams Access Control Policy Monitor Service - Monitors and triggers reloads of a security domain's access-control-policy.xml file.
Active Directory Group Name Service - Provides a cache for lookup of Active Directory group SIDs and their associated names.
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.

You can deploy any number of services, each nested within the <service-manager> start and close tags, which has className and debug parameters. You should not change the className value. If you are having difficulty configuring <service-manager> services, you might set the debug value to true to provide verbose log output.

Example Service Configuration

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 10 and 11 to see how this attribute is used).
service-class - Declares the Java class that implements the 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 email messages. Perhaps the service will be used by a Cams 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 Java classes:

com.myco.message.TextNotifier - a Java interface that extends com.cafesoft.core.service.Service.
com.myco.message.EmailTextNotifier - a Java class that implements interface com.myco.message.TextNotifier and uses SMTP to send an email message.

Example 10 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-manager className="com.cafesoft.core.service.StandardServiceManager">
 ...
 <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>
 ...
</service-manager>

Example 10 - An example Cams service manager service registration for an email notifier

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 11 could be added to make both e-mail and pager text notification available to components.

<service-manager className="com.cafesoft.core.service.StandardServiceManager">
 ...
 <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>
 ...
</service-manager>

Example 11 - An example Cams service manager service registration for a pager notifier

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 requires 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 12 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>

Example 12 - Configuring a JDBC Connection Pool using a Cams-provided Service

The <service> tag parameter values are:

id - The identity of this service for this security domain.
enable - Set to true if this service is enabled, false if it is not.
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 service.

The <param-list> parameters are:

check.seconds - The number of seconds between checks to see if the access-control-policy.xml file has been modified. The value must be between 1 and 120 seconds. The default value is 5 seconds.

Active Directory Group Name Service

Sites that configure the Cams Active Directory login module to return the user's Active Directory tokenGroups attribute must configure this service. The tokenGroups attribute contains a complete list of all groups to which a user belongs. This is an Active Directory computed attribute, meaning it is not stored in Active Directory but dynamically created when queried. The tokenGroups attributes are returned as Active Directory security identifiers (SIDs), which must be resolved to their common names. For performance reasons, the Cams Active Directory group name service looks up all group SIDs and their associated names at Cams server startup or whenever a new group is found. The resulting cache is available for quick reference by the Cams Active Directory login module during user authentication.

Example 13 shows samples values.

<service-manager className="com.cafesoft.core.service.StandardServiceManager">
 ...
 <!-- Register an Active Directory group name lookup service -->
 <service id="active-directory-group-name" enabled="true" debug="false">
  <service-type>com.cafesoft.cams.service.ActiveDirectoryGroupNameService</service-type>
  <service-class>com.cafesoft.security.engine.service.ActiveDirectoryGroupNameServiceImpl</service-class>
  <param-list>
   <param name="host"           value="host.company.com"/>
   <param name="port"           value="389"/>
   <param name="username"       value=""/>
   <param name="password"       value=""/>
   <param name="baseDN"         value="dc=company,dc=com"/>
   <param name="useSSL"         value="false"/>
   <param name="connectTimeout" value="3000"/>
  </param-list>
 </service>
 ...
</service-manager>

Example 13 - Configuring the Cams Active Directory group name 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 Active Directory login module configuration.
enabled - Set to true if this service is enabled, false if it is not.
debug - true enables DEBUG-level messages for this Cams service and false disables them. If enabled, DEBUG messages are logged to the security domain trace log file and include Active Directory connection configuration parameters, service startup/shutdown messages, etc.

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

The <param-list> parameters are:

host - The DNS host name or IP address of the Active Directory server.
port - The Active Directory server connection port (389 by default, 636 for SSL). The Active Directory login module may also connect to the Global Catalog (port 3268 by default).
username - The fully qualified Active Directory user name to use for binding the connection.
password - The user name's password.
baseDN - The base distinguished name to search for available groups. Use a broad value to include all groups in your Active Directory. For example, Active Directory supplies default groups in the Builtin and Users tree nodes. Your Active Directory schema may included both these nodes under a domain node such as dc=domain,dc=company,dc=com, where the values for domain, company and com correspond to the domain configured for your Active Directory.
useSSL - (Optional) A flag that enables/disables use of SSL for connections. Use true to enable SSL, false to disable use of SSL. If not specified, false is the default.
NOTE: You must also import a trusted certificate chain for Active Directory into the Cams keystore at CAMS_HOME/conf/cams-keystore.jks. For complete instructions on how to do this, please see Using SSL when accessing LDAP user directories.
connectTimeout - (Optional) The number of milliseconds to wait to establish an Active Directory server connection before timing out the request. This value provides a way to interrupt an attempted connection, which can take nearly 1 minute to fail in cases where the Activer Directory host is unavailable due to a network outage.
NOTE: To prevent a Cams web agent authentication request timeout from ocurring, make sure the connectTimeout value is less than the connection.authentication.timeout value found in a Cams web agent's cams-webagent.conf file.

JDBC Connection Pool Service

The overhead associating with opening and closing database connections is high. In production or high-volume environments, you can dramatically improve performance by sharing database connections between requests using connection pools. When a connection is needed it is borrowed from the pool and then returned to the pool when done for reuse later.

Cams provides a service that utilizes the Apache Jakarta database connection pooling JDBC driver and underlying classes to provide robust database connection pooling. After configuring a connection pool using this service, other components within the Cams policy server (like login modules, access control rules, managed session event handlers, etc.) can then request a pooled connection using the standard JDBC API. The pooling JDBC driver does the work of expanding and shrinking the pool of connections within the parameters you configure. It can also validate a connection before use, after use and while sitting idle in the pool. Example 14 shows the values you'll configure for your site using the Sample User Database schema and values with the open source HSQLDB relational database.

<service-manager className="com.cafesoft.core.service.StandardServiceManager">
 ...
 <!-- Register a JDBC connection pool -->
 <service id="myusersdb-connection-pool" enabled="true">
 <service-type>com.cafesoft.cams.service.JdbcConnectionPoolService</service-type>
 <service-class>com.cafesoft.security.engine.service.JakartaJdbcConnectionPoolService</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:hsql://localhost/"/>
   <param name="username" value="sa"/>
   <param name="password" value=""/>
   <param name="maxActive" value="5"/>
   <param name="maxIdle" value="1"/>
   <param name="whenExhaustedAction" value="BLOCK"/>
   <param name="maxBlockMillis" value="2000"/>
   <param name="testOnBorrow" value="true"/>
   <param name="testOnReturn" value="false"/>
   <param name="testQuery" value="select USER_ID from USERS where USER_ID = 1"/>
   <param name="timeBetweenEvictionRunsMillis" value="10000"/>
   <param name="minEvictableIdleTimeMillis" value="30000"/>
   <param name="testWhileIdle" value="false"/>
  </param-list>
 </service>
 ...
</service-manager>

Example 14 - Configuring a JDBC connection pool using a Cams-provided service

The <service> tag parameter values are:

id - The unique identity of this service for this security domain.
enabled - 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 service.

The <param-list> parameters are:

debug - true enables DEBUG-level messages for this Cams service and false disables them. If enabled, DEBUG messages are logged to the security domain trace log file and include JDBC connection pool configuration parameters, service startup/shutdown messages, etc.
poolName - the name of the connection pool, which is case sensitive and should contain only alpha-numeric characters, underscores or dashes. The JDBC URL configured with a client such as the JDBC login module will contain this value. If the pool name is "example", then the JDBC URL used by clients should be "jdbc:apache:commons:dbcp:example"
driver - JDBC driver class used to connect with your SQL database. The one shown (org.hsqldb.jdbcDriver) is for the open source Hypersonic SQL database. If you're using DB2, MySQL, Oracle, MSSQL or some other database, substitute this parameter with the appropriate JDBC driver class.
url - the JDBC URL to be used with the driver (configured in step 3) to connect with your SQL database.
username and password - credentials authorized to create connections to your SQL database.
maxActive - the maximum number of connections that can be borrowed from the pool at the same time.
maxIdle - the maximum number of connections that can sit idle in the pool at any time. If a negative number, there is no limit to the number of objects that may be idle at one time.
whenExhaustedAction - specifies the behaviour when the maximum number of active connections have been borrowed and another connection is requested. Valid options include:

FAIL - an SQLException is thrown
GROW - will create a new connection and return it (which essentially makes maxActive meaningless)
BLOCK - block until a new or idle connection is available

maxBlockMillis - if whenExhaustedAction is set to BLOCK, then this value indicates the maximum number of milliseconds to wait for a new or idle connection. If negative, block indefinitely until a connection is available.
testOnBorrow - if true, then the JDBC connection is validated when borrowed from the pool.
testOnReturn - if true, then the JDBC connection is validated when returned to the pool.
testQuery- if connections are to be tested when borrowed and/or when returned, the SQL statement used to test the connection. The SQL statement should return at least one row to indicate success.
timeBetweenEvictionRunsMillis - (optional) the period (in milliseconds) between runs of the eviction thread, which kills idle objects. If negative, then no eviction thread will be launched.
minEvictableIdleTimeMillis - (required if timeBetweenEvictionRunsMillis is set) the minimum duration (in milliseconds) that a connection may sit idle in the pool before it is eligable for eviction due to idleness. If negative, no connection will be dropped from the pool due to idle time alone.
testWhileIdle - true indicates that idle connections should be tested using the testQuery. Connections that fail to validate will be dropped from the pool. If false, then connections will not be tested while idle.

If a JDBC connection pool with name example is configured, the following JDBC driver and URL must be used to request pooled connections:

JDBC Driver class: org.apache.commons.dbcp.PoolingDriver
JDBC URL: jdbc:apache:commons:dbcp:example

WARNING: A JDBC database connection pool configured in any security domain will be available to all other security domains within the same Cams policy server instance. Most customers configure one database connection pool in the system security domain that is shared by any other security domains. If you need to configure multiple database connection pools then you can only use a pool name value once across all security domains in a Cams policy server. Also, because login modules and other internal Cams policy server clients can connect to a JDBC database connection pool from any security domain, consideration should be given to database security if your Cams security domains are administered by distinct administrators or organizations.

Cams XML User Repository Service

The Cams XML user repository service is used with the XML login module. This service loads a Cams user repository file into memory, and provides methods to lookup user names, passwords and roles. The service also detects if the Cams user repository file has changed and reloads if necessary. Example 16 shows the configuration values. Except for the repositoryFilePath, the default values should not usually 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>

Example 16 - Cams XML user repository configuration

The <service> tag parameter values are:

id - The identity of this service for this security domain.

WARNING: You must match this value with the corresponding serviceId value when configuring the XML login module in the login-config.xml 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 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