Login Configuration

Cams uses an implementation of the Java Authentication and Authorization Service (JAAS) to provide user authentication services. JAAS authentication defines a Java version of the Pluggable Authentication Module (PAM) framework, 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. Cams does not use the authorization features of JAAS.

This document describes how to configure Cams login modules, which are standard JAAS components used to authenticate users and obtain their roles. See also the Login Configuration Tag Reference for more information on all the XML tags used in the login-config.xml file.

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

Login Configuration

Each Cams security domain must have a login configuration defined in login-config.xml. The login-config.xml file contains both required and optional data specific to login modules. One or more login module configurations can be specified by nesting values within one or more <login-config-entry name="name"> open and close tags, as you can see in the sample login-config.xml file.

NOTE: The default http value for the name parameter should be used for most sites. This value is required for Cams authentication to reference a specific login configuration to use. In most cases, one login configuration entry is sufficient. However, you can optionally specify multiple login configuration entries, each with a unique name. You could then specify that distinct Cams web agents use different login configuration entries by setting the cams.loginconfig.entry value in cams-webagent.conf. For example, if you have distinct web servers for your extranet and intranet, you could use one login configuration entry to authenticate external users on the extranet site and the other to authenticate internal users on the intranet site.

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 location of the Java class for the specified login module implementation. The class names for the login modules supplied with Cams are:

• com.cafesoft.cams.auth.login.module.ActiveDirectoryLoginModule
• com.cafesoft.cams.auth.login.module.JdbcLoginModule
• com.cafesoft.cams.auth.login.module.LdapLoginModule
• com.cafesoft.cams.auth.login.module.XmlLoginModule

<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>
</login-config-entry>	

A <login-config-entry> can have one or more <login-module-entry>. The flag parameter determines the behavior when multiple login modules are used by specifying whether a module is required, requisite, sufficient or optional.

• REQUIRED - Normally set when authentication by this module is a must. With this flag, any module failure results in the PAM framework returning the error to the caller after executing all other modules on the stack. For the function to be able to return success to the application, all required modules have to report success.
• REQUISITE - The module must be successfully checked in order for the authentication to be successful. If a requisite module check fails, the user is notified immediately with a message reflecting the first failed required or requisite module.
• SUFFICIENT - Used if the module succeeds the PAM framework, then returns success to the application immediately without trying any other modules. For failure cases, the sufficient modules are treated as optional.
• OPTIONAL - Used when the user is allowed access, even if that module has failed. With this flag, the PAM framework ignores the module failure and continues processing the next module in sequence.

Specifying more than one <login-module-entry> for a single <login-config-entry> configuration is also known as stacking. The interaction between flags when stacking can be complicated so you should keep these configurations as simple as possible. In most cases, you'll specify a single login module with flag value set to REQUIRED.

The optional values are specific to each login module and are explained in the sections below. All options 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. Login module configurators are provided for Active Directory, LDAP and SQL databases. We highly recommend that you start the Jetty test server and browse to:

http://localhost:8080/

to access these configurators. 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 changed configuration values for your Cams policy server, you may have to change any associated values found in CAMS_HOME/jetty/etc/cams-webagent.conf.

Login Modules

The login modules included with Cams are:

• Active Directory Login Module - for use with Microsoft Active Directory
• JDBC Login Module - for use with SQL databases that have JDBC drivers
• LDAP Login Module - for use with most LDAPv3 compliant directories
• XML Login Module - for use with the Cams XML user directory

Active Directory Login Module

You use this login module to access authentication credentials and group membership information stored in Microsoft Active Directory. Like any other directory servers, Active Directory can be configured to support virtually any schema. However, Microsoft has a strictly defined, proprietary schema that most sites use. Also, your schema will be different if migrated your from a Windows NT domain or started fresh with Active Directory. The Cams Active Directory login module provides support for the default Active Directory schema as shown in example 2, but is flexible to handle variations.

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

The Active Directory login module options values are:

• host - The DNS host name or IP address of the Active Directory server.
• port - The Active Directory server connection port (389 by default, 636 for SSL). 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 Activer Directory host is unavailable due to a network outage.
  NOTE: To prevent a Cams web agent authentication request timeout from ocurring, make sure the connectTimeout value is less than the connection.authentication.timeout value found in a Cams web agent's cams-webagent.conf file.
• baseDN - The base distinguished name for the user search. Always in the format cn=Users,dc=company,dc=com for Active Directory's default schema, where the values company 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).
• 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.
• domain - (Optional) The Active Directory domain to append to the username 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 username 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 list of one or more default roles separated by a comma to be added to each user session.

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 schema without modification. Example 4 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 4 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 4 - JDBC login module configuration for the sample user database

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

