Back | Next | Contents Cams Administrator's Guide

Login Configuration

The Cams authentication services provides a virtual directory where one or more user directories (typically Active Directory, LDAP or an SQL database) can easily be configured for authentication. Cams uses a Pluggable Authentication Module (PAM) framework known as JAAS (Java Authentication and Authorization Service), which permits applications to remain independent from underlying authentication technologies. By using a PAM framework, the Cams JAAS implementation enables the use of new or updated authentication technologies without requiring internal modification to Cams.

This document describes how to configure Cams login modules to authenticate users and assign roles. See also the Login Configuration Tag Reference for information on XML tags used in the login-config.xml file.

NOTE: If a Cams login module does not meet your needs as is, Programming Cams JAAS Login Modules explains how to create a new Cams login module. The source code for all Cams login modules described in this document is included with the documentation download.

Login Configuration

Each Cams security domain defines one or more login configurations in login-config.xml. A login configuration contains configuration values Cams uses to connect user directories to try to authenticate user credentials and then search for group memberships. One or more login modules can be specified by nesting values within <login-config-entry name="http"> open and close tags, as shown in the sample login-config.xml file.

NOTE: Cams login pages contain a required cams_login_config hidden field value that is dynamically populated or statically hard coded, which specifies the security domain-specific <login-config-entry> to use. When dynamically populated, this value is obtained from the cams.loginconfig.entry value defined in cams-webagent.conf for the Cams web agent that populates the login page. The default http value, may be changed, but should be used for most sites.

Within the <login-config-entry> open and close tags, you specify how login modules will be used. The parameters className and flag are required for each <login-module-entry> as show in Example 1. The class name specifies the fully-qualified Java class used to reference a login module. The Java class names for the standard login modules supplied with Cams are:

  • com.cafesoft.cams.auth.login.module.ActiveDirectoryLoginModule
  • com.cafesoft.cams.auth.login.module.DigipassJdbcLoginModule
  • com.cafesoft.cams.auth.login.module.JdbcLoginModule
  • com.cafesoft.cams.auth.login.module.LdapLoginModule
  • com.cafesoft.cams.auth.login.module.RsaSecurIdLoginModule
  • com.cafesoft.cams.auth.login.module.UnboundIDLdapLoginModule
  • com.cafesoft.cams.auth.login.module.X509CertificateLdapLoginModule
  • com.cafesoft.cams.auth.login.module.XmlLoginModule

NOTE: Additional login modules are supplied in the Cams distribution for use with Cams Automatic Enterprise Sign-on (AESO). A few undocumented login modules are also available. For these, see the login module source code comments, available in the documentation download, for configuration instructions.

<login-config-entry name="http">
 <login-module-entry
 className="com.cafesoft.cams.auth.login.module.XmlLoginModule"
 flag="REQUIRED">
 <options>
  <option name="serviceId" value="cams-user-repository"/>
  <option name="debug" value="true"/>
 </options>
</login-module-entry>

Example 1 - Cams login-config.xml example with required <login-module-entry> parameters in red

A <login-config-entry> can have one or more <login-module-entry>. Use of more than one <login-module-entry> is known as stacking. The required flag parameter determines the login module behavioral dependencies, which is especially important when login modules are stacked. The flag can be one of four values:

  • REQUIRED - The login module must be successful for overall authentication to succeed. Any failure results in the return of an error after executing all other login modules on the stack.
  • REQUISITE - The login module must be successful for overall authentication to succeed. Any failure results in the immediate return of an error, no more login modules in the stack are executed. A message reflecting the first failed required or requisite login module is returned.
  • SUFFICIENT - If the login module succeeds, overall authentication succeeds without trying any other login modules in the stack. Failure cases are treated the same as optional.
  • OPTIONAL - A login module failure is ignored and overall authentication success will be a function of other login modules in the stack.

The interaction between flags when stacking can be complicated so you should keep these configurations as simple as possible. Most sites specify a single login module with flag value set to REQUIRED.

Additional <option> values are specific to each login module and described in the sections below. All <option> tags require name and value parameters. For example, all Cams login modules include a debug option to toggle debug on and off. The tag is <option name="debug" value="true"/> with true or false as the value.

NOTE: The Jetty test web server that is included with the Cams policy server provides login module configurators to test login module values and generate the associated XML using your browser. Login module configurators are provided for Active Directory, LDAP and SQL databases. We highly recommend that you use these tools by starting the test Jetty server. Once there, you'll find complete instructions on how to proceed. By default, the Jetty test server is configured to run without modification. However, if you change configuration values for your Cams policy server, you may have to change any associated values found in CAMS_HOME/jetty/etc/cams-webagent.conf.

NOTE: Most sites define one <login-config-entry> is sufficient. However, in addition to stacking login modules within a <login-config-entry>, you can also specify more than one <login-config-entry>, each with a unique name parameter. This can be useful to enable separate user communities to use different login module stacks for authentication within the same security domain.

Login Modules

The login modules included with Cams are:

Active Directory Login Module

NOTE: The Active Directory login module is deprecated with the Cams 3.1 release. We recommend using the UnboundID Active Directory login module, which has feature, performance and stability improvements without comprise of previous LDAP login module functionality. When migrating, copy previous values only into the UnboundID Active Directory login module XML snippet provided in this documentation.

You use this login module to access authentication credentials stored in Microsoft Active Directory. Active Directory, like most directory servers, can be configured to support virtually any schema. The Cams Active Directory login module provides support for the default Active Directory schema as shown in Example 2.

Tree Structure Active Directory Objects

cn=Users,dc=domain,dc=com

dn=user_1_DN

dn=user_2_DN

dn=user_n_DN

dn=group_1_DN

dn=group_2_DN

dn=group_n_DN

Users:

top

person

organizationalPerson

user

Groups:

top

group


Example 2 - Default schema and objects supported by the Active Directory login module

The Active Directory login module expects to find user values stored in specific attributes to successfully perform:

  1. Authentication - The Active Directory user principal names (UPN) such as name@domain.com is required for authentication. The Active Directory login module attempts to bind to Active Directory using the UPN and the password. If successful, the users roles are then queried and saved.

  2. Role Assignment - Once successful authentication is performed, the Cams Active Directory login module then maps roles based upon the configured role attribute. Two methods of Active Directory group lookup are available:

    1. The user's Active Directory memberOf attribute can be configured for simplicity. This attribute contains references to most groups to which the user belongs (excluding the user's primary group and any nested group memberships). Many sites find this to be sufficient. The individual group names are fully qualified distinguished names and are exploded by the Active Directory login module to obtain the group common name, which is found in the left most component (e.g. the group name for distinguished name cn=mygroup,cn=users,dc=domain,dc=com would be mygroup).

    2. Alternately, the user's Active Directory 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. Use of this attribute requires configuration of a Cams Active Directory group name service. 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 Active Directory login module during user authentication.

Example 3 shows the sample entry for the Active Directory login module.

<login-module-entry
className="com.cafesoft.cams.auth.login.module.ActiveDirectoryLoginModule"
flag="REQUIRED">
<options>
<option name="debug" value="false"/>
<option name="host" value="host.domain.com"/>
<option name="port" value="389"/> <option name="useSSL" value="false"/> <option name="connectTimeout" value="3000"/>
<option name="baseDN" value="cn=Users,dc=domain,dc=com"/>
<option name="scope" value="ONE"/>
<option name="filter" value="(&amp;(objectclass=user)(userPrincipalName={username}))"/>
<option name="roleAttr" value="memberOf"/>
</options>
</login-module-entry>

Example 3 - Cams Active Directory login module login-config.xml sample

