Back | Next | Contents Cams Administrator's Guide

Examples

The Cams documentation download includes an examples.zip file that contains source code for useful Cams policy server pluggin examples and some components such as Cams login modules. All Cams policy server examples are included in compiled format in the CAMS_HOME/lib directory and are available for immediate configuration if no modifications are required. Because many Cams customers find these examples both convenient and useful as is, this document describes how to configure and use the most popular Cams examples. Examples not documented here may be documented in the Cams Programmer's Guide.

JDBC Logger Authentication Request Valve

The Cams JDBC Logger Authentication Request Valve compliments or replaces the default Cams Log Authentication Request Valve writing matching authentication requests to a database table rather than a file. This valve uses the Cams authentication valve API, which is an unpublished Cams API. Usage of unpublished Cams API's in this valve as is may not be supported in future releases of Cams.

Register the Valve

Example 1 shows how to register and configure the example JdbcLoggerAuthRequestValve by adding the <auth-valve> element and attributes to the <authentication-service> in security-domain.xml.

NOTE: To continue using the LogAuthRequestValve to log to a local file, do not change its configuration (recommended for fault tolerance). Otherwise, comment or or delete the default reference to the LogAuthRequestValve.

<!-- Configure the authentication service -->
<auth-service
className="com.cafesoft.security.engine.auth.StandardAuthService"> ... <!-- Configure the authentication event JDBC database logging valve -->
<auth-valve className="examples.valves.JdbcLoggerAuthRequestValve" debug="false">
<param-list> <param name="jdbcDriver" value="org.apache.commons.dbcp.PoolingDriver"/> <param name="jdbcUrl" value="jdbc:apache:commons:dbcp:example-jdbc-pool"/>
<param name="insertSql" value="insert into MYDOMAIN_AUTHENTICATION_LOG (EVENT_DATE, REMOTE_ADDRESS, LOGIN_CONFIG, STATUS, REASON, SESSION_ID, USER_NAME)
values (?, ?, ?, ?, ?, ?, ?)
"/>
<param name="logOnAuthFailure" value="http=username"/>
</param-list>
</auth-valve> ... </auth-service>

Example 1 - Register the JDBC Logger Authentication Request Valve example within a security domain

The parameters for this example are:

  • jdbcDriver - the fully-qualified class name of the JDBC driver to use. NOTE: Example 1 shows use of a JDBC connection pooling driver that dramatically improves performance and scalability for components like this logger valve. You are highly advised to use connection pooling. For more information, see section Using JDBC Connection Pooling in the Cams Administrator's Guide.
  • jdbcUrl - the JDBC database connection URL.
  • jdbcUser - (optional) The user name to access the database.
  • jdbcPassword - (optional) The password to access the database.
  • insertSql - The SQL prepared statement to insert the log entry into the database. For example, for the default database schema (see Example 2) uses:

    insert into CAMSTOUR_AUTHENTICATION_LOG (EVENT_DATE, REMOTE_ADDRESS, LOGIN_CONFIG, STATUS, REASON, SESSION_ID, USER_NAME) values (?, ?, ?, ?, ?, ?, ?)

  • logOnAuthFailure - A comma-separated list of the callback values to log on authentication failure. For example, for user name and password authentication using the http <login-config-entry>, your are advised to use only the username callback value to avoid logging sensitive password information.

After setting all configuration values, creating a compatible table in your database and installing the appropriate JDBC driver in CAMS_HOME/lib, you'll need to restart the Cams policy server to test the configuration.

NOTE: This valve ignores authentication requests for login-config type cams-agent.