• jdbcDriver - The fully qualified Java class name for your database's JDBC driver.
• jdbcUrl - The JDBC URL used to access the database (see the JDBC driver documentation).
• jdbcUsername - (Optional) The username 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. The username entered by the user at login will be substituted for the "?". Any valid query for you 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.
• rolePreparedStatement - The SQL prepared statement used to select the user's groups and/or roles from the database. The username entered by the user at login will be substituted for the "?". Any valid query for you 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 list of one or more default roles separated by a comma to be added to each user session.

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 5
   

<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 USERNAME = ? "/>
  <option name="passwordColumn" value="PASSWORD"/>
  <option name="rolePreparedStatement" 
         value="SELECT ROLE FROM USER_ROLES WHERE USERNAME = ? "/>
  <option name="roleColumn" value="ROLE"/>
 </options>
</login-module-entry>

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

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

1. jdbcDriver - use the Jakarta/Commons PoolingDriver as shown in Example 5.
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 SunOne 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 6.

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

1. Authentication - The LDAP login module substitutes the username that the user enters when prompted for authentication against the {username} parameter in curely 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 username 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 specifiy 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 specifiy 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 Jetty test 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 acheive 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 sepecification 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 7 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 7 - 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 username 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 username 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.
• roleFilter - The filter to use to search for a users roles. The username 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 list of one or more default roles separated by a comma to be added to each user session.

XML Login Module

Example 10 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 username, 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 10 - 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 repostiory 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 list of one or more default roles separated by a comma to be added to each user session.

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. In the web or HTTP space, most webapps use form authentication, typically requesting a username and password for authentication. In this case you can use the Cams NamePasswordCallbackHandler, which takes a username 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 all require the callback handler to supply a username and password. These login modules work well with the NamePasswordCallbackHandler. However, Cams has a pluggable callback framework to associate custom callback handlers with login modules. If the NamePasswordCallbackHandler does not meet your needs, see Cams Callback Handlers to understand how to create a new one. For example, you may want to specify a third authentication credential in addition to username and password, such as the last four digits of a user's social security number or a pin.

Login Parameters

Login parameters are optional tags that help define the login configuration. As shown in example 11, the Cams policy server sends the camsLoginUrl value to a Cams web agent when an access check requires user authentication. The Cams web agent then redirects the user's browser to URL indicated by camsLoginUrl, which references an HTML form that:

1. Prompts the user for login credentials (e.g. the default Cams NamePasswordCallbackHandler requires form field values cams_cb_username and cams_cb_password for the username and password respectively.
2. POSTs the credentials to the login URL configured by the Cams web agent (/cams/login by default).

The value of camsLoginUrl can be an absolute or relative URL. Any web server with a Cams web agent can be used provided the web or application server is in the same Internet domain as the web or application server that made the original request.

<login-parameters>
 	<login-parameter name="camsLoginUrl" value="/cams/login.jsp"/>
</login-parameters>

Example 11 - Cams login parameters

NOTE: You must change camsLoginUrl to reference a login page deployed at your site. For example, IIS sites might use the default /cams/login.asp supplied with the Cams IIS web agent and Apache sites might use the default /cgi-bin/cams-login.sh supplied with the Apache 1.3/2.0 web agents. Cams login pages are provided as samples that contain the required parameters. You can customize them or create new login pages as required.

Customizing LoginException 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 12 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 12 - 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 13 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 13 - 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 an optional 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 your Cams enabled site with autologin enabled and an AUTOLOGIN cookie is presented, Cams web agents will proactively and 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.

The Cams AUTOLOGIN feature is considered 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 following steps are required to implement Cams automatic HTTP login:

1. Add a checkbox with name cams_cb_autologin_flag to the Cams login page that enables the user to select future automatic authentication.
   NOTE: The checkbox is normally presented with a label such as Remember Me.
2. Enable the Cams automatic HTTP login feature in your Cams web agents.
3. Enable and configure the Cams automatic HTTP 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 Cams web agents.

More details for each of these steps is provided below.

Configuring the Cams Login Page

The option to perform Cams automatic HTTP login for future authentications is normally presented to a user with a HTML 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 HTTP cookies that store encrypted passwords.

Example 14 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 14 - Adding the cams_cb_autologin_flag checkbox to a Cams login page

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

#
#--- Enable the Cams automatic login feature. The automatic login feature must
#--- be enabled on the Cams policy server as well, in order to use this feature.
#--- Consult the Cams policy server administration guide as well as the web
#--- agent documentation for more details.
#
cams.autologin.enabled=true

Example 15 - 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 HTTP 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 HTTP 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 16 shows the Cams automatic HTTP 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 16.

...
<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 16 - Enabling the Cams Auto Login 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 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 automatice 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: Blowfish, DES, and DESede
  (triple DES). 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.
• 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.

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 username, password and autologin_flag callback parameters that are sent from Cams login pages containing fields named:

• cams_cb_username
• cams_cb_password,
• cams_cb_autologin_flag

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

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

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

Example 17 - 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 web or application servers containing your Cams web agents.

To test automatic login, just login to your website using normal authentication credentials making sure your select Remember Me on the 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 website. 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.

Back | Next | Contents

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