The Active Directory login module options values are:

  • debug - Enables/disables debugging for the login module.
  • 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). Note that the Active Directory login module may also connect to the Global Catalog (port 3268 by 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 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 a 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 Active Directory host is unavailable due to a network outage.
    NOTE: To prevent a Cams web agent authentication request timeout from occurring, make sure the connectTimeout value is less than the connection.authentication.timeout value found in a Cams web agent's cams-webagent.conf file.
  • baseDN - The base distinguished name for the user search. Always in the format cn=Users,dc=domain,dc=com for Active Directory's default schema, where the values domain and com correspond to the domain configured for the particular directory.
  • scope - Specifies the search scope to use. 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). This value should be set to ONE for most Active Directory sites.
  • filter - The filter to use to search for a user's roles. The UPN 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 a XML tag, you must substitute the value "&amp;" for any ampersands in the filter.
  • roleAttr - The name of the attribute that contains the group names to be mapped to Cams roles. Use memberOf for convenience (returns all user group memberships except the user's primary group and any nested groups). Use tokenGroups to return all groups of which the user is a member. Use of tokenGroups requires configuration of the Cams Active Directory group name service (see the optional serviceId configuration value).
  • domain - (optional) The Active Directory domain to append to the user name for user convenience and to improve accuracy. If this value is present then the Active Directory login module will append "@" followed by the domain value to the user name to compose the UPN before attempting a bind. An alternative approach would be to perform this concatenation in the login page, perhaps using a select element to enable the user to choose the domain.
  • emptyPassword - (optional) Allow use of empty passwords (false by default). Set this value to true to allow use of empty passwords when Active Directory is configured to allow anonymous binds.
  • defaultRoles - (optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.
  • roleRegexPattern - (optional) Limits roles saved in user sessions to those that match a regular expression pattern. This option is useful when a role search returns many user roles that are not referenced in the access control policy for the security domain. For access control polices with a limited number of roles a regular expression separating role names with the pipe ("|") character is suggested.
  • useRoleSearch - (optional) A value of "true" (default) indicates that a role search will be attempted [true|false]. This option is useful for sites configuring Cams for single sign-on (sometimes to a SharePoint or OWA server using Cams Windows Impersonation) and not role-based access control.
  • useDomainInRoleSearch - (optional) A value of "true" (default) indicates that the optionally supplied domain used for authentication will be included in the role search filter's {username} substitution value [true|false]. This option is useful for sites that have migrated from an NT domain to Active Directory, where accounts may not have a userPrincipalName attribute. In such cases, configuring this value to false and using a role search filter that searches on the sAMAccountName attribute instead of the userPrincipalName is suggested.
  • serviceId - (optional) The unique identifier of the Cams Active Directory group name service (configured in security-domain.xml). This configuration value is required if you set the roleAttr configuration value to tokenGroups.
  • addPrivateCredentials - (optional) A flag that indicates whether or not a java.net.PasswordAuthentication object containing the user name and password should be added to the Subject's private credential set on successful authentication. See Cams IIS Web Agent Guide - Windows Impersonation Configuration for additional information.

    WARNING: The values in this object are not encrypted and can be accessed by other Cams policy components and web agent. Administrator must ensure that only trusted components are used and have access!

Digipass JDBC Login Module

You use the Digipass JDBC login module with VASCO Vacman controller software to verify user entered VASCO Digipass authentication credentials with those stored in a relational database such as Oracle, DB2, Microsoft SQL, MySQL, Sybase or any other database with a JDBC driver.

The Digipass JDBC login module supports use of a VASCO recommended SQL database schema (see the Vacman Controller Integration Sample Implementation Guide for more information). Example 4 shows a sample DIGIPASS table (where the DIGIPASS specific data is stored), which can be joined to the Sample User Database USERS table. Alternatively, you could use the DIGIPASS table only by changing the USER_ID_FK field into a varchar(20) primary key as shown in the VASCO documentation. Other examples found in this section use the Sample User Database schema with the table in Example 4.

DIGIPASS
USER_ID_FK int(11)

SERIAL_NUMBER varchar(22)
MODEL_NUMBER varchar(5)
MODE char(2)
DATA varchar(248)

Example 4 - Sample User Database USERS table joined with a sample DIGIPASS table

NOTE: Cafésoft does not supply utilities to load Digipass data into your database. You should contact VASCO if you need help loading Digipass data and related values.

The Digipass JDBC login module uses the following work flow for Digipass authentication requests:

  1. Query a user's Digipass serial number, authentication mode and data blob.
  2. Determine if the authentication mode is response only (RO) or challenge/response (CR).
  3. If RO, use the one-time password to try to authenticate the user.
  4. If CR, and there is NO challenge, generate a challenge.

    NOTE: The Cams architecture does not support returning a challenge generated by the Digipass JDBC login module to the user. The challenge is written to the Cams policy server system console and, if debug is enabled, to a log. Please contact Cafésoft if challenge/response support is required.

  5. If CR, and there is a challenge, use it and the password to try to authenticate the user.
  6. Save the Digipass data blob to the database to preserve authentication request state.
Configuring the VASCO Vacman Controller for use with Cams

You must configure Cams to use the VASCO Vacman controller libraries, which perform the authentication check and update the Digipass data blob. The Cams policy server and the Cams Digipass JDBC login module have been tested and verified to work with Vacman controller version 3.5.0. Because Cafésoft is not licensed to distribute VASCO Digipass libraries you must obtain them from VASCO along with your Digipass tokens and software. To configure the libraries:

  1. Copy the Vacman Controller aal2wrap.jar Java API wrapper jar file into CAMS_HOME/lib. You'll find this file in the java directory of the Windows or Linux RPM installations described in steps 2 and 3.

  2. Windows only:

    The Vacman controller is packaged with a Windows installer in a file such as Vc3507w.exe, which will install the libraries aal2sdk.dll and aal2sdk.lib in:

    C:\Program Files\VASCO\VACMAN Controller for Windows 3.5.0\win32\bin

    You must include this directory in the Windows system path on the Cams policy server system, or copy the aal2sdk.dll and aal2sdk.lib library files into a directory already in the system path.

  3. Linux only:

    The Vacman controller is packaged as an RPM in a file such as aal2sdk-3.5.0-0.i386.rpm, which will install the libraries libaal2sdk-3.5.0.so and libaal2sdk.so in:

    /opt/vasco/VACMAN_Controller-3.5/lib/

    You must include this directory in the Linux system path for the account that runs the Cams policy server or copy the libaal2sdk-3.5.0.so and libaal2sdk.so library files into a directory already in the account's path.
Configuring the Digipass JDBC login module options

Example 5 shows a Digipass JDBC login module configuration using the VASCO Digipass database schema as described in Sample User Database and a JDBC connection pool.

<Login-module-entry
className="com.cafesoft.cams.auth.login.module.DigipassJdbcLoginModule"
flag="REQUIRED">
<options>
<option name="debug" value="false"/>
<option name="jdbcDriver" value="org.apache.commons.dbcp.PoolingDriver"/>
<option name="jdbcUrl" value="jdbc:apache:commons:dbcp:example-jdbc-pool"/>
<option name="jdbcUsername" value=""/>
<option name="jdbcPassword" value=""/> <option name="getDigipassPreparedStatement" value="select SERIAL_NUMBER, MODE, DATA from USERS join DIGIPASS on USERS.USER_ID = DIGIPASS.USER_ID_FK where USERS.USER_NAME = ?"/>
<option name="saveDigipassPreparedStatement" value="update DIGIPASS set DATA = ? where SERIAL_NUMBER = ?"/>
<option name="digipassDataColumn" value="DATA"/>
<option name="serialNumberColumn" value="SERIAL_NUMBER"/>
<option name="authenticationModeColumn" value="MODE"/>
<option name="responseLength" value="11"/>
<option name="kernelParameters" value="100,24,0,0,1,0,0,0,0,6,0,100,0,0,0x7FFFFF,0,0,0,0"/>
<option name="rolePreparedStatement" value="select ROLES.ROLE_NAME from USERS, ROLES, USER_ROLES where USERS.USER_NAME = ? and USERS.USER_ID = USER_ROLES.USER_ID_FK and USER_ROLES.ROLE_ID_FK = ROLES.ROLE_ID"/>
<option name="roleColumn" value="ROLE_NAME"/>
</options>
</login-module-entry>

Example 5- Digipass JDBC login module configuration for the sample user database

The Digipass JDBC login module option values are (required unless otherwise specified):

  • debug - Enables/disables debugging for the login module.
  • jdbcDriver - The fully qualified Java class name for your database's JDBC driver.

    NOTE: Configuring the Digipass JDBC login module to handle database connections directly requires opening and closing a database connection at least twice for each Digipass authentication request. Because this is an expensive use of resources, we recommend that you configure JDBC database connection pooling for production environments.

  • jdbcUrl - The JDBC URL used to access the database (see the JDBC driver documentation).
  • jdbcUsername - (optional) The user name to access the database.
  • jdbcPassword - (optional) The password to access the database.
  • getDigipassPreparedStatement - The SQL prepared statement used to select the user's Digipass serial number, mode and data blob from the database. For example: "select SERIAL_NUMBER, MODE, DATA from USERS join DIGIPASS on USERS.USER_ID = DIGIPASS.USER_ID_FK where USERS.USER_NAME = ?". The user name entered by the user at login will be substituted for the "?". Any valid query for your database should work, including use of stored procedures.
  • saveDigipassPreparedStatement - The SQL prepared statement used to save the user's Digipass data blob to the database. For example: "update DIGIPASS set DATA = ? where SERIAL_NUMBER = ?". The Digipass blob and serial number will be substituted for the first and second "?" respectively. Any valid query for your database should work, including use of stored procedures.
  • digipassDataColumn - The database column name for the Digipass data blob.
  • serialNumberColumn - The database column name for the Digipass serial number.
  • authenticationModeColumn - The database column name for the Digipass authentication mode. Possible values include:
    • RO - Response Only, used for Digipass one-time passwords.
    • CR - Challenge/Response, see the note in work flow section above.
  • responseLength - The expected total length of the response after a challenge (4 for pre-pended challenge plus the length of the dynamic response).
  • kernelParameters - The comma-delimited Vacman controller kernel parameters to use as integers or hex values, for example: "100,24,0,0,1,0,0,0,0,6,0,100,0,0,0x7FFFFF,0,0,0,0". Please refer to the Vacman Controller documentation for information on how to tune these values.
  • rolePreparedStatement - The SQL prepared statement used to select the user's groups and/or roles from the database. For example: "select ROLES.ROLE_NAME from USERS, ROLES, USER_ROLES where USERS.USER_NAME = ? and USERS.USER_ID = USER_ROLES.USER_ID_FK and USER_ROLES.ROLE_ID_FK = ROLES.ROLE_ID". The user name entered by the user at login will be substituted for the "?". Any valid query for your database should work, including use of stored procedures.
  • roleColumn - The table column name that will be returned with the result set from the rolePreparedStatement where the user's groups and/or roles are found. All values returned will be assigned as roles to the user.
  • accountExpiredPreparedStatement - (optional) The SQL prepared statement to determine if a user account has expired or been disabled. The result set must return a value of "1" if the account has expired, or "0" if it has not. For example: "select count(*) from USERS where USER_NAME = ? and ACCOUNT_DISABLED > 0". The user name entered by the user at login will be substituted for the "?". Any valid query for your database should work, including use of stored procedures. This prepared statement is executed conditionally after the password has been validated.
  • defaultRoles - (optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.

NOTE: You must obtain and install the JDBC driver supplied by your database vendor. To use any JDBC driver with Cams, copy the driver's jar file(s) into the CAMS_HOME/lib directory. For example, if you want to use MySQL with the standard J2SDK installation, you would copy mysql-connector-java-3.0.15-ga-bin.jar to CAMS_HOME/lib. See your database vendor documentation for more information.

JDBC Login Module

You use the JDBC login module to access authentication credentials stored in relational databases such as Oracle, DB2, Microsoft SQL, MySQL, Sybase or any other database with a JDBC driver. The JDBC login module is flexible to support a wide range of database schemas without modification. Example 6 shows a JDBC login module configuration using the Sample User Database schema and values with the open source HSQLDB relational database.

NOTE: Though valid and recommended for initial testing, configuring a JDBC login module to handle database connections as show in Example 6 requires opening and closing a database connection for each authentication request. Because this is an expensive use of resources, we recommend that you configure JDBC database connection pooling for production environments.

<Login-module-entry
  className="com.cafesoft.cams.auth.login.module.JdbcLoginModule"
  flag="REQUIRED">
 <options>
  <option name="debug"          value="false"/>
  <option name="jdbcDriver"     value="org.hsqldb.jdbcDriver"/>
  <option name="jdbcUrl"        value="jdbc:hsqldb:hsql://localhost/"/>
  <option name="jdbcUsername"   value="sa"/>
  <option name="jdbcPassword"   value=""/>
  <option name="userPreparedStatement"
         value="select PASSWORD from USERS where USER_NAME = ?"/>
  <option name="passwordColumn" value="PASSWORD"/>
  <option name="rolePreparedStatement"
         value="select ROLES.ROLE_NAME from USERS, ROLES, USER_ROLES
                where USERS.USER_NAME = ?
                and USERS.USER_ID = USER_ROLES.USER_ID_FK
                and USER_ROLES.ROLE_ID_FK = ROLES.ROLE_ID"/>
  <option name="roleColumn"     value="ROLE_NAME"/>
 </options>
</login-module-entry> 

Example 6 - JDBC login module configuration for the sample user database

The JDBC login module option values are (required unless otherwise specified):

  • debug - Enables/disables debugging for the login module.
  • jdbcDriver - The fully qualified Java class name for your database's JDBC driver.

    NOTE: For greatest efficiency and performance, we strongly recommend that you configure JDBC connection pooling in production environments.

  • jdbcUrl - The JDBC URL used to access the database (see the JDBC driver documentation).
  • jdbcUsername - (optional) The user name to access the database.
  • jdbcPassword - (optional) The password to access the database.
  • userPreparedStatement - The SQL prepared statement used to select the user's password from the database. For example: "select PASSWORD from USERS where USER_NAME = ?". The user name entered by the user at login will be substituted for the "?". Any valid query for your database should work, including use of stored procedures.
  • passwordColumn - The table column name that will be returned with the result set from the userPreparedStatement where the user's password is found.
  • accountExpiredPreparedStatement - (optional) The SQL prepared statement to determine if a user account has expired. The result set must return a value of "1" if the account has expired, or "0" if it has not. For example: "select count(*) from USERS where USER_NAME = ? and ACCOUNT_DISABLED > 0". The user name entered by the user at login will be substituted for the "?". Any valid query for your database should work, including use of stored procedures. This prepared statement is executed conditionally after the password has been validated.
  • passwordExpiredPreparedStatement - (optional) The SQL prepared statement to determine if a user password has expired. The result set must return a value of "1" if the password has expired, or "0" if it has not. For example: "select count(*) from USERS where USER_NAME = ? and DATEDIFF(CURRENT_TIMESTAMP, PASSWORD_LAST_SET) > 90". The user name entered by the user at login will be substituted for the "?". Any valid query for your database should work, including use of stored procedures. This prepared statement is executed conditionally after the password has been validated.
  • rolePreparedStatement - The SQL prepared statement used to select the user's groups and/or roles from the database. For example: "select ROLES.ROLE_NAME from USERS, ROLES, USER_ROLES where USERS.USER_NAME = ? and USERS.USER_ID = USER_ROLES.USER_ID_FK and USER_ROLES.ROLE_ID_FK = ROLES.ROLE_ID". The user name entered by the user at login will be substituted for the "?". Any valid query for your database should work, including use of stored procedures.
  • roleColumn - The table column name that will be returned with the result set from the rolePreparedStatement where the user's groups and/or roles are found. All values returned will be assigned as roles to the user.
  • emptyPassword - (optional) Allow use of empty passwords (false by default). Set this value to true to allow anonymous login.
  • defaultRoles - (optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.
  • addPrivateCredentials - (optional) A flag that indicates whether or not a java.net.PasswordAuthentication object containing the user name and password should be added to the Subject's private credential set on successful authentication. See Cams IIS Web Agent Guide - Windows Impersonation Configuration for additional information. WARNING: The values in this object are not encrypted and can be accessed by other Cams policy components and web agent. Administrator must ensure that only trusted components are used and have access!
  • charEncoding - (optional) the character set encoding used to convert password characters to bytes when used for digest string comparisons. If not specified, then default platform character encoding is used. NOTE: if user passwords are stored as digest strings, the same character encoding should be used in this login module as used when the password digest was originally created.

    The JDBC login module supports password digests using UNIX Crypt, MD5, and SHA, SMD5 and SSHA algorithms. The algorithm is specified within curly brackets in a label that precedes a base 64 encoding of the hashed password (e.g. {CRYPT}, {MD5}, {SHA}, {SMD5}, {SSHA}), which may also include salt bytes.

NOTE: You must obtain and install the JDBC driver supplied by your database vendor. To use any JDBC driver with Cams, copy the driver's jar file(s) into the CAMS_HOME/lib directory. For example, if you want to use MySQL with the standard J2SDK installation, you would copy mysql-connector-java-3.0.15-ga-bin.jar to CAMS_HOME/lib. See your database vendor documentation for more information.

Using JDBC Connection Pooling

JDBC connection pooling is the recommended way to configure authentication with a relational database in production environments. To use JDBC connection pooling from the JDBC login module, you must:

  1. Setup a Cams JDBC connection pool service
  2. Configure the JDBC login module to use the Jakarta/Commons JDBC Connection pooling driver as shown in Example 7
<login-module-entry
  className="com.cafesoft.cams.auth.login.module.JdbcLoginModule"
  flag="REQUIRED">
 <options>
  <option name="debug"          value="false"/>
  <option name="jdbcDriver"     value="org.apache.commons.dbcp.PoolingDriver"/>
  <option name="jdbcUrl"        value="jdbc:apache:commons:dbcp:example-jdbc-pool"/>
  <option name="userPreparedStatement"
         value="select PASSWORD from USERS where USER_NAME = ?"/>
  <option name="passwordColumn" value="PASSWORD"/>
  <option name="rolePreparedStatement"
         value="select ROLES.ROLE_NAME from USERS, ROLES, USER_ROLES
                where USERS.USER_NAME = ?
                and USERS.USER_ID = USER_ROLES.USER_ID_FK
                and USER_ROLES.ROLE_ID_FK = ROLES.ROLE_ID"/>
  <option name="roleColumn"     value="ROLE_NAME"/>
 </options>
</login-module-entry>

Example 7 - Using pooled JDBC connections with the JDBC login module

The JDBC login module option values are configured as shown in Example 6 with the following differences:

  1. jdbcDriver - use org.apache.commons.dbcp.PoolingDriver.
  2. jdbcUrl - must start with jdbc:apache:commons:dbcp: and must end with the poolName as configured in the JDBC connection pooling service in security-domain.xml.
  3. jdbcUsername and jdbcPassword - You do not need to supply these options as database authentication credentials are supplied in the JDBC connection pooling service configuration.

LDAP Login Module

NOTE: The LDAP login module is deprecated with the Cams 3.1 release. We recommend using the UnboundID LDAP login module, which has feature, performance and stability improvements without comprise of functionality.

You use the LDAP login module to access authentication credentials store in the Sun ONE Directory Server, Red Hat Directory Server, OpenLDAP and any other LDAPv3 compliant user directory. LDAP directory schema will vary from site to site. This login module is flexible to support many variations of X.500 and DNS style schemas similar to those shown in Example 8.

Tree Structure LDAP Objects

dc=domain,dc=com

ou=people

dn=user_1_DN

dn=user_2_DN

dn=user_n_DN

ou=groups

dn=group_1_DN

dn=group_2_DN

dn=group_n_DN

Users:

top

person

organizationalPerson

inetOrgPerson

Groups:

top

groupOfUniqueName


Example 8 - Sample DNS style LDAP schema and objects supported by the LDAP login module

The LDAP login module expects a schema similar to the one specified in Example 8 to successfully perform:

  1. Authentication - The LDAP login module substitutes the user name that the user enters when prompted for authentication against the {username} parameter in curly brackets in the userDN (distinguished name) option value (see below). The Cams authentication service then attempts to connect and bind to the LDAP server with the user DN and password. If the bind is successful, then Cams authentication succeeds. For example, if you enter johnsmith for the user name and the userDN option value is:

    uid={username},ou=people,dc=domain,dc=com

    then Cams will attempt to bind with user DN:

    uid=johnsmith,ou=people,dc=domain,dc=com

  2. Role Assignment - After authentication succeeds the Cams LDAP login module performs a role search to retrieve and assign the user roles. Sites often use group attributes for role assignments (though they really are different). You must specify the base distinguished name, search scope, search filter and role attribute name that will be used to find the roles.

    NOTE: If your LDAP server does not provide groups or roles, then it is valid to specify a role filter that succeeds but returns nothing. A better option would be to alter the LDAP login module code to not perform the role search. See Programming Cams JAAS Login Modules.

Your LDAP server may use a schema different from the one specified above. Also, your LDAP server's access control settings may effect integration with Cams. For example, for the LDAP login module to return role information successfully, the LDAP server access control policy must allow a bound user to search the group tree to obtain role membership data.

The recommended approach is to use the LDAP login module configurator, which is included with the Cams test Jetty web server. This tool enables you to quickly configure and test options and then generate XML for insertion into login-module.xml and testing with the Cams policy server. For example, to find roles, use searches such as:

baseDN: ou=groups,dc=domain,dc=com
filter: (uniqueMember=uid=myUID,dc=domain,dc=com)
scope: one
attributes: cn

Example 9 shows the sample entry for the LDAP login module.

<login-module-entry
 className="com.cafesoft.cams.auth.login.module.LdapLoginModule"
 flag="REQUIRED">
 <options>
  <option name="debug"          value="false"/>
  <option name="host"           value="host.domain.com"/>
<option name="port" value="389"/> <option name="useSSL" value="false"/> <option name="connectTimeout" value="3000"/> <option name="userDN" value="uid={username},ou=people,dc=domain,dc=com"/> <option name="roleBaseDN" value="ou=groups,dc=domain,dc=com"/> <option name="roleScope" value="ONE"/> <option name="roleFilter" value="(uniqueMember=uid={username},ou=people,dc=domain,dc=com)"/> <option name="roleAttrName" value="cn"/> </options> </login-module-entry>

Example 9 - Cams LDAP login module login-config.xml sample

The required LDAP login module options values are:

  • debug - Enables/disables debugging for the login module.
  • host - The LDAP server host name or IP address.
  • port - The LDAP server port number.
  • 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.
  • 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 (and may cause Cams web agents to timeout while waiting for an authentication request).
    NOTE: To prevent a Cams web agent authentication request timeout from occurring, make sure the connectTimeout value is less than the connection.authentication.timeout value found in a Cams web agent's cams-webagent.conf file.
  • userDN - The distinguished name pattern for a user. The user name entered by the user at login will be substituted for the value "{username}". The LDAP login module will not successfully find users in schemas that use a distinguished name that does not use the user name to distinguish users.
  • roleBaseDN - The base distinguished name to use for your LDAP schema role searches.
  • roleScope - 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).
  • roleAttrName - The name of the attribute used to store the role names (usually only one name is supplied but this can be a comma-delimited list).
  • roleFilter - The filter to use to search for a users roles. 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.
  • emptyPassword - (optional) Allow use of empty passwords (false by default). Set this value to true to allow anonymous login.
  • defaultRoles - (optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.
  • roleRegexPattern - (optional) Limits roles saved in user sessions to those that match a regular expression pattern. This option is useful when a role search returns many user roles that are not referenced in the access control policy for the security domain. For access control polices with a limited number of roles a regular expression separating role names with the pipe ("|") character is suggested.

RSA SecurID Login Module

The RSA SecurID login module provides authentication of users with RSA standard cards, key fobs, or disconnected SID800 tokens and requires:

  • RSA SecurID Authentication Manager version 5.1 or later
  • Customer access to the RSA SecurID Authentication Agent API Java classes.

NOTE: Cafésoft is not licensed to distribute the RSA Authentication Agent API classes. You must download the from RSA and install the classes as described later in this section.

The following steps are required to install and configure this login module:

    1. Register the Cams RSA SecurID Login Module in login-config.xml
    2. Install the RSA Authentication Agent API version 5.0.3 classes (or compatible)
    3. Register the Cams policy server host as an RSA SecurID Agent Host
    4. Generate/Install the RSA Agent Host node secret file (securid)
    5. Generate/Install the RSA Agent Host configuration record file (sdconf.rec)
    6. Create/Edit the RSA Agent Host configuration options file (sdopts.rec)
    7. Create/Edit the RSA SecurID API configuration file (rsa_api.properties)
    8. Restart the Cams Policy Server and test RSA SecurID authentication
Step 1 - Register the Cams RSA SecurID login module in login-config.xml

Edit the desired security domain login-config.xml and add a login-module-entry as shown in Example 10.

NOTE: The login-config.xml file that ships with the Cams policy server system security domain includes a this entry. Simply uncomment the associated XML elements to use it.

<!-- RSA SecurID login module. -->
<login-module-entry
className="com.cafesoft.cams.auth.login.module.RsaSecurIdLoginModule"
flag="REQUIRED">
<options>
<option name="debug" value="false"/>
<option name="configPath" value="${cams.security-domain.home}/rsa_api.properties"/>
<option name="defaultRoles" value="SECURID"/>
</options>
</login-module-entry>

Example 10 - Cams RSA SecurID login module configuration in login-config.xml

The RSA SecurID login module options are:

  • debug - Enables/disables debugging for the login module.
  • configPath - The absolute file path to the RSA SecurID API configuration file. This file is named 'rsa_api.properties' in the RSA SecurID Authentication API documentation. The instructions in section assume that you will install this file in the security domain home directory. Example 10 shows use of Cams variable ${cams.security-domain.home} to construct the file path.
  • defaultRoles - (optional) A comma-delimited list of roles to be assigned to each successfully authenticated user. Example 10 shows assignment of the SECURID role.
  • username_cb_name - (optional) By default, a username callback is expected. If the login form uses a different name for the field, then optionally configure it. For example, for cams_cb_uid use:

    <option name="username_cb_name" value="uid"/>

  • password_cb_name - (optional) By default, a password callback is expected. If the login form uses a different name for the field, then optionally configure it. For example, for cams_cb_code use:

    <option name="password_cb_name" value="code"/>
Step 2 - Install the RSA Authentication Agent API version 5.0.3 classes (or compatible)

The RSA Authentication Agent API 5.0.3 for Java (or compatible) can be downloaded from the RSA SecurCare Online site at https://knowledge.rsasecurity.com. The download file (named authapi-5.0.3.159.zip or similar) contains many files, including documentation, example code and the compiled Java classes for the API.

Extract the files to a temporary directory, then find the file named authapi.jar and copy it to the Cams policy server library directory at CAMS_HOME/lib.

NOTE: Copy only the authapi.jar file to the CAMS_HOME/lib directory. Do not copy the log4J.jar file that comes witht the RSA Authentication Agent API as the Cams policy server already includes these classes.

Step 3 - Register the Cams Policy Server host as an RSA SecurID Agent Host

The host for each Cams policy server must be registered with the the RSA Authentication Manager as an Agent Host. This enables use of the RSA Authentication API (used by the Cams RSA SecurId login module) as a SecurID authentication agent from each host on which a Cams policy server is installed. The complete instructions for this task are not included here as they vary slightly from one version of the RSA Authentication Manager to another, but you'll need to use the administration GUI and menu item "Agent Host -> Add Agent Host" (if not already added) or "Agent Host -> Edit Agent Host" (if already added).

Figure 1 shows sample settings using version 6.1 of the RSA Authentication Manager GUI.

Figure 1 - Adding the Cams Policy Server host as an RSA Agent Host using the RSA Authentication Manager

Step 4 - Generate/Install the RSA Agent Host node secret file (securid)

The RSA Agent Host node secret file contains secret keys that are used for encryption of traffic between the RSA agent host and the RSA Authentication Manager. In addition, the node secret file has two forms: a binary form usually named nodesecret.rec generated by the RSA Authentication Manager GUI and a clear text from usually named securid. You'll need the securid file for use with the Cams RSA SecurID login module. To create this file:

    1. Select RSA Authentication Manager menu item "Agent Host -> Edit Agent Host".
    2. Select the Create Node Secret File... button and follow directions to create the nodesecret.rec file.
    3. Use the RSA Authentication Manager agent_nsload command utility as described in the RSA Administrator's Guide to load the nodesecret.rec file into the Authentication Manager database. For example:

      agent_nsload -f nodesecret.rec -p mypassword

    4. Find the associated securid file that was generated by the agent_nsload utility. On Windows systems, this file will usually be stored at %SYSTEMROOT%\system32\securid and in the ACEDATA directory on UNIX systems. Once you've found the securid file, copy it into your Cams policy server security domain home directory. For example:

      CAMS_HOME/conf/domains/system/securid
Step 5 - Generate/Install the RSA Agent Host configuration record file (sdconf.rec)

Every device defined as an RSA Authentication Agent Host has an RSA Authentication Manager configuration file (sdconf.rec) in the %SYSTEMROOT%\system32 directory (on Windows machines) or the ACEDATA directory (on UNIX machines). RSA Authentication Manager creates the initial configuration file during the installation of the Primary server and stores it in the ACEDATA directory on the Primary.

To generate the configuration file for an Agent Host, open the Database Administration application (described in Chapter 2, Using RSA Authentication Manager Administration Applications), and click "Agent Host > Generate Configuration Files". Click Help for details and instructions. Copy the resulting sdconf.rec file into your Cams policy server security domain home directory. For example:

CAMS_HOME/conf/domains/system/sdconf.rec

Step 6 - Create/Edit the RSA Agent Host configuration options file (sdopts.rec)

The RSA Agent Host configuration options file is essentially used to specify the IP addresses and load balancing settings for client use of RSA Authentication Manager server(s) and the client IP address of your Agent Host (in cases where the agent host system has multiple IP addresses assigned).

Using a text editor, create a file at CAMS_HOME/conf/domains/system/sdopts.rec and add configuration options as described in the RSA Authentication Manager API documentation. Example 11 shows sample entries created for an environment in which an RSA Authentication Manager server is installed at 192.168.0.132 and a Cams policy server is installed at 192.168.0.130. You'll need to customize this value based on your system topology.

;
; The RSA Authentication Manager IP address and load balancing factor
;
USESERVER=192.168.0.132, 10
; ; The RSA Agent Host IP address (Cams Policy Server IP address)
;
CLIENT_IP=192.168.0.130

Example 11 - Example RSA Agent Host configuration options file (sdopts.rec)

Step 7 - Create/Edit the RSA SecurID API configuration file (rsa_api.properties)

The RSA SecurID API requires a configuration file, usually named rsa_api.properties. This file references all the other files and sets the many possible logging options. This is the file that is referenced by the Cams RSA SecurId login module configPath option.

Using a text editor, create a file at CAMS_HOME/conf/domains/system/rsa_api.properties and copy/paste the text from Example 12 into it. Edit the bold/red values so that the RSA_AGENT_HOST value is the IP address and all file paths are adjusted for your Cams policy server installation.

WARNING: All file paths referenced by this file must be absolute, not relative.

#	RSA Authentication API Properties
#	Override Host IP Address
RSA_AGENT_HOST=192.168.0.130

#	Interval in seconds between which configuration is refreshed.
RSA_CONFIG_READ_INTERVAL=600

#	[This section is for Data Repository configuration.]
#	Type of the Server configuration.
SDCONF_TYPE=FILE
#	Path of the Server configuration.
SDCONF_LOC=c:/cams-policy-server-3.0.2/conf/domains/system/sdconf.rec
#	Type of the Server statuses.
SDSTATUS_TYPE=FILE
#	Path of the Server statuses.
SDSTATUS_LOC=c:/cams-policy-server-3.0.2/logs/JAStatus.1
#	Type of the Server options.
SDOPTS_TYPE=FILE
#	Path of the Server options.
SDOPTS_LOC=c:/cams-policy-server-3.0.2/conf/domains/system/sdopts.rec
#	Type of the Node Secret.
SDNDSCRT_TYPE=FILE
#	Path of the Node Secret.
SDNDSCRT_LOC=c:/cams-policy-server-3.0.2/conf/domains/system/securid

#	[This section is for event logger.]
#	Logs event messages to the console.
RSA_LOG_TO_CONSOLE=NO
#	Logs event messages to a file.
RSA_LOG_TO_FILE=YES
#	Name of the log file.
RSA_LOG_FILE=c:/cams-policy-server-3.0.2/logs/rsa_api.log
#	Minimum severity level allowed to log.
RSA_LOG_LEVEL=INFO

#	[This section is for debugger.]
#	Enables debug tracing.
RSA_ENABLE_DEBUG=NO
#	Sends tracing to the console.
RSA_DEBUG_TO_CONSOLE=NO
#	Sends tracing to a file.
RSA_DEBUG_TO_FILE=NO
#	Name of the trace file.
RSA_DEBUG_FILE=c:/cams-policy-server-3.0.2/logs/rsa_api_debug.log
#	Allows function entry tracing.
RSA_DEBUG_ENTRY=NO
#	Allows function exit tracing.
RSA_DEBUG_EXIT=NO
#	Allows control flow tracing.
RSA_DEBUG_FLOW=NO
#	Allows regular tracing.
RSA_DEBUG_NORMAL=NO
#	Traces the location.
RSA_DEBUG_LOCATION=NO

Example 12 - Example RSA Authentication API for Java configuration file (rsa_api.properties)

Step 8 - Restart the Cams policy server and test RSA SecurID Authentication

After restarting the Cams policy server, you can use the Jetty test server included with Cams to test RSA SecurID authentication. See Installation Instructions Step 6 for more details.

Once you have the Cams test page displayed, enter your user name in the Username field and your SecurID PIN+tokencode in the Password field, then click the Login button. If login succeeds, you should see Cams HTTP request headers displayed showing your user name and the default SECURID role.

NOTE: The RSA SecurID login module does not support prompting for a NEW PIN, so you'll want to be sure that your users already have PINs assigned via other means.

If authentication fails, make sure your user name and PIN+tokencode work properly using a different means. Other option include:

    1. Enabling DEBUG messages in the RSA SecurId login module and examining your Cams policy server's system-trace.log.
    2. Enabling the many DEBUG options in the rsa_api.properties file and looking in rsa_api_debug.log.

Unbound ID Active Directory Login Module

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.

You use the UnboundID Active Directory login module to access authentication credentials stored in Active Directory. This login module improves upon the Active Directory login module using the UnboundID LDAP SDK for Java for implementation, which 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 Server Sets. The following Server Set 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 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.

Active Directory, like most directory servers, can be configured to support virtually any schema. The Cams Active Directory login module provides support for the default Active Directory schema as shown in Example 13.

Tree Structure Active Directory Objects

cn=Users,dc=domain,dc=com

dn=user_1_DN

dn=user_2_DN

dn=user_n_DN

dn=group_1_DN

dn=group_2_DN

dn=group_n_DN

Users:

top

person

organizationalPerson

user

Groups:

top

group


Example 13 - Default schema and objects supported by the Active Directory login module

The Active Directory login module expects to find user values stored in specific attributes to successfully perform:

  1. Authentication - The Active Directory user principal names (UPN) such as name@domain.com is required for authentication. The Active Directory login module attempts to bind to Active Directory using the UPN and the password. If successful, the users roles are then queried and saved.

  2. Role Assignment - Once successful authentication is performed, the Cams Active Directory login module then maps roles based upon the configured role attribute. Two methods of Active Directory group lookup are available:

    1. The user's Active Directory memberOf attribute can be configured for simplicity. This attribute contains references to most groups to which the user belongs (excluding the user's primary group and any nested group memberships). Many sites find this to be sufficient. The individual group names are fully qualified distinguished names and are exploded by the Active Directory login module to obtain the group common name, which is found in the left most component (e.g. the group name for distinguished name cn=mygroup,cn=users,dc=domain,dc=com would be mygroup).

    2. Alternately, the user's Active Directory 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. Use of this attribute requires configuration of a Cams Active Directory group name service. The tokenGroups attributes are returned as Active Directory security identifiers (SIDs), which must be resolved to their common names. For performance reasons, the Cams UnboundID 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 Active Directory login module during user authentication.

Example 14 shows the sample entry for the UnboundID Active Directory login module.

NOTE: When migrating from the deprecated Active Directory login module, we recommend copying previous configuration values into the XML snippet provided in Example 14 to ensure that parameters names are correct.

<login-module-entry
className="com.cafesoft.cams.auth.login.module.UnboundIDActiveDirectoryLoginModule"
flag="REQUIRED">
<options> <option name="debug" value="false"/>
<option name="ldapPoolServiceId" value="unboundid-ldap-connection-pool"/> <!-- Used only if ldapPoolServiceId not supplied <option name="serverSetType" value="SINGLE"/> <option name="connectionHost" value="host.domain.com"/>
<option name="connectionPort" value="389"/> <option name="useSSL" value="false"/> <option name="connectionTimeout" value="3000"/> <option name="responseTimeout" value="3000"/> --> <option name="baseDN" value="cn=Users,dc=domain,dc=com"/> <option name="scope" value="ONE"/> <option name="filter" value="(&amp;(objectclass=user)(userPrincipalName={username}))"/> <option name="attribute" value="memberOf"/> <option name="groupNameServiceId" value="unboundid-active-directory-group-name"/> <option name="domain" value="domain.com"/> <option name="useDomainInRoleSearch" value="true"/> <!-- Optional <option name="emptyPassword" value="false"/> <option name="defaultRoles" value="role1,role2,role3..."/> <option name="useRoleSearch" value="true"/> <option name="roleRegexPattern" value="role1|role2|role3..."/> <option name="addPrivateCredentials" value="false"/> --> </options>
</login-module-entry>

Example 14 - Cams UnboundID Active Directory login module login-config.xml sample

The UnboundID Active Directory login module options values are:

  • debug - Enables/disables debugging for the login module.
  • ldapPoolServiceId - (optional) The name of the service ID configured in security-domain.xml for an UnboundID LDAP connection pooling service. When configured, the connection pooling service uses the services LDAP connection parameters and ignores any configured for this login module. When a serviceId is used, the following LDAP connection-related options are not needed for this login module configuration: 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 login module are shared and must be the same for each 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 serviceId 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.
    NOTE:
    You must configure your Active Directory server with a digital certificate to enable LDAPS connections, but do not need to import the digital certificate into the Cams keystore.
  • 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.
    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)
  • baseDN - The base distinguished name for the user search. Always in the format cn=Users,dc=domain,dc=com for Active Directory's default schema, where the values domain and com correspond to the domain configured for the particular directory.
  • scope - 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). This value should be set to ONE for most Active Directory sites.
  • filter - The filter to use to search for a user's roles. The user name will be substituted for the value "{username}". If the optional domain value is supplied, the domain will be appended to the user name.
    NOTE: Search filters often contain an ampersand character ("&"). To prevent a search filter ampersand from being interpreted by the Cams XML parser as a XML tag, you must substitute the value "&amp;" for any ampersands in the filter.
  • attribute - The name of the attribute that contains the group names to be mapped to Cams roles. Use memberOf for convenience (returns all user group memberships except the user's primary group and any nested groups). Use tokenGroups to return all groups of which the user is a member. Use of tokenGroups requires configuration of the Cams UnboundID Active Directory group name service (see the optional groupNameServiceId configuration value).
  • groupNameServiceId - (optional) The unique identifier of the Cams UnboundID Active Directory group name service (configured in security-domain.xml). This configuration value is required if you set the attribute configuration value to tokenGroups.
  • domain - (optional) The Active Directory domain to append to the user name for user convenience and accuracy. If this value is present the Active Directory login module will append "@" followed by the domain value to the user name to compose the UPN before attempting a bind. An alternative approach would be to perform this concatenation in the login page, perhaps using a select element to enable the user to choose the domain.
  • roleRegexPattern - (optional) Limits roles saved in user sessions to those that match a regular expression pattern. This option is useful when a role search returns many user roles that are not referenced in the access control policy for the security domain. For access control polices with a limited number of roles a regular expression separating role names with the pipe ("|") character is suggested.
  • useDomainInRoleSearch - (optional) A value of true (default) indicates that the optionally supplied domain used for authentication will be included in the role search filter's {username} substitution value [true|false]. This option is useful for sites that have migrated from an NT domain to Active Directory, where accounts may not have a userPrincipalName attribute. In such cases, configuring this value to false and using a role search filter that searches on the sAMAccountName attribute instead of the userPrincipalName is suggested.
  • emptyPassword - (optional) Allow use of empty passwords (false by default). Set this value to true to allow anonymous login.
  • defaultRoles - (optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.
  • useRoleSearch - (optional) A value of true (default) indicates that a role search will be attempted [true|false]. This option is useful for sites configuring Cams for single sign-on (sometimes to a SharePoint or OWA server using Cams Windows Impersonation) and not using Cams for role-based access control.
  • addPrivateCredentials - (optional) A flag that indicates whether or not a java.net.PasswordAuthentication object containing the user name and password should be added to the Subject's private credential set on successful authentication. See Cams IIS Web Agent Guide - Windows Impersonation Configuration for additional information.

    WARNING: The private credientials are not encrypted and can be accessed by other Cams policy components, Cams web agent and applications within your web tier. Administrators must ensure that only trusted components are used and have access!

Unbound ID LDAP Login Module

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.

You use the UnboundID LDAP login module to access authentication credentials stored in LDAPv3 compliant user directories. This login module flexibly supports many variations of X.500 and DNS style schema similar to those described in Example 15.

Tree Structure LDAP Objects

dc=domain,dc=com

ou=people

dn=user_1_DN

dn=user_2_DN

dn=user_n_DN

ou=groups

dn=group_1_DN

dn=group_2_DN

dn=group_n_DN

Users:

top

person

organizationalPerson

inetOrgPerson

Groups:

top

groupOfUniqueName


Example 15 - Sample DNS style LDAP schema and objects supported by the LDAP login module

The UnboundID LDAP login module expects a schema similar to those in Example 15 to perform:

  1. Authentication - The UnboundID LDAP login module substitutes the user name that the user enters when prompted for authentication against the {username} parameter in curly brackets in the userDN (distinguished name) option value (see below). The Cams authentication service then attempts to connect and bind to the LDAP server with the userDN and password. If the bind is successful, then authentication for this login module succeeds. For example, if you enter johnsmith for the user name and the userDN option value is:

    uid={username},ou=people,dc=domain,dc=com

    then Cams will attempt to bind with userDN:

    uid=johnsmith,ou=people,dc=domain,dc=com

  2. Role Assignment - After authentication succeeds the Cams UnboundID LDAP login module performs a role search to retrieve and assign the user roles. Sites often use group attributes for role assignments (though they are different). You must specify the base distinguished name, search scope, search filter and role attribute name that will be used to find roles.

    NOTE: If your LDAP server does not provide groups or roles, then it is valid to specify a role filter that returns nothing. Another option would be to alter the LDAP login module for your requirements. See Programming Cams JAAS Login Modules.

Your LDAP server may use a schema different from the one specified above. Also, your LDAP server's access control settings may effect integration with Cams. For example, for the LDAP login module to return role information successfully, the LDAP server access control policy must allow a bound user to search the group tree.

We recommend you use the UnboundID LDAP login module configurator in the Cams test Jetty web server. This tool enables you to quickly configure and test options and then generate XML for insertion into login-module.xml and testing with the Cams policy server. For example, to find roles, use searches such as:

baseDN: ou=groups,dc=domain,dc=com
filter: (uniqueMember=uid=myUID,dc=domain,dc=com)
scope: one
attributes: cn

The UnboundID LDAP login module enable the following features to be configured:

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 Server Sets. The following Server Set 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 provides 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.

Example 16 shows a sample UnboundID LDAP login module configuration.

NOTE: When migrating from the deprecated LDAP login module, we recommend copying previous configuration values into the XML snippet provided in Example 16 to ensure that parameters names are correct.

<login-module-entry
 className="com.cafesoft.cams.auth.login.module.UnboundIDLdapLoginModule"
 flag="REQUIRED">
 <options>
  <option name="debug"             value="false"/>
  <option name="ldapPoolServiceId" value="unboundid-ldap-connection-pool"/>

  <!-- Used only if ldapPoolServieId not supplied
  <option name="serverSetType"     value="SINGLE"/>
  <option name="connectionHost"    value="host.domain.com"/>
<option name="connectionPort" value="389"/> <option name="useSSL" value="false"/> <option name="connectionTimeout" value="3000"/> <option name="responseTimeout" value="3000"/> <option name="ldapServerType" value="ACTIVE_DIRECTORY"/> --> <option name="userDN" value="uid={username},ou=people,dc=domain,dc=com"/> <option name="baseDN" value="ou=groups,dc=domain,dc=com"/> <option name="scope" value="ONE"/> <option name="filter" value="(uniqueMember=uid={username},ou=people,dc=domain,dc=com)"/> <option name="attribute" value="cn"/> <!-- Optional <option name="emptyPassword" value="false"/> <option name="defaultRoles" value="role1,role2,role3..."/> <option name="roleRegexPattern" value="role1|role2|role3..."/> --> </options> </login-module-entry>

Example 16 - Cams UnboundID LDAP login module login-config.xml sample

The required LDAP login module options values are:

  • debug - Enables/disables debugging for the login module.
  • ldapPoolServiceId - (optional) The name of the service ID configured in security-domain.xml for an UnboundID LDAP connection pooling service. When configured, the connection pooling service uses the services LDAP connection parameters and ignores any configured for this login module. When a ldapPoolServiceId is used, the following LDAP connection-related options are not needed for this login module configuration: 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 login module are shared and must be the same for each 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.
  • 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.
  • ldapServerType - (optional) A tag used to set the LDAP server type, which is useful for identifying server-specific error codes and translating them to specific login exceptions like: AccountExpiredException, CredentialExpiredException, FailedLoginException, and LoginException. Valid values include:
    ACTIVE_DIRECTORY - Active Directory and ADAM (AD LDS as of Windows Server 2008)
    GENERIC - (default) All LDAP servers that are not ACTIVE_DIRECTORY
  • userDN - (required) The distinguished name pattern for a user. The user name entered by the user at login will be substituted for the value "{username}". The LDAP login module will not successfully find users in schema that use a distinguished name that does not use the user name to distinguish users.
  • baseDN - (required) The base distinguished name to use for your LDAP schema role searches.
  • scope - (required) 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).
  • filter - (required) The filter to use to search for a users roles. 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 XML parser as tag, you must substitute the value "&amp;" for any ampersands in the filter.
  • attribute - (required) The name of the attribute used to store the role names (usually only one name is supplied but this can be a comma-delimited list).
  • emptyPassword - (optional) Allow use of empty passwords (false by default). Set this value to true to allow anonymous login.
  • defaultRoles - (optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.
  • roleRegexPattern - (optional) Limits roles saved in user sessions to those that match a regular expression pattern. This option is useful when a role search returns many user roles that are not referenced in the access control policy for the security domain. For access control polices with a limited number of roles a regular expression separating role names with the pipe ("|") character is suggested.

X.509 Certificate LDAP Login Module

The Cams X.509 Certificate LDAP login module requires a user to enter a user name and password as well as supply a valid X.509 client certificate, which are all used for Cams authentication. This login module uses the same login configuration options and supports the same directory schemas as the Cams LDAP login module with two additional requirements. First, user's web browser and the web server used for the Cams authentication POST must be configured for SSL/TLS mutual authentication to force transmission of the user's X.509 client certificate. Second, the LDAP server schema must contain a userCertificate attribute in each user account with an exact copy of each user's X.509 client certificate installed in the user's browser.

Upon receipt of the three required credentials as a Cams authentication request, the Cams X.509 Certificate LDAP login module first validates the user name and password. Then, the client certificate's date is checked for validity after which the certificate is exactly compared to the certificate found in userCertificate attribute of the user's account. If all these checks pass, authentication for this login module succeeds.

To configure Cams and the X.509 Certificate LDAP login module, the following three steps are required:

Step 1) Configure your web server and browser for mutual authentication

Cams relies upon SSL/TLS mutual authentication for the X.509 Certificate LDAP login module to operate correctly. You should reference your web or application server documentation for configuration instructions. If you are not familiar with SSL/TLS mutual authentication, we strongly suggest you learn about it before configuring this login module. As a learning aid, the Cams policy server's Jetty test web server includes instructions to easily configure it for SSL/TLS mutual authentication with a test X.509 Certificate Java Key Store (JKS) login module. Configuration instructions are found in the Cams policy server distribution at CAMS_HOME/jetty/etc/x509/README.txt.

Step 2) Enable the Cams web agent to send the client certificate

You must enable each Cams web agent you'll use for authentication requests to submit the X.509 client certificate by setting in cams-webagent.conf:

cams.login.x509.cert.enable=true

Please see the Configuration Properties appendix, which is included with the documentation for each Cams web agent for more information.

Step 3) Configure the Cams X.509 Certificate LDAP login module options

