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 are found in the Cams Programmer's Guide.

JDBC User Attribute Managed Session Event Handler
JDBC Last Login Managed Session Event Handler
LDAP User Attribute Managed Session Event Handler
Role Login Notifier Managed Session Event Handler

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, and 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 1 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">
    <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 1 - 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, and 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 2 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">
    <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 2 - 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

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, and 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 3 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">
    <param-list>
      <param name="connectionHost" value="host.company.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=mycompany,dc=com"/>
      <param name="searchScope" value="ONE"/>
      <param name="searchPattern" value="(uid={username})"/>
      <param name="searchAttributes" value="employee-id,country"/>
      <param name="nameSpace" value="userinfo"/>
      <param name="excludeUsers" value="cams-web-agent"/>
    </param-list>
  </session-event-handler>
</session-manager-service>

Example 3 - 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 "&" 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 4 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">
    <param-list>
      <param name="fromAddress" value="user@company.com"/>
      <param name="msgSubject" value="User Login"/>
      <param name="roleName" value="everyone"/>
    </param-list>
  </session-event-handler>
</session-manager-service>

Example 4 - 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 5 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@company.com"/>
    </param-list>
  </service>
</service-manager>

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

Back | Next | Contents