+----------------+-------------+------+-----+---------+-------+
| Field          | Type        | Null | Key | Default | Extra |
+----------------+-------------+------+-----+---------+-------+
| EVENT_DATE     | datetime    | YES  | MUL | NULL    |       |
| REMOTE_ADDRESS | varchar(15) | YES  |     | NULL    |       |
| LOGIN_CONFIG   | varchar(10) | YES  |     | NULL    |       |
| STATUS         | int(11)     | YES  | MUL | NULL    |       |
| REASON         | int(11)     | YES  |     | NULL    |       |
| SESSION_ID     | varchar(96) | YES  |     | NULL    |       |
| USER_NAME      | varchar(50) | YES  | MUL | NULL    |       |
+----------------+-------------+------+-----+---------+-------+
CREATE TABLE `mydomain_authentication_log` (
 `EVENT_DATE` datetime default NULL,
 `REMOTE_ADDRESS` varchar(15) default NULL,
 `LOGIN_CONFIG` varchar(10) default NULL,
 `STATUS` int(11) default NULL,
 `REASON` int(11) default NULL,
 `SESSION_ID` varchar(96) default NULL,
 `USER_NAME` varchar(50) default NULL,
 KEY `USERNAME` (`USER_NAME`),
 KEY `RESULT` (`STATUS`),
 KEY `EVENT_DATE` (`EVENT_DATE`)
 ) ENGINE=MyISAM DEFAULT CHARSET=latin1

Example 2 - Default MySQL database schema for the JDBC Logger Authentication Request Valve

JDBC Logger Access Control Valve

The Cams JDBC Logger Access Control Valve compliments or replaces the default Cams Log Access Control Valve writing matching access control requests to a database table rather than a file. This valve uses the Cams access control valve API, which is an unpublished Cams API. Usage of unpublished Cams API's in this valve as is may not be supported in future releases of Cams.

Register the Valve

Example 3 shows how to register and configure the example JdbcLoggerAccessControlValve by adding the <access-control-valve> element and attributes to the <access-control-service> in security-domain.xml.

NOTE: To continue using the LogAccessControlRequestValve to log to a local file, do not change its configuration (recommended for fault tolerance). Otherwise, comment or or delete the default reference to the LogAccessControlRequestValve.

<!-- Configure the access control service -->
<access-control-service
className="com.cafesoft.security.engine.access.StandardAccessControlService"> ... <!-- Configure the access control request JDBC database logging valve -->
<access-control-valve className="examples.valves.JdbcLoggerAccessControlValve" debug="false">
<param-list> <param name="jdbcDriver" value="org.apache.commons.dbcp.PoolingDriver"/> <param name="jdbcUrl" value="jdbc:apache:commons:dbcp:example-jdbc-pool"/>
<param name="insertSql" value="insert into MYDOMAIN_ACCESS_CONTROL_LOG
(EVENT_DATE, REMOTE_ADDRESS, SESSION_ID, USER_NAME, RESOURCE_TYPE,
RESOURCE_ID, RESOURCE_ACTION, STATUS, REASON)
values (?, ?, ?, ?, ?, ?, ?, ?, ?)
"/>
<param name="cond1.match.resource-type" value="http"/>
<param name="cond1.match.resource-id" value="^.\*\/downloads/mystuff/.*$"/>
<param name="cond1.match.resource-actions" value="GET"/>
<param name="cond1.match.response-status" value="GRANTED"/>
<param name="cond2.match.resource-type" value="http"/>
<param name="cond2.match.resource-id" value="^.\*\/downloads/yourstuff/.*$"/>
<param name="cond2.match.resource-actions" value=""/>
<param name="cond2.match.response-status" value=""/>
</param-list>
</access-control-valve> ... </access-control-service>

Example 3 - Register the JDBC Logger Access Control Valve example within a security domain

The parameters for this example are:

  • jdbcDriver - the fully-qualified class name of the JDBC driver to use. NOTE: Example 3 shows use of a JDBC connection pooling driver that dramatically improves performance and scalability for components like this logger valve. You are highly advised to use connection pooling. For more information, see section Using JDBC Connection Pooling in the Cams Administrator's Guide.
  • jdbcUrl - the JDBC database connection URL.
  • jdbcUser - (optional) The user name to access the database.
  • jdbcPassword - (optional) The password to access the database.
  • insertSql - The SQL prepared statement to insert the log entry into the database. For example, for the default database schema (see Example 4) uses:

    insert into MYDOMAIN_ACCESS_CONTROL_LOG (EVENT_DATE, REMOTE_ADDRESS, SESSION_ID, USER_NAME, RESOURCE_TYPE,
    RESOURCE_ID, RESOURCE_ACTION, STATUS, REASON) values (?, ?, ?, ?, ?, ?, ?, ?, ?)

  • condN.match.resource-type - The type of protected resources to be matched. Valid values include a registered resource type (e.g. http, cams, etc) or an empty string. If empty or not specified, all resource types are matched. For the first condition, replace the letter "N" with the number "1". Number additional conditions sequentially.
  • condN.match.resource-id- A regular expression used to match the identifier of the requested resource. If not specified, then
    * all requested resources match. For the first condition, replace the letter "N" with the number "1". Number additional conditions sequentially.
  • condN.match.resource-actions - The resource request actions to be matched. If empty or not specified, then all actions are matched. If multiple actions are specified (e.g. "GET,POST"), an access control request matches if any of the actions match. For the first condition, replace the letter "N" with the number "1". Number additional conditions sequentially.
  • condN.match.response-status - The access control response status that must match the access control request. Valid values include: "GRANTED", "DENIED", "PENDING", "" (empty), or null (the parameter is not specified). A not specified or empty value matches any access control response status. For the first condition, replace the letter "N" with the number "1". Number additional conditions sequentially.