Because the X.509 Certificate LDAP login module configuration options are exactly the same as for the LDAP login module, configuration information is not duplicated. Instead, please see the instructions for the Cams LDAP login module paying close attention to the warning below.

WARNING: When using LDAP login module instructions to configure the X.509 Certificate LDAP login module, remember to change the login module className reference from:

com.cafesoft.cams.auth.login.module.LdapLoginModule

to:

com.cafesoft.cams.auth.login.module.X509CertificateLDAPLoginModule

To help you get started, a brief SSL/TLS Mutual Authentication Primer is provided as an appendix, which includes links to SSL/TLS configuration instructions for popular web servers and browsers. Another appendix, Configuring Apache 2.0 for SSL/TLS Mutual Authentication using an OpenSSL Certificate Authority includes the recipe Cafésoft uses internally to configure an Apache 2.0 SSL/TLS mutual authentication test environment.

NOTE: The X.509 Certificate LDAP login module does not support use of a Certificate Revocation List (CRL). Normally, the internal workflow would be to disable the user account or revoke the X.509 certificate within the user account instead. Should you require CRL support in this login module or need support for a directory server other than LDAP for client certificate storage, please contact Cafésoft for recommendations.

XML Login Module

Example 17 shows the sample entry for the XML login module. You use the XML login module to access authentication credentials stored in a cams-users.xml directory, found by default in each security domain. This user directory is supplied with Cams for convenience and system-level use (e.g. Cams web agent authentication) and is not recommend for production sites with a large number of users.

The XML login module does not process the contents of the cams-users.xml file directly. Instead, it makes use of a Cams service, which loads the XML file and reloads it when modifications are made. This Cams service (defined in security-domain.xml) caches user name, password, and role information in memory, greatly improving the efficiency of authentication making it ideal for small user communities that don't change and for authenticating Cams web agents. The path to Cams user directory and the XML handler that knows how to parse the file are specified in the service manager configuration.

<!-- In login-config.xml, register a cams-users.xml directory service -->
<login-config-entry>
 ...
 <login-module-entry
   className="com.cafesoft.cams.auth.login.module.XmlLoginModule"
   flag="REQUIRED">
  <options>
   <option name="debug"     value="false"/>
   <option name="serviceId" value="cams-user-repository"/>
  </options>
 </login-module-entry>
 ...
<login-config-entry>

<!-- In security-domain.xml, register a cams-users.xml directory service -->
<service manager> ... <service id="cams-directory" 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.security-domain.home}/cams-users.xml"/>
<param name="repositoryFactoryClass"
value="com.cafesoft.security.engine.auth.login.userrepository.XmlUserRepositoryFactory"/>
<param name="handlerClass"
value="com.cafesoft.security.engine.auth.login.userrepository.CamsXmlUserRepositoryHandler"/>
<param name="debug" value="false"/>
</param-list>
</service> ... </service-manager>

Example 17 - Sample Cams XML login module as defined in login-config.xml and by the associated security-domain.xml service

The required XML login module options values are:

  • debug - Enables/disables debugging for the login module.
  • serviceId - The unique identifier of the Cams XML user repository service (configured in security-domain.xml) that you will use with the XML login module.
  • repositoryFilePath - The fully-qualified file path to the XML user repository (the default location is in the same security domain directory as the associated login-config.xml file).
  • repositoryFactoryClass - The fully-qualified Java class name of the class that implements the XML user repository (the default is com.cafesoft.security.engine.auth.login.userrepository.XmlUserRepositoryFactory).
  • emptyPassword - (optional) Allow use of empty passwords (false by default). Set this value to true to allow anonymous login.
  • defaultRoles - (optional) A comma-delimited list of roles to be assigned to each successfully authenticated user.
  • charEncoding - (optional) the character set encoding used to convert password characters to bytes when used for digest string comparisons. If not specified, then default platform character encoding is used. NOTE: if user passwords are stored as digest strings, the same character encoding should be used in this login module as used when the password digest was originally created.

The XML login module supports password digests using UNIX Crypt, MD5, and SHA, SMD5, and SSHA. The algorithm is specified within curly brackets in a label that precedes a base 64 encoding of the hashed password (e.g., {CRYPT}, {MD5}, {SHA}, {SMD5}, {SSHA}), which may also include salt bytes. See password digests for more information.

See Security Domain Configuration - Cams XML User Repository Service for information on how to configure services.

Callback Handlers

Cams uses callback handlers to pass user credentials to the login module. The default Cams MapCallbackHandler is sufficient to pass virtually any type of credential to the login module for use, including user names, password, pins, tokens, X.509 certificates, and more. To specify a callback handler for use with a Cams login module, each <login-config-entry> includes the following required tag, which you'll not likely need to change:

<callback-handler
  classname="com.cafesoft.cams.auth.callback.MapCallbackHandler"/>  		 

The standard Cams JDBC, LDAP and XML login modules are coded to use the MapCallbackHandler to obtain the user name and password credentials. Other Cams login modules use the MapCallbackHandler to obtain X.509 certificates and other credentials supplied with a Cams authentication request.

Login Parameters

Login parameters help define the login configuration. The Cams policy server sends the required camsLoginUrl to a Cams web agent when an access check requires user authentication. The Cams web agent then redirects the user's browser to the URL indicated by camsLoginUrl, which references a dynamic script that generates a HTML form to:

  1. Prompt the user for login credentials. For example, the default Cams JDBC, LDAP and XML login modules require user name and password credentials, which they obtain from the cams_cb_username and cams_cb_password HTML form fields via the Cams MapCallbackHandler. Three additional required form values are dynamically populated by the script using redirect query parameters, including: cams_security_domain, cams_login_config and cams_original_url.
  2. POST the credentials and other required values to the configured Cams web agent login URL, which is by default /cams/login.

The value of camsLoginUrl can be an absolute or relative URL. The default /cams/login.jsp relative URL only works correctly on web servers that support Java Server Pages (JSPs).

WARNING: You must change the camsLoginUrl to reference a valid dynamic script on your site. For example, IIS sites might use the default script /cams/login.aspx supplied with the Cams IIS web agent and Apache sites might use the default script /cgi-bin/cams-login.pl supplied with Cams Apache web agents.

Generally, we recommend that you configure a web server (or pair of redundant web servers when using a Cams policy server cluster) as authentication proxies to serve the Cams login page and receive posted login values. This approach eases integration in heterogeneous environments or when many web servers are deployed. These authentication proxies can also be configured with digital certificates to enable secure transmission of the user credentials from browsers to the web server using HTTPS. Example 18 shows use of a fully-qualified, secure camsLoginUrl value. Any web server with a Cams web agent can be used as an authentication proxy.

<login-parameters>
 	<login-parameter name="camsLoginUrl" value="https://www.domain.com/cams/login.jsp"/>
</login-parameters>

Example 18 - Cams login parameters

NOTE: Cams login pages are samples. You should customize them for your site or use them as templates to create new login pages in any scripting language supported by your web server. For more information, see the Login Scripts appendix included in the documentation for each Cams web agent.

Customizing Login Exception Messages

Login modules throw exceptions for various failure conditions, which you can use to provide users information on why the request failed. You can customize messages associated with these standard JAAS login exception classes used by Cams login module implementations:

  • javax.security.auth.login.LoginException - indicates an error while trying to authenticate a user. In general, this exception is thrown by login module implementations to indicate a configuration, connectivity or runtime error, not a normal authentication failure.
  • javax.security.auth.login.FailedLoginException - indicates an authentication failure. For example, a user may not exist or the supplied password is invalid.
  • javax.security.auth.login.AccountExpiredException - indicates that an account has expired. For example, a login module, after successfully authenticating a user, may determine that the user's account has expired.
  • javax.security.auth.login.CredentialExpiredException - indicates that a credential has expired. For example, a login module may determine that the user's password, although entered correctly, has expired.

In addition, login module developers are free to create new login exception subclasses to convey appropriate context for why an authentication request has failed. Cams provides a way for each security domain to define customized login exception messages based on the class or subclass of the login exception that may be thrown by a login module. Standard login exception messages are provided in a file named login-exception.properties in each security domain's home directory.

Example 19 shows the messages defined for the login exception class and standard subclasses.

#
#--- Customized LoginException error messages.
#
javax.security.auth.login.FailedLoginException.message=\
       "Authentication failed, invalid credentials"
#
#--- Indicates that a user account has expired.
#
javax.security.auth.login.AccountExpiredException.message=\
       "Authentication failed, account expired"
#
#--- Indicates that a credential (e.g. password) associated with a user
#--- account has expired.
#
javax.security.auth.login.CredentialExpiredException.message=\
       "Authentication failed, credentials expired"
#
#--- Generic LoginException, which is returned if the LoginModule throws
#--- javax.security.auth.login.LoginException or a subclass-specific
#--- message is not defined.
#
javax.security.auth.login.LoginException.message=\
       "Authentication failed, authentication error"

Example 19 - Standard Cams login exception messages defined in login-exception.properties

The actual message returned when a login exception (or a subclass of login exception) is thrown by a login module is as follows:

  1. If a login module throws javax.security.auth.login.LoginException and property: javax.security.auth.LoginException.message is defined, then the value of this property is returned.
  2. If a login module throws a subclass of javax.security.auth.login.LoginException and a property with the exact subclass name followed by .message is defined, then the value of that property is returned.
  3. If a login module throws a subclass of javax.security.auth.login.LoginException and a property with the exact subclass name followed by Message is NOT defined, then the value of javax.security.auth.login.LoginException.message is returned.
  4. If a login module throws javax.security.auth.login.LoginException or any subclass of that exception, and a corresponding property is NOT defined in this file, then the textual message provided by the login module when it instantiated the login exception is returned.
    NOTE: This may be useful for debugging unsuccessful login attempts because login module implementations will sometimes include context sensitive messages. To see only the raw login exception messages provided by a login module, comment out all properties in login-exception.properties.

To support a context-sensitive message for a subclass of login exception which is not included in the login-exception.properties, simply add a line of the form:

<LoginException subclass name>Message=Message Text

Example 20 shows a custom exception used by a fictitious login module that records previous failed login attempts and does not permit additional login attempts for a given period.

#
#--- Indicates the authentication failed due to 3 previous failed login attempts.
#
example.auth.login.MultipleFailedLoginsException.message=\
       "Authentication failed, 3 or more previous login failures. Try again in 2 minutes."

Example 20 - Adding a new login exception message to login-exception.properties

Support for Password Digests

Password digests are one-way hashes that securely store a password using secure, industry standard hashing algorithms. Cams login modules that retrieve the password value from a database implement support for Cams to compare digests within the login module. In this case, when a user supplies a password for authentication the Cams login module determines how the password in the user directory was hashed and then uses the same formula to hash the password to be validated. If the resulting digest is the same as the digest stored in the user directory, the user is authenticated.

Cams provides supports for UNIX Crypt, SHA (with and without salt) and MD5 (with and without salt) digests. Typically, encryption authorities today recommend use of the SHA algorithm with random salt bytes. For more information on how Cams implements support of digest, see the Password Digests appendix and the online password digests web application.

Configuring Cams Automatic HTTP User Login

Cams provides a user convenience feature that enables returning web site users to automatically and transparently login if they successfully authenticated on a previous visit and chose to be remembered. This feature is facilitated by sending a persistent AUTOLOGIN cookie containing encrypted user credentials to the user's browser on successful authentication. When the user returns to access a Cams enabled site with automatic login enabled and an AUTOLOGIN cookie is presented, Cams web agents transparently try to authenticate the user. If the authentication is successful, a normal Cams memory resident session cookie is sent to the user's browser. If Cams cross DNS domain single sign-on (CDSSO) is also enabled, successful AUTOLOGIN will initiate the CDSSO protocol to create a Cams session cookie in all cookie domains. NOTE: See Configuring Cams Cross DNS Domain Web Single Sign-On for more information.

The Cams automatic login feature is a user convenience that enables transparent authentication in the case that a previous Cams session expired due to inactivity. If a user explicitly logs out, then the Cams AUTOLOGIN cookie is removed by the Cams web agent that intercepts the logout request and the user will be required to provide their login credentials the next time he visits your Cams-enabled site. The Cams AUTOLOGIN cookie also has a site configurable expiration value that you can set.

The following steps are required to implement Cams automatic login:

  1. Add a checkbox with name cams_cb_autologin_flag to the Cams login page that enables the user to select automatic authentication for subsequent visits. The checkbox is normally presented with a label such as Remember Me.
  2. Enable the Cams automatic login feature in your Cams web agents.
  3. Enable the Cams automatic login cookie "secure" setting if desired. NOTE: Please see details on the consequences of using this feature later in this document.
  4. Enable and configure the Cams automatic login authentication valve in the authentication service of the desired security domain(s).
  5. Restart the Cams policy server and web agents.

More details for each of these steps is provided below.

Configuring the Cams Login Page

The option to perform Cams automatic login for future authentications is normally presented to a user with a checkbox on a Cams login page. You can also add a hidden field to the login page that automatically selects this feature for all authenticating users, but it is generally encouraged to allow the user to select this feature as he may have security concerns related to persistent cookies that store encrypted passwords.

