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 must define a login configuration in login-config.xml. A login configuration are the value Cams uses to connect to a user directory, try to authenticate a user after they supply credentials and search for group memberships if the authentication succeeds. 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. The default http value for <login-config-entry name="http"> should be used for most sites.

NOTE: Cams login pages contain a required cams_login_config value that is dynamically populated or statically hard coded into the page to specify which <login-config-entry> to use within a security domain. When dynamically populated, this value is obtained from the cams.loginconfig.entry value defined in each Cams web agent's cams-webagent.conf file.

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 login modules supplied with Cams are:

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

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

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=company,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@company.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=mycompany,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.company.com"/>
  <option name="port"     value="389"/>
  <option name="useSSL"   value="false"/>
  <option name="connectTimeout" value="3000"/>
  <option name="baseDN"   value="cn=Users,dc=company,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:

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 Example 4 with 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):

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):

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

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=company,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=company,dc=com

    then Cams will attempt to bind with user DN:

    uid=johnsmith,ou=people,dc=company,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 the required options and generate the XML once you have the correct settings. After you achieve success, you can enter the values in login-module.xml and test with Cams. For example, searches such as:

base distinguished name: ou=people,dc=company,dc=com
filter: (ou=myUserName,ou=people,dc=company,dc=com)
scope: one
attributes: userPassword

can be used to determine if the userPassword value can be returned for a user. If your search tool supports specification of calling the compare method, you can use similar values with it to determine if a compare can be done. Searches such as:

base distinguished name: ou=groups,dc=company,dc=com
filter: (uniqueMember=uid=myUserName,dc=company,dc=com)
scope: one
attributes: cn

can be used to determine the roles.

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.company.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=company,dc=com"/>
  <option name="roleBaseDN" value="ou=groups,dc=company,dc=com"/>
  <option name="roleScope" value="ONE"/>
  <option name="roleFilter" 
         value="(uniqueMember=uid={username},ou=people,dc=company,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:

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:

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:

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.

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 13 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 13 - 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:

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 login credentials from the calling application to the login module. For most sites, requesting a user name and password for authentication credentials using an HTML form is sufficient. In this case you use the standard Cams NamePasswordCallbackHandler, which takes a user name and password as input and provides them to the login module.

To specify a callback handler for use with a Cams login module, each <login-config-entry> includes the following required tag: 

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

The Cams JDBC, LDAP and XML login modules generally are configured with the NamePasswordCallbackHandler to supply the user name and password. The NamePasswordCallbackHandler also handles X.509 certificates when supplied with a Cams authentication request. If the NamePasswordCallbackHandler does not meet your needs, see Cams Callback Handlers to understand how to create a new one using Cams pluggable callback framework. For example, you may want to create a new callback handler to accept a third authentication credential in addition to user name and password, such as the last four digits of a user's social security number or a pin.

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 NamePasswordCallbackHandler requires form field values cams_cb_username and cams_cb_password for the user name and password respectively. 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 relative URL (/cams/login.jsp) 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.asp 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 14 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.company.com/cams/login.jsp"/>
</login-parameters>

Example 14 - Cams login parameters

NOTE: Cams login pages are provided as samples that contain the required parameters. You can customize them or create new login pages as required in any scripting language valid for 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:

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 15 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 15 - 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 16 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 16 - 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 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 and configure the Cams automatic login authentication valve in the authentication service of the desired security domain(s).
  4. Use the Cams AutoLoginNamePasswordCallbackHandler instead of the normal NamePasswordCallbackHandler in login-config.xml
  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 17 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 17 - 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 18.

#
# 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 18 - Enabling Cams HTTP autologin 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 19 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. Add or uncomment this valve in the context of the security-domain.xml shown in Example 17.

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

 <!-- The Cams AutoLoginAuthValve -->
 <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 19 - 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.

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.

Configure the AutoLoginNamePasswordCallbackHandler

A callback handler must be configured in login-config.xml for each security domain where Cams automatic HTTP login is enabled. The AutoLoginNamePasswordCallbackHandler provides support for the user name, password and autologin_flag callback parameters that are sent from Cams login pages containing fields named:

Comment out the existing NamePasswordCallbackHandler and add the AutoLoginNamePasswordCallbackHandler in login-config.xml for each security domain as shown in Example 20.

<login-config-entry name="http">
 ...


 <!-- Register the user name/password callback handler
 <callback-handler className="com.cafesoft.cams.auth.callback.NamePasswordCallbackHandler"/>
 -->

 <!-- The Cams AutoLoginNamePasswordCallbackHandler -->
 <callback-handler className="com.cafesoft.cams.auth.callback.AutoLoginNamePasswordCallbackHandler"/>

 ...
</login-config-entry>

Example 20 - Configuring the Cams automatic HTTP login callback handler in login-config.xml

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 cross DNS domain web single sign-on (CDSSO) using Cams Policy Server-based components and Cams web agents. General information is available in the Cams introductory section Cross DNS Domain Web Single Sign-On.

Configuring Cams Web Agents as Cookie Providers

All Cams web agents are configured by default to act as cookie providers for cross DNS domain web single sign-on. Specifically formatted HTTP GET requests received at a configurable URI are intercepted and handled as CDSSO requests. Example 21 shows the default Cams CDSSO URI value in cams-webagent.conf.

#
# 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 21 - Property that configures Cams CDSSO URI 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 cross DNS domain single sign-on. This component is responsible for:

  1. Determining if the <login-config-entry> specified for an authentication request will use CDSSO.
  2. On successful authentication, adding instructions to the authentication response that will cause a Cams web agent to redirect the user's browser to the first cookie provider URL. The URL contains query parameters (including an encrypted cams_sso_context token) used to convey the cross DNS domain single sign-on context to the Cams web agents in the configured cookie domains.
  3. On receiving an authentication request containing SSO tokens, they are decrypted, validated and updated. New instructions are added to the authentication response that will cause a Cams web agent to redirect to the next cookie provider or to redirect to the cams_original_url if all cookie providers have been visited.

Example 22 shows the Cams cross DNS domain authentication valve component that can be configured within a security-domain.xml file. If you're using the system security-domain.xml file supplied with Cams, this valve is already available, but commented out and disabled. Add or uncomment this valve in the context of the security-domain.xml shown in Example 22.

...
<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.CamsHttpCDSSOAuthValve">
  <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="cookieProviderUrls"
          value="http://localhost:8080/cams/sso,http://127.0.0.1:8080/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>
 </auth-valve>
...

Example 22 - Enabling the Cams Cross DNS Domain Single Sign-On authentication valve

After adding or uncommenting the valve, you must configure its parameters as described below. Examples are not provided so that you won't be tempted to copy published secret key values that could make encrypted CDSSO 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.

NOTE: If you choose to use the Cross DNS domain single sign-on valve with the Auto Login authentication 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 cross DNS domain options and components, remember to restart the Cams policy server and the web or application servers containing your Cams web agents.

To test cross DNS domain single sign-on, use the camstest page included with all Cams web agents. After successful login to Cams, you should be able to visit the camstest page in every cookie domain and see the Cams session identifier and secure Cams HTTP request headers.

If you have a web browser that enables you to see HTTP cookies stored in your browser (e.g. Firefox), you should see Cams session cookies for every cookie domain registered. It will have a Cams cluster and security domain-specific name. For example:

CAMS_SID_MYCAMSCLUSTER_SYSTEM

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

Back | Next | Contents

© Copyright 1996-2008 Cafésoft LLC. All rights reserved.