After setting all configuration values, creating a compatible table in your database and installing the appropriate JDBC driver in CAMS_HOME/lib, you'll need to restart the Cams policy server to test the configuration.

WARNING: This JDBC access control valve has not been optimized to buffer access control events before writing to the database. Sites under heavy load may experience performance degradation. You should thoroughly benchmark before deploying this valve into production. Reducing the number of matches to those only of interest is helpful. For example, you can enhance the condN.match.resource-id regular expression to elminate gifs, style sheets, javascript. etc. Or, you could choose to only log events with a "DENIED" status.

+-----------------+--------------+------+-----+---------------------+-------+
| Field | Type | Null | Key | Default | Extra |
+-----------------+--------------+------+-----+---------------------+-------+
| EVENT_DATE | datetime | YES | | 0000-00-00 00:00:00 | |
| REMOTE_ADDRESS | varchar(15) | YES | | NULL | |
| SESSION_ID | varchar(96) | YES | MUL | NULL | |
| USER_NAME | varchar(50) | YES | | NULL | |
| RESOURCE_TYPE | varchar(10) | YES | | NULL | |
| RESOURCE_ID | varchar(128) | YES | | NULL | |
| RESOURCE_ACTION | varchar(10) | YES | | NULL | |
| STATUS | int(11) | YES | | NULL | |
| REASON | int(11) | YES | | NULL | |
+-----------------+--------------+------+-----+---------------------+-------+
CREATE TABLE `mydomain_access_control_log` (
`EVENT_DATE` datetime default '0000-00-00 00:00:00',
`REMOTE_ADDRESS` varchar(15) default NULL,
`SESSION_ID` varchar(96) default NULL,
`USER_NAME` varchar(50) default NULL,
`RESOURCE_TYPE` varchar(10) default NULL,
`RESOURCE_ID` varchar(128) default NULL,
`RESOURCE_ACTION` varchar(10) default NULL,
`STATUS` int(11) default NULL,
`REASON` int(11) default NULL,
KEY `SESSION_ID` (`SESSION_ID`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1

Example 4 - Default MySQL database schema for the JDBC Logger Authentication Request Valve

JDBC User Attribute Managed Session Event Handler

A component that plugs into the Cams manage session event service (configured in security-domain.xml) to add user-specific values to a Cams session using a SQL database query. For example, after a session is successfully created, you might query values such as a users employee ID or country. These values then are useful throughout the user session for webapp personalization, fine-grained access controls and custom Cams access control rules.

Cams makes session information available to webapps using secure HTTP request headers. Cams composes the HTTP header name for each value using the prefix CAMS-HTTP-, then the namespace followed by a dash and the value name. For example, a session value of EMPLOYEE_ID in the namespace USERINFO would be available in the header named:

CAMS-HTTP-USERINFO-EMPLOYEE_ID

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

This Cams component queries configurable user-specific data from a relational database and inserts the corresponding result set name/value pairs as attributes into a Cams session. The database column names are used for the attribute name. Result sets should only return one row as only the first row of the result set is processed.

Register the Session Event Handler

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

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

 ...

 <session-event-handler
  className="examples.session.JdbcUserAttributeManagedSessionEventHandler"
  debug="false">
<param-list> <param name="jdbcDriver" value="org.apache.commons.dbcp.PoolingDriver"/> <param name="url" value="jdbc:apache:commons:dbcp:example-jdbc-pool"/> <param name="user" value=""/> <param name="password" value=""/> <param name="sql" value="SELECT EMPLOYEE_ID FROM USER_ACCOUNTS WHERE USER_NAME = ?"/> <param name="nameSpace" value="userinfo"/> <param name="excludeUsers" value="cams-web-agent"/>
</param-list>
</session-event-handler> ... </session-manager-service>

Example 5 - Register the JDBC User Attribute Managed Session Event Handler example within a security domain

The parameters for this example are:

  • jdbcDriver - the fully qualified class name of the JDBC driver to use
  • url - the JDBC database connection URL
  • user - (optional) the user account to connect to the database
  • password - (optional) the password for the user account to connect to the database
  • sql - the SQL for the prepared statement that will be used to query the attribute value, the login user name will be substituted for the question mark ("?")
  • nameSpace - the session attribute's namespace.
  • excludeUsers - (optional) a comma-delimited list of user names to exclude (it is generally recommended that you minimally excluded the cams-web-agent user name to prevent the database query from triggering for Cams web agent logins)

NOTE: Example 1 shows use of a JDBC driver provided by Cams that pools JDBC Connections and can dramatically improve performance and scalability for session event handlers. For more information, see section Using JDBC Connection Pooling in the Cams Administrator's Guide.

JDBC Last Login Managed Session Event Handler

A component that plugs into the Cams manage session event service (configured in security-domain.xml) to to fetch the previous last login value and set a new one using SQL database queries. This component is useful when SQL databases are the configured user direction and features similar to those found in LDAP servers and Active Directory are desired to track a user's last successful login.

Cams makes session information available to webapps using secure HTTP request headers. Cams composes the HTTP header name for each value using the prefix CAMS-HTTP-, then the namespace followed by a dash and the value name. For example, a session value of LAST_LOGIN in the namespace USERINFO would be available in the header named:

CAMS-HTTP-USERINFO-LAST_LOGIN

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

Register the Session Event Handler

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

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

 ...

 <session-event-handler
  className="examples.session.JdbcLastLoginManagedSessionEventHandler"
  debug="false">
<param-list> <param name="jdbcDriver" value="org.apache.commons.dbcp.PoolingDriver"/> <param name="url" value="jdbc:apache:commons:dbcp:example-jdbc-pool"/> <param name="user" value=""/> <param name="password" value=""/> <param name="queryPreparedStatement" value="SELECT DATE_FORMAT(LAST_LOGIN, '%b %d, %Y %l:%i:%s %p') FROM USER_ACCOUNTS WHERE USER_NAME = ?"/> <param name="updatePreparedStatement" value="UPDATE USER_ACCOUNTS SET LAST_LOGIN = ? WHERE USER_NAME = ?"/> <param name="nameSpace" value="userinfo"/> <param name="excludeUsers" value="cams-web-agent"/>
</param-list>
</session-event-handler> ... </session-manager-service>

Example 6 - Register the JDBC Last Login Managed Session Event Handler example within a security domain

The parameters for this example are:

  • jdbcDriver - the fully qualified class name of the JDBC driver to use
  • url - the JDBC database connection URL
  • user - (optional) the user account to connect to the database
  • password - (optional) the password for the user account to connect to the database
  • queryPreparedStatement - the SQL for the prepared statement that will be used to query the last login date as a string formatted value, the login user name will be substituted for the question mark ("?")
  • updatePreparedStatement - the SQL for the prepared statement that will be used to update the last login date value, the current date/time will be substituted for the first question mark ("?") and the login user name will be substituted for the second question mark
  • nameSpace - the session attribute's namespace.
  • excludeUsers - (optional) a comma-delimited list of user names to exclude (it is generally recommended that you minimally excluded the cams-web-agent user name to prevent the database query from triggering for Cams web agent logins)

NOTE: Example 2 shows use of a JDBC driver provided by Cams that pools JDBC Connections and can dramatically improve performance and scalability for session event handlers. For more information, see section Using JDBC Connection Pooling in the Cams Administrator's Guide.

LDAP User Attribute Managed Session Event Handler

NOTE: The LDAP User Attribute Managed Session Event Handler is deprecated with the Cams 3.1 release. We recommended using the UnboundID LDAP User Attribute Managed Session Event Handler, which has feature, performance and stability enhancements without comprise of functionality.

A component that plugs into the Cams manage session event service (configured in security-domain.xml) to add user-specific values to a Cams session using a LDAP search filter. For example, after a session is successfully created, you might query values such as a users employee ID or country. These values then are useful throughout the user session for webapp personalization, fine-grained access controls and custom Cams access control rules.

Cams makes session information available to webapps using secure HTTP request headers. Cams composes the HTTP header name for each value using the prefix CAMS-HTTP-, then the namespace followed by a dash and the value name. For example, a session value of COUNTRY in the namespace USERINFO would be available in the header named:

CAMS-HTTP-USERINFO-COUNTRY

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

This component queries configurable user-specific data from a LDAP server and inserts the corresponding result set name/value pairs as attributes into a Cams session. The LDAP attribute names are used for the Cams session attribute name. If multiple attribute values are returned for a given attribute, only the first value is used.

Register the Session Event Handler

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

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

 ...

 <session-event-handler
  className="examples.session.LdapUserAttributeManagedSessionEventHandler"
  debug="false">
<param-list> <param name="connectionHost" value="host.domain.com"/> <param name="connectionPort" value="389"/> <param name="ldapVersion" value="3"/> <param name="connectTimeout" value="3000"/> <param name="useSSL" value="false"/> <param name="loginDN" value=""/> <param name="loginPassword" value=""/> <param name="searchBase" value="ou=people,dc=domain,dc=com"/> <param name="searchScope" value="ONE"/> <param name="searchPattern" value="(uid={username})"/> <param name="searchAttributes" value="attr1,attr2,attr3..."/> <param name="nameSpace" value="userinfo"/> <param name="excludeUsers" value="cams-web-agent"/>
</param-list>
</session-event-handler> ... </session-manager-service>

Example 7 - Register the LDAP User Attribute Managed Session Event Handler example within a security domain

The parameters for this example are:

  • connectionHost - The LDAP server host name or IP address.
  • connectionPort - The LDAP server port number.
  • ldapVersion - The LDAP protocol version. If not specified, 3 is the default.
  • connectTimeout - (optional) The number of milliseconds to wait to establish a LDAP 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 LDAP server host is unavailable due to a network outage. If not specified, 3000 is the default.
  • 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 your LDAP server 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.
  • loginDN - The user account to bind to the LDAP server.
  • loginPassword - The password for the bind user account.
  • searchBase - The base distinguished name to use for your LDAP schema role searches.
  • searchScope - Specifies the LDAP search scope to use for role searches. Valid values are BASE (search is done only at the base dn tree node), ONE (search is done only at the first child tree node of the base dn), and SUB (search is done at the base dn node and all child nodes).
  • searchPattern - The filter pattern to use to search for a user. The user name entered by the user at login will be substituted for the value "{username}".
    NOTE: Search filters often contain an ampersand character ("&"). To prevent a search filter ampersand from being interpreted by the Cams XML parser as tag, you must substitute the value "&amp;" for any ampersands in the filter.
  • searchAttributes - A comma-delimited list of attributes to return.
  • nameSpace - the session attribute's namespace. If null or an empty string, then the default namespace: "default:namespace" is used.
  • excludeUsers - (optional) a comma-delimited list of user names to exclude (it is generally recommended that you minimally excluded the cams-web-agent user name to prevent the database query from triggering for Cams web agent logins).

Role Login Notifier Managed Session Event Handler

A component that plugs into the Cams manage session event service (configured in security-domain.xml) to send a text message when user's with a specified role login. By default, this example sends the text message to a specified email address using a Cams SMTP notifier service. Information on the configuration of both components is provided.

Register the Session Event Handler

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

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

 ...

 <session-event-handler
  className="examples.session.examples.service.RoleLoginNotifier"
  debug="false">
<param-list> <param name="fromAddress" value="user@domain.com"/> <param name="msgSubject" value="User Login"/> <param name="roleName" value="everyone"/>
</param-list>
</session-event-handler> ... </session-manager-service>

Example 8 - Register the Role Login Notifier example within a security domain

The parameters for this example are:

  • fromAddress - The sender email address.
  • msgSubject - The email subject.
  • roleName - The role that a user must have for a message to be sent.

Register the SMTP Notifier Service

Example 9 shows how to register and configure the example SmtpTextNotifierService, which is used by the RoleLoginNotifier to send a text message, by adding the <service> element and attributes to the <service-manager> in security-domain.xml.

<!-- Register services accessible within this security domain -->
<service-manager
className="com.cafesoft.core.service.StandardServiceManager"> ... <!-- Register a text notifier service (used by the RoleLoginNotifier
session-event-handler -->

<service id="email-text-notifier-service" enabled="true" debug="false">
<service-type>examples.service.TextNotifierService</service-type>
<service-class>examples.service.SmtpTextNotifierService</service-class>
<param-list>
<param name="smtp.host" value="localhost"/>
<param name="smtp.to" value="user@domain.com"/>
</param-list>
</service> ... </service-manager>

Example 9 - Register the SMTP Text Notifier Service example within a security domain

The parameters for this example are:

  • stmp.host - The email SMTP server to use.
  • stmp.to - The email to which the message is sent.

UnboundID LDAP User Attribute Managed Session Event Handler

WARNING: Use of this Cams components, which uses the UnboundID LDAP SDK for Java, requires use of Java JRE 1.5 or greater for the Cams policy server.

This session event handler provides functionality similar to the LDAP User Attribute Session Event Handler. However, use of the UnboundID LDAP SDK for Java enables additional features to be configured, such as:

Server Sets - The UnboundID LDAP SDK for Java provides a mechanism that can be used to manage connections across multiple servers for failover and load balancing called ServerSets. The following ServerSet implementations are available:

  • A single server set, which contains a reference to a single server. It is primarily used for cases in which a server set may be needed, but only a single server is to be used.
  • A round robin server set, in which each subsequent connection will be established to the next server in the specified list. If a given server isn't available, then it will be skipped and the server set will move to the next server in the list.
  • A failover server set, in which all attempts to create a connection will be tried against the first server in the list, and will only try the second if the first is unavailable, and only try the third if both the first and second are unavailable, etc.

Connection Pooling - The UnboundID LDAP SDK for Java provides an enhanced connection pooling mechanism. A Cams UnboundID LDAP Connection Pool Service can be configured in security-domain.xml to enable Cams UnboundID components to share LDAP connections. This greatly improves overall system efficiency and reduces the load Cams components place on your LDAP server. For more information on configuring this service, see Cams UnboundID LDAP Connection Pool Service.

Simplified LDAPS - Similar to how browsers negotiate SSL sessions with a web server, UnboundID LDAP SDK for Java proivdes SSL utilities that trust the digital certificate sent by your LDAP server to create an LDAPS connection. You must still configure your LDAP server with a digital certificate to enable LDAPS connections, but do not need to import the digital certificate into the Cams keystore.

Register the Session Event Handler

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

NOTE: When migrating from the deprecated LDAP User Attribute Managed Session Event Handler, we recommend copying the configuration values into the XML snippet provided in Example 10 to ensure that parameters names are correct.

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

 ...

 <session-event-handler
  className="examples.session.UnboundIDLdapUserAttributeManagedSessionEventHandler"
  debug="false">
<param-list> <param name="ldapPoolServiceId" value="unboundid-ldap-connection-pool"/> <!-- Used only if ldapPoolServiceId not supplied <param name="serverSetType" value="SINGLE"/> <param name="connectionHost" value="host.domain.com"/> <param name="connectionPort" value="389"/> <param name="useSSL" value="false"/> <param name="loginDN" value=""/> <param name="loginPassword" value=""/> <param name="connectionTimeout" value="3000"/> <param name="responseTimeout" value="3000"/> --> <param name="baseDN" value="ou=people,dc=domain,dc=com"/> <param name="scope" value="ONE"/> <param name="filter" value="(uid={username})"/> <param name="attributes" value="attr1,attr2,attr3..."/> <param name="nameSpace" value="userinfo"/> <param name="excludeUsers" value="cams-web-agent"/> <param name="includeUsersInRole" value="users,foo,bar"/>
</param-list>
</session-event-handler> ... </session-manager-service>

Example 10 - Register the UnboundID LDAP User Attribute Managed Session Event Handler example within a security domain

The parameters for this example are:

  • ldapPoolServiceId - (optional) The name of the service ID configured in security-domain.xml for a Cams UnboundID LDAP connection pool service. When configured, bound LDAP connections are obtained from and returned to the connection pool service. LDAP connection-related parameters for this component configuration are ignored and can be omitted, including: connectionHost, connectionPort, serverSetType, useSSL, connectionTimeout, and responseTimeout.
    NOTE: You must setup a Cams UnboundID LDAP connection pool service.
  • serverSetType - (optional) Can be:
    SINGLE - (default) Connects to a single server.
    FAILOVER - Attempts to establish connections to servers in the order they are provided. If the first server is unavailable, then it will attempt to connect to the second, then to the third, etc.
    ROUND_ROBIN - Uses a round-robin algorithm to select the server to which the connection should be established. Any number of servers may be included in this server set, and each request will attempt to retrieve a connection to the next server in the list, circling back to the beginning of the list as necessary. If a server is unavailable when an attempt is made to establish a connection to it, then the connection will be established to the next available server in the set.
    WARNING: Except for the connectionHost and connectionPort parameters, all other parameters for this component are shared and must be the same for each LDAP server when more than one are configured in a ServerSet.
  • connectionHost - (conditional) A comma-delimited set of DNS host names or IP addresses used to connect to LDAP. See serverSetType for configuration options to use more than one host. Ignored if a ldapPoolServiceId is provided.
  • connectionPort - (conditional) A comma-delimited set of one or more ports used to connect to LDAP. You must specify a port of the same type (LDAP or LDAPS) for each host in the connectionHost option. Default values are 389 for LDAP and 636 for LDAPS. Ignored if a ldapPoolServiceId is provided.
  • 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. Ignored if a ldapPoolServiceId is provided.
    NOTE:
    You must configure your LDAP server with a digital certificate to enable LDAPS connections, but do not need to import the digital certificate into the Cams keystore.
  • loginDN - (conditional) The user account to bind connections to the LDAP server. Ignored if a ldapPoolServiceId is provided.
  • loginPassword - (conditional) The password for the loginDN. Ignored if a ldapPoolServiceId is provided.
  • connectionTimeout - (optional) The number of milliseconds to wait for a connection to the LDAP server before failing (default=3000). This value provides a way to interrupt an attempted connection. Ignored if a ldapPoolServiceId is provided.
    NOTE: To prevent a Cams web agent authentication request timeout from occurring, make sure the connectionTimeout value is less than the connection.authentication.timeout value found in a Cams web agent's cams-webagent.conf file.
  • responseTimeout - (optional) The number of milliseconds to wait for a response from the server before failing (default=3000). Ignored if a ldapPoolServiceId is provided.
  • baseDN - (required) The base distinguished name to use for LDAP user attribute searches.
  • scope - (required) Specifies the LDAP search scope to use for user attribute searches. Valid values are BASE (search is done only at the base dn tree node), ONE (search is done only at the first child tree node of the base dn) and SUB (search is done at the base dn node and all child nodes).
  • filter - (required) The filter pattern to use to search for a user's attributes. The user name entered by the user at login will be substituted for the value "{username}".
    NOTE: Search filters often contain an ampersand character ("&"). To prevent a search filter ampersand from being interpreted by the Cams XML parser as tag, you must substitute the value "&amp;" for any filter ampersands.
  • attributes - (required) A comma-delimited list of attributes to return.
  • nameSpace - (required) A namespace to use to save user session attributes. If null or an empty string, then the default namespace: "default:namespace" is used.
  • excludeUsers - (optional) A comma-delimited list of user names to exclude from searches. We recommend that you minimally excluded the cams-web-agent user name (or other if you have changed it) to prevent searches from triggering for Cams web agent logins.
  • includeUsersInRoles - (optional) A comma-delimited list of one or more user roles that, if supplied, a user must have at least one for this session event handler to attempt the search for attributes.

Back | Next | Contents