Example 21 shows the HTML that adds a Remember Me checkbox to a Cams login page. The check box must be named cams_cb_autologin_flag and must be added within the HTML form containing the other HTML input fields containing Cams callback values.

...
<input type="checkbox" name="cams_cb_autologin_flag" value="true"/> Remember Me
...

Example 21 - Adding the cams_cb_autologin_flag checkbox to a Cams login page

If the user selects this checkbox and then Posts the form to a Cams-enabled web site, the parameter cams_cb_autologin_flag=true will be sent. This will inform Cams that the user has opted to use Cams automatic login on future visits if the current authentication request succeeds.

Configuring the Cams Web Agent

Cams web agents enable automatic HTTP user login by setting the cams.autologin.enabled=true property in cams-webagent.conf as shown in Example 22.

#
# cams.autologin.enabled
# Toggle Cams automatic login on/off [true|false]. The automatic login
# feature must be enabled in the associated security domains's
# security-domain.xml file.
#
cams.autologin.enabled=true

Example 22 - Enabling Cams HTTP autologin in cams-webagent.conf

The Cams AUTOLOGIN cookie may also be configured as "secure", which tells web browsers that the cookie is only to be sent to SSL-protected URLs within the configured AUTOLOGIN "cookie domain". This can help thwart access to the Cams AUTOLOGIN cookie value, which might potentially be decrypted using a brute-force attack to access user credentials.

Despite the extra security this feature provides, most sites choosing to use Cams AUTOLOGIN will probably NOT use this feature because it can reduce user convenience or may require restructuring a site so that all authentication-protected content is available ONLY via SSL.

For example:

  • if the AUTOLOGIN cookie is configured to be "secure"
  • AND a user is not authenticated
  • AND the user attempts to access a non-SSL web page for which a Cams access control policy requires user authentication
  • THEN the user will not be transparently logged in via AUTOLOGIN
  • Instead, the user will need to log in manually

If this restriction does not apply to your site and/or if you do want to enable secure AUTOLOGIN cookies because convenience is more important to users than tighter security, set the value cams.autologin.cookie.secure=true property in cams-webagentconf as shown in Example 23.

NOTE: Most sites implementing autologin will give the user the option to Remember Me by selecting a check box. You should also consider providing information to users on your web site on the security consequences of using this feature, especially if the autologin cookie is not secure.

#
# cams.autologin.cookie.secure
# Make the Cams AUTOLOGIN cookie secure by setting the Cookie "Secure" flag
# This flag tells web browsers to send the Cams AUTOLOGIN cookie only to
# SSL-enabled web sites. NOTE: before setting this value to "true", you
# should test your web site to ensure that AUTOLOGIN works correctly
# through an SSL-enabled URL and access only SSL-enabled URLs when
# an authenticated user identity is required.
#
cams.autologin.cookie.secure=true

Example 23 - Enabling use of secure Cams autologin cookies in cams-webagent.conf

Configuring the Cams Policy Server Authentication Service

The Cams policy server includes a component that must be uncommented and enabled in security-domain.xml to support Cams automatic login. When enabled and during normal (non-automatic) authentication, this component is responsible for:

  1. Determining if future automatic login is requested by a user that has successfully authenticated.
  2. Encrypting all Cams callback values using a security domain specific encryption algorithm, secret key and other security parameters.
  3. Adding the Cams automatic login value to the authentication response for handling by Cams web agents.

When automatic login is requested by a Cams web agent by presenting the Cams AUTOLOGIN cookie value as an authentication token, this component is responsible for:

  1. Decrypting the AUTOLOGIN authentication token
  2. Adding the decrypted callback parameters to the authentication request

If the encrypted AUTOLOGIN authentication token cannot be successfully decrypted because the encryption algorithm, secret key or other security parameters have been changed since the original AUTOLOGIN cookie was created, then callback parameters cannot be added to the authentication request. In this case, authentication will fail and the Cams web agent will ultimately tell the user's browser to delete the Cams AUTOLOGIN cookie.

Example 24 shows the Cams automatic login authentication valve component that can be configured within any security-domain.xml file. If you're using the standard security-domain.xml file that ships with the system security domain, this valve is already available, but commented out and disabled.

...
<auth-pipeline className="com.cafesoft.security.engine.auth.StandardAuthPipeline">

 <!-- The Cams Autologin Authentication Valve -->
<auth-valve className="com.cafesoft.security.engine.auth.valves.AutoLoginAuthValve">
<param-list>
<param name="enabled" value="false"/>
<param name="algorithm" value=""/>
<param name="key" value=""/>
<param name="iv" value=""/>
<param name="expiration" value=""/>
<param name="suffix" value=""/>
</param-list>
</auth-valve> ...

Example 24 - Enabling the Cams Auto Login authentication valve

After adding or uncommenting the valve, you must configure its parameters as described below. Example values are not provided so that you won't be tempted to copy published values that could make encrypted AUTOLOGIN values vulnerable to attack.

NOTE: Use the scripts provided at CAMS_HOME/bin/camsSecretKeyGen.bat/sh or the web application in the Cams policy server's Jetty web server to select an encryption algorithm and generate a random encryption/decryption key and initialization vector.

  • enabled - set this value to true to enable Cams automatic HTTP login and to false to disable it.
  • algorithm - the secret key algorithm to be used when encrypting and decrypting selected values sent to/received from the Cams web agents. Valid values include: AES, Blowfish, DES, and DESede
    (triple DES). AES uses a 32 byte encryption key, Blowfish uses a 16 byte encryption key, DES uses an 8 byte key, and DESede uses a 24 byte key.
  • key - the secret encryption/decryption key in hexadecimal format. The actual number of bytes used depends on the algorithm, although it is legal to supply more key bytes than needed.
  • iv - the encryption/decryption initialization vector in hexadecimal format. This value is used to scramble the beginning of encrypted values to ward against dictionary attacks. This should be an 8 byte (16 hex digit) value for Blowfish, DES, and DESede and a 16 byte (32 hex digit) value for AES.
  • expiration - the number of days for which the AUTOLOGIN cookie is valid and after which it will expire.
  • suffix - a value that is added to the AUTOLOGIN token before decryption as a marker to ensure that various components such as the key or iv have not changed since the last attempt to login automatically. On decryption, this value must be at the end of the authentication token to verify that decryption has successfully recovered the originally encrypted values. You may use any short string for this value, although it must not contain the colon ":" character.

NOTE: If you choose to use the Auto Login authentication valve with the Cross DNS domain single sign-on valve, you must place the XML configuring the Auto Login valve after the XML for the Cross DNS domain single sign-on valve. This enables the CDSSO valve to access the authentication response information needed for these two features to work together correctly.

Restart the Cams Policy Server and Cams Web Agents

After configuring Cams automatic HTTP login options and components, remember to restart the Cams policy server and the servers containing your Cams web agents. To test automatic login, login to your site using normal authentication credentials making sure your select Remember Me on the Cams login page. On successful authentication, the Cams AUTOLOGIN cookie will be created. It will have a Cams cluster and security domain-specific name. For example:

CAMS_AUTO_LOGIN_MYCAMSCLUSTER_SYSTEM

Do NOT logout from your web site. You must either let the Cams session ID cookie expire, named something like CAMS_SID_MYCAMSCLUSTER_SYSTEM, or manually remove the cookie from your browser. After removal, attempt to access any resource on the site that created the Cams AUTOLOGIN cookie. If a new Cams session cookie is created and you can browse to protected resources without being prompted for authentication, then automatic login succeeded.

NOTE: The FireFox web browser is useful when doing testing involving cookies. You can use select the "Tools -> Options -> Privacy -> Cookies -> View Cookies" to view and remove persistent and memory resident cookies.

Deleting the Cams AUTOLOGIN Cookie

The Cams AUTOLOGIN cookie has a configurable expiration period (in days) that will force the user's browser to automatically delete the cookie once the expiration date/time has been passed. A user may also force deletion of the AUTOLOGIN cookie by explicitly clicking a Cams logout URL on the originating web site.

Administrators may force deletion of AUTOLOGIN cookies by changing the secret key parameters used to encrypt the cookie value. AUTOLOGIN cookies that cannot be decrypted by the Cams automatic login valve are always removed.

NOTE: Though the Cams automatic login and Cams cross DNS domain web single sign-on can be used together, the AUTOLOGIN cookie will only be deleted in the DNS cookie domain in which the user requests logout. If you configure propagation of autologin parameters during CDSSO (configured in the CDSSO valve), an AUTOLOGIN cookie will be created in every cookie domain. When the user explicitly logs out, only the AUTOLOGIN cookie in the "current" cookie domain is deleted. This issue will be resolved when Cams cross DNS domain single logout is implemented.

Configuring Cams Cross DNS Domain Web Single Sign-On

Cams supports just-in-time cross DNS domain web single sign-on (CDSSO) using Cams policy server-based components and Cams web agents. The implementation uses an identity (IdP) and service provider (SP) paradigm. After a Cams session is established within a designated IdP cookie domain, session cookies are automatically created for configured SP cookie domains as users visit them, or just-in-time. If a user without an existing Cams session visits a service provider cookie domain first, he is redirected to the identity provider cookie domain to login, then redirected to the originally requested service provider URL after successful login.

Additional general information is available in the Cams policy server introductory section Cross DNS Domain Web Single Sign-On. This section provides configuration instructions.

The Cams policy server has three components that must be uncommented, enabled, and configured in security-domain.xml to support CDSSO. These components are responsible for:

  1. Centralizing CDSSO configuration settings so they are available to authentication and access control services.
  2. Handling login to identity and service provider cookie domains.
  3. Redirecting users to the identity provider login page if access to a resource is denied because authentication is required.

The three components are:

  1. service id="jit-http-cdsso-service"
  2. auth-valve className="com.cafesoft.security.engine.auth.valves.CamsJITHttpCDSSOAuthValve"
  3. access-control-valve className="com.cafesoft.security.engine.access.valves.CamsJITHttpCDSSOAccessControlValve"

Details on configuring these components is provided in the following sections, but first let's review the Cams web agent configuration requirements.

Configuring Cams Web Agents as Cookie Providers

All Cams web agents are configured by default to act as CDSSO cookie providers. Specifically formatted HTTP GET requests received at a configurable URI are intercepted and handled as CDSSO requests. Example 25 shows the default Cams CDSSO URI value in cams-webagent.conf. We recommend that you leave this value set to the default URI.

#
# cams.sso.uri
# The Cams web agent interprets GET requests to this URI as a cross
# DNS domain single sign-on request.
#
cams.sso.uri=/cams/sso

Example 25 - Property that configures Cams CDSSO URI in cams-webagent.conf

Configuring the Cams Policy Server CDSSO Service

Example 26 shows the Cams CDSSO service component that must be configured within a security-domain.xml file. If you're using the system security-domain.xml file supplied with Cams, this service is already available, but commented out and disabled.

...
<service-manager className="com.cafesoft.core.service.StandardServiceManager">

 <!-- The Cams Just-In-Time Cross DNS Domain Web Single Sign-on Service -->
 <service id="jit-http-cdsso-service" enabled="true" debug="false">
   <service-type>com.cafesoft.security.engine.service.HttpCDSSOService</service-type>
   <service-class>com.cafesoft.security.engine.service.StandardJITHttpCDSSOService</service-class>
   <param-list>
     <param name="enabled"                      value="false"/>
     <param name="algorithm"                    value="Blowfish"/>
     <param name="key"                          value=""/>
     <param name="iv"                           value=""/>
     <param name="enabledForLoginConfigEntries" value="http"/>
     <param name="idp.cookie.domain"            value=".mydomain.com"/>
<param name="idp.cookie.provider.url" value="http://idp.mydomain.com/cams/sso"/> <param name="sp.cookie.domain.1" value=".example.com"/>
<param name="sp.cookie.provider.url.1" value="http://sp.example.com/cams/sso"/> <param name="ssoContextValiditySeconds" value="5"/> <param name="cookieHostSpecific" value="false"/> <param name="cookieDomainSpecialTLDs" value="aero,biz,com,coop,edu,gov,info,int,mil,museum,name,net,org,pro,mobi,us,eu,at,cc,de,bg,tv,bz"/> <param name="cookieDomainMapToLongest" value=""/> <param name="propagateAutoLoginParameters" value="false"/> </param-list> </service> ...

Example 26 - Configuring the Cams Cross DNS Domain Single Sign-On service

After adding or uncommenting the service, you must configure its parameters as described below.

NOTE: An example secret key and initialization vector are not provided so that you won't copy published secret key values that could make encrypted CDSSO values vulnerable to attack. Use the scripts provided at CAMS_HOME/bin/camsSecretKeyGen.bat/sh or the web application in the Cams policy server's Jetty web server to select an encryption algorithm and generate a random encryption/decryption key and initialization vector.

  • enabled - set this value to true to enable the valve and to false to disable it.
  • algorithm - the secret key algorithm to be used when encrypting and decrypting selected values sent to and received from Cams web agents. Valid values include: AES, Blowfish, DES and DESede (triple DES). AES uses a 32 byte encryption key, Blowfish uses a 16 byte encryption key, DES uses an 8 byte key and DESede uses a 24 byte key.
  • key - the secret encryption/decryption key in hexadecimal format. The actual number of bytes used depends on the algorithm, although it is legal to supply more key bytes than needed.
  • iv - the encryption/decryption initialization vector in hexadecimal format. This value is used to scramble the beginning of encrypted values to ward against dictionary attacks. This should be an 8 byte (16 hex digit) value for Blowfish, DES, and DESede and a 16 byte (32 hex digit) value for AES.
  • enabledForLoginConfigEntries - a comma-delimited list of <login-config-entry> names (defined within the security domain's login-config.xml) within an authentication request for which the CDSSO valve will be used. Since the same authentication pipeline may be used to authenticate Cams web agents or other user communities, this value can be used to include only the desired subset of authentication requests eligible for CDSSO.
  • idp.cookie.domain - the identity provider (IdP) cookie domain. You must designate one and only one DNS cookie domain as your identity provider cookie domain. When users login to Cams, session cookie will be created for this cookie domain. As users visit web resources in service provider cookie domains in your environment, Cams will transparently create session cookies for those service provider cookie domains using a redirect protocol that leverages the established identity at the identity provider cookie domain. The value of parameter idp.cookie.domain must tail match the host part of the cookie provider url assigned to parameter idp.cookie.provider.url.
  • idp.cookie.provider.url - the cookie provider URL for the identity provider (IdP) cookie domain. The host name in this fully-qualified URL must tail match the value of parameter idp.cookie.domain. The following configuration examples show IdP settings for a fully-qualified DNS domain, an unqualified host name, and an IP address:
    Example: Fully-qualified DNS Names

    <param name="idp.cookie.domain" value=".mydomain.com"/>
    <param name="idp.cookie.provider.url" value="http://idp.mydomain.com/cams/sso"/>

    Example: Unqualified Host Names

    <param name="idp.cookie.domain" value="localhost"/>
    <param name="idp.cookie.provider.url" value="http://localhost/cams/sso"/>

    Example: IP Address

    <param name="idp.cookie.domain" value="127.0.0.1"/>
    <param name="idp.cookie.provider.url" value="http://127.0.0.1/cams/sso"/>

  • sp.cookie.domain.N - a designated service provider (SP) cookie domain. The actual parameter name must end with a number, which must start with the number 1. For example: sp.cookie.domain.1. You may configure as many SP cookie domains as needed, but they must be numbered sequentially (starting with 1) and without skipping any numbers in the sequence. So, if you configure three SP cookie domains, the corresponding property name must be: sp.cookie.domain.1, sp.cookie.domain.2, and sp.cookie.domain.3.
  • sp.cookie.provider.url.N - the SP cookie provider URL for SP cookie domain N. The actual parameter name must use the same number as its corresponding sp.cookie.domain.N parameter. The following configuration examples show SP settings for a fully-qualified DNS domain, an unqualified host name, and an IP address:
    Example: Fully-qualified DNS Names

    <param name="sp.cookie.domain.1" value=".example.com"/>
    <param name="sp.cookie.provider.url.1" value="http://sp.example.com/cams/sso"/>

    Example: Unqualified Host Names

    <param name="sp.cookie.domain.1" value="myhost"/>
    <param name="sp.cookie.provider.url.1" value="http://myhost/cams/sso"/>

    Example: IP Address

    <param name="sp.cookie.domain.1" value="192.168.1.100"/>
    <param name="sp.cookie.provider.url.1" value="http://192.168.1.100/cams/sso"/>

    NOTE: For increased security, we recommend that you use SSL-enabled cookie provider URLs.

  • ssoContextValiditySeconds - the number of seconds for which the SSO context created for an IdP and used for SP login is valid before it expires. Each SSO context is valid for one and only one SP login transaction. If the SSO context is received in a subsequent Cams authentication request after the specified number of seconds, it will be rejected and SSO will fail.
  • cookieHostSpecific - set the Cams cookie domain host-specific (true) or DNS domain wide (false). For example, the cookie would be specific to host www.d1.com rather than being sent to all hosts withing cookie domain .d1.com. The default value is false.
    NOTE:
    this value must be defined with the same value as property cams.cookie.host-specific in cams-webagent.conf files or unpredictable results may occur.
  • cookieDomainSpecialTLDs - An optional, comma-separated list of special DNS top-level domains (TLDs) that are allowed to have a cookie domain depth of 2. Non-special TLDs will have a default cookie domain depth of 3. For example, if TLD uk is in the list, then a cookie domain of .d1.uk (depth=2) is permitted. If uk is not in the special TLD list, then the cookie for host www.d1.uk would be host-specific because cookie domain .d1.uk (depth=2) would be invalid, however a cookie domain of .d2.d1.uk (depth=3) would be valid for a host like www.d1.d1.uk. If not specified (property is missing or empty), the value is: aero,biz,com,coop,edu,gov,info,int,mil,museum,name,net,org,pro,mobi,us,eu,at,cc,de,bg,tv,bz.
    NOTE: This value must be defined with the same value as property cams.cookie.host-specific in cams-webagent.conf files or unpredictable results may occur.
  • cookieDomainMapToLongest - An optional, comma-separated list of cookie domains that limits Cams session cookie scope to an arbitrary DNS subdomain. For example, a fully-qualified host name www.d2.d1.com with defined special TLD com, would by default be assigned a cookie domain of depth 2 (.d1.com). By using cookieDomainMapToLongest=.d2.d1.com the cookie would be assigned its subdomain instead and would consequently be sent by web browsers only to hosts within that DNS subdomain. The default value is empty (no mappings defined).
    NOTE: This value must be defined with the same value as property cams.cookie.host-specific in cams-webagent.conf files or unpredictable results may occur.
  • propagateAutoLoginParameters - An optional true or false (default) value that is used with the Cams AUTOLOGIN authentication valve. If the AUTOLOGIN valve is enabled and the propagateAutoLoginParameters is set to true, the CDSSO valve captures the AUTOLOGIN parameters and uses them during CDSSO to create AUTOLOGIN cookies as IdP and SP session cookies are created. This enables AUTOLOGIN and CDSSO for any site a user visits first where the AUTOLOGIN values have been propagated.

NOTE: When CDSSO is enabled all initial login requests SHOULD be directed to the IdP cookie domain. This ensures that a Cams session cookie is available in the IdP cookie domain and subsequent SSO requests to SP cookie domains work transparently. If a misconfigured login page posts login requests to an SP cookie domain, the Cams policy server logs a warning message, but allows the login request to continue. In this case, if login succeeds, a Cams session cookie is created for the SP cookie domain only. If the user then navigates to a Cams protected web resource at the IdP or another SP cookie domain, he will need to login again. To simplify your SSO environment and maximize user convenience, configure all login pages to login to the IdP cookie domain.

Configuring the Cams Policy Server CDSSO auth-valve

Example 27 shows the Cams CDSSO auth-valve component that must be configured within a security-domain.xml file. If you're using the system security-domain.xml file supplied with Cams, this service is already available, but commented out and disabled.

...
<auth-pipeline className="com.cafesoft.security.engine.auth.StandardAuthPipeline">

 <!-- The Cams Cross DNS Domain Web Single Sign-on AuthValve -->
 <auth-valve
className="com.cafesoft.security.engine.auth.valves.CamsJITHttpCDSSOAuthValve"
debug="false">
<param-list>
<param name="enabled" value="true"/>
<param name="cdssoServiceId" value="jit-http-cdsso-service"/>
</param-list>
</auth-valve> ...

Example 27 - Configuring the Cams Cross DNS Domain Single Sign-On authentication valve

Configure parameters as described below.

  • enabled - set this value to true to enable the valve and to false to disable it.
  • cdssoServiceId - the identity of the CDSSO service configured in section Configuring the Cams Policy Server CDSSO Service. This value must exactly match the id value configured for the CDSSO service.

Configuring the Cams Policy Server CDSSO access-control-valve

Example 28 shows the Cams CDSSO access-control-valve component that must be configured within a security-domain.xml file. If you're using the system security-domain.xml file supplied with Cams, this service is already available, but commented out and disabled.

...
<auth-control-pipeline className="com.cafesoft.security.engine.access.StandardAccessControlPipeline">

 <!-- The Cams Cross DNS Domain Web Single Sign-on AccessControlValve -->
 <access-control-valve
className="com.cafesoft.security.engine.access.valves.CamsJITHttpCDSSOAccessControlValve"
debug="false">
<param-list>
<param name="enabled" value="true"/>
<param name="cdssoServiceId" value="jit-http-cdsso-service"/>
</param-list>
</access-control-valve> ...

Example 28 - Configuring the Cams Cross DNS Domain Single Sign-On authentication valve

Configure parameters as described below.

  • enabled - set this value to true to enable the valve and to false to disable it.
  • cdssoServiceId - the identity of the CDSSO service configured in section Configuring the Cams Policy Server CDSSO Service. This value must exactly match the id value configured for the CDSSO service.

Restart the Cams Policy Server and Cams Web Agents

After configuring Cams CDSSO options and components, create a role-based access control rule and invoking permission(s) such as those described in Integration Quick Start - Configure a basic access control policy. Your permission should protect at least one web resource on each test SP web site. For simplicity, you might use the same web resource for all test SP sites, such as: /secure/index.html. Remember to restart the Cams policy server and the web servers containing your Cams web agents.

To test, use the camstest page included with all Cams web agents. After successful login to the Cams IdP using camstest, you should be able able to visit the secure web resources on the test SP sites without being prompted for login. You can check the camstest page in every SP cookie domain after accessing the secure web resource and see a Cams cookie with the same session identifier as the Cams IdP cookie.

Web browsers such as Chrome or Firefox are also useful to view HTTP cookies. You should see Cams session cookies for every SP cookie domain that was both registered for CDSSO and accessed during the test. Each cookie has the same Cams cluster and security domain-specific name prefix, for example: CAMS_SID_MYCAMSCLUSTER_SYSTEM.

Configuring Cams CDSSO Single Logout

Cams CDSSO Single Logout (SLO) is configured using a web server script. An example script is provided with each web agent in the scripting language most common to the target web server. Please see Scripts - Cross DNS Domain Single Logout found in the documentation of each Cams web agent for information on the design and integration of the SLO script.

Back | Next | Contents