Release 3.2

Cams Policy Server



Release Overview

Cams is a powerful web single sign-on and access management solution. When configured for use with Cams web agents, the Cams policy server provides centralized management of security for Apache andIIS web servers and J2EE application servers. This document includes information specific to this release of the Cams policy server.

System Requirements

  • Java JRE 1.6 or greater
  • 1GB system memory
  • 10MB disk space for software
Tested Operating Systems
  • Windows Server 2008/2012
  • Red Hat Enterprise 5/6/7
  • Sun Solaris 10/11
  • SuSE Linux 9/10
  • Other operating systems that support Java JDK SE 1.5 or greater
Tested User Directories
LDAP
  • CA eTrust Directory Server
  • IBM Directory Server
  • Microsoft Active Directory
  • Microsoft AD LDS
  • OpenDJ
  • OpenDS
  • OpenLDAP
  • Red Hat Directory Server
  • Sun ONE Directory Server
  • UnboundID Directory Server
  • Other LDAP v3 compliant servers
Databases (vendor supplies the JDBC driver)
  • IBM DB2
  • Informix
  • MSSQL
  • MSSQL
  • MySQL
  • Oracle
  • Postgres
  • Sybase
  • Other databases with a JDBC driver

Installation

The installation instructions assume that you:

  • are using and familiar with the target operating system: Windows or Linux/UNIX
  • have the J2SDK 1.6 or greater installed and configured or have downloaded Cams policy server for Windows or Red Hat Linux, which include a Java JRE

Before starting, make sure you have obtained license keys from Cafésoft for the Cams policy server. You can request evaluation license keys or purchase permanent license keys at:

http://www.cafesoft.com/

Cams policy server installation instructions are found in:

The Cams policy server includes the lightweight Jetty web server for testing a Cams installation. The installation document referenced above includes instructions on how to use it for testing. Once you complete testing, we recommend the following steps:

  1. To learn more about Cams terminology and architecture, see Cams Administrator's Guide - Introduction.
  2. To begin configuration of the access control rules and permissions, see the Cams Administrator's Guide - Integration Quick Start and Cams Administrator's Guide - Access Control Services.
  3. To learn about running the Cams policy server in a cluster configuration, see Cams Administrator's Guide - Policy Server Clustering Quick Start.
  4. To harden your Cams installation, see Cams Administrator's Guide - Hardening Cams.

Migrating

Migrating to Cams 3.2 from Cams 3.1

Cams 3.2 contains a significant enhancement to Cross DNS Domain Web Single Sign-on (CDSSO). The new components implementing these features require changes to your Cams policy server security-domain.xml file. If you previously configured Cams CDSSO, the settings will look familiar to you. The new Cams 3.2 CDSSO functionality also requires version 3.2 Cams web agents, though Cams web agents do not have any configuration changes for this feature.

WARNING: When migrating to the Cams policy server 3.2 release, we strongly recommend that you also upgrade to version 3.2 Cams web agents. Though the Cams 3.2 service protocols are compatible with Cams 3.1, the version 3.2 Cams policy server supports only the new Cams 3.2 Just-in-time CDSSO profile. Enabling the new CDSSO feature in a version 3.2 Cams policy server environment with version 3.1 Cams web agents will result in error messages and difficult to debug behavior.

To upgrade from Cams 3.1 to Cams 3.2 we recommend using your existing Cams 3.1 policy server configuration (referred to in these instructions as CAMS_HOME) and migrating the values from your Cams 3.1 security-domain.xml file into the new Cams 3.2 security-domain.xml file. You will also need to copy the new Cams 3.2 libraries.

Use the following steps:

  1. Make a backup of your Cams 3.1 deployment.
  2. Extract the Cams policy server 3.2 distribution to the temporary directory (referred as CAMS_3.2_TEMP_HOME).
  3. Copy the new Cams 3.2 libraries, README and ReleaseNotes.html into your Cams deployment:

    cp CAMS_3.2_TEMP_HOME/lib/* CAMS_HOME/lib
    cp CAMS_3.2_TEMP_HOME/README.txt CAMS_HOME
    cp CAMS_3.2_TEMP_HOME/ReleaseNotes.html CAMS_HOME


  4. Migrate customizations you have previously made from your backup CAMS_3.1_HOME/conf/domains/system/security-domain.xml file into the new CAMS_3.2_HOME/conf/domains/system/security-domain.xml file. If you configured the Cams 3.1 CamsHttpCDSSOAuthValve, do not migrate the configuration elements. However, many of the values can be transferred directly to the new Cams 3.2 StandardJITHttpCDSSOService configuration, which you can use to follow these instructions: Configuring Cams Cross DNS Domain Web Single Sign-On.
    NOTE: If you prefer, please send your Cams 3.1 security-domain.xml file to Cafésoft support and we will migrate values and configure StandardJITHttpCDSSOService for you.
  5. To upgrade your Cams web agents to Cams 3.2, we recommend:
    a) Java web agents - copy the libraries from the extracted Cams 3.2 download to replace the Cams 3.1 libraries; copy the new slo.jsp and slo.gif into the cams web application.
    b) IIS web agents - copy the libraries (dlls) from the extracted Cams 3.2 download to replace the Cams 3.1 libraries; ; copy the new slo.jsp and slo.gif into the library directory
    c) Apache web agents - use the installation script to manage the upgrade selecting the option to retain your existing cams-webagent.conf file. If you have made customizations to cams_login.pl, you'll want to backup and then restore this script after the managed upgrade.
  6. Restart your Cams policy server and web agents and test.

For more information on the design and configuration of the new CDSSO implementation, please see the Release 3.2.1 section below.

Migrating to Cams 3.1 from Cams 3.0

Cams policy server configuration files only require changes if new options are used in Cams 3.1. These can generally be integrated on demand as new features are used. However, all Cams login modules included in the distribution now use the MapCallbackHandler. You must reconfigure login-config.xml for each security domain replacing and NamePasswordCallbackHandler references with MapCallbackHandler:

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

WARNING: If you have custom login modules deployed at your site, you will need to refactor them to use the MapCallbackHandler. See the code examples for the standard login modules found in the Cams policy server documentation download.

NOTE: Enhancements are regularly made to the Cams web agents. You are recommended but not required to use the latest Cams web agent releases with Cams policy server 3.1. Cams policy server releases 3.0.70 and greater contain character encoding changes that require use of the most current Cams web agents to enable.

Migrating to Cams 3.0 from Cams 2.1

Existing Cams policy server 2.1 configuration files will work without modification in a Cams 3.0 environment. However, if you desire to use new functionality, you'll need to copy and paste the associated configuration values into the approriate files. To upgrade to Cams 3.0:

  1. Unzip or extract the Cams policy server 3.0 distribution to the directory of your choice.
  2. Rename or move the Cams 3.0 CAMS_HOME/conf directory to CAMS_HOME/conf_original
  3. Copy the entire CAMS_HOME/conf directory from your Cams policy server 2.1 deployment to the same location in Cams policy server 3.0.
  4. Copy the Cams policy server 3.0 DTDs from the CAMS_HOME/conf_orginal/dtd/* to CAMS_HOME/conf/dtd.
  5. Copy any libraries (such as a JDBC driver) that you may require from your Cams policy server 2.1 deployment to the same location in Cams policy server 3.0.
  6. For each Cams web agent, start with the new cams-webagent.conf file and migrate your customized value from the Cams 2.1 cams-webagent.conf into it. You may need to review and tune the regular expressions used for cross-scripting prevention.
  7. Review the code in the sample Cams 3.0 web agent login pages that implements the parameter cross-scripting feature and migrate similar functionality into your existing login page(s).

WARNING: Because of Cams protocol changes, Cams 3.0 web agents are NOT backwards compatible with a Cams 2.1 policy server. You MUST migrate to both the Cams 3.0 policy server and web agents simultaneously.

Release 3.2.11 Details

Date: August 1, 2013

This is an enhancement update to the Cams 3.2.10 policy server production release.

Improved Cams Policy Server Restart on Linux and Solaris

The Cams Policy Server now performs a restart appropriately via the initd_cams_linux.sh and initd_cams_unix.sh scripts distributed with the policy server. Previous versions of these scripts did not correctly wait until the current policy server instance was shutdown before starting a new instance, resulting in a server socket "bind" exception.

Release 3.2.10 Details

Date: June 29, 2013

This is an enhancement and bug fix update to the Cams 3.2.8 policy server production release.

Improved Cams Policy Server Shutdown

The Cams Policy Server now performs shutdown in a timely fashion even if remotely connected web agents are unable to respond or an input/output exception is thrown. In most cases, the policy server shuts down within 15 seconds.

XML Text Parsing Ignores Embedded Comments

The Cams policy server XML parser did not return the full text associated with an XML element if an XML comment node was embedded within the text element. The policy server XML parser now assembles the complete XML text data, omitting embedded comments before returning the data to the caller. This fixes bugs like the one reported by a customer when a commented out URL value before the desired URL value in an access-control-policy.xml file cause return of an empty string.

Release 3.2.8 Details

Date: February 14, 2013

This is a bug fix update to the Cams 3.2.7 policy server production release.

CDSSO Failure in Multiple Node Clustered Policy Server Environments

The new Cams Cross Domain Single Sign-On (CDSSO) implementation fails intermittently with error "No SSOContext for session id" in environments with two or more clustered policy server nodes. This problem was caused by incomplete handling of "sticky session" behavior between policy servers and web agents.

NOTE: if using CDSSO in a Cams policy server cluster with two more nodes, you must update policy servers to at least release 3.2.8 and web agents to releases on/after February 14, 2013.

Release 3.2.7 Details

Date: February 8, 2013

This is a bug fix and minor enhancement update to the Cams 3.2.6 policy server production release.

Automatic Login compatibility with new CDSSO Implementation

The Cams policy server "AutoLoginAuthValve" now excludes a Cross DNS domain Single Sign-On (CDSSO) login parameter from the generated AUTOLOGIN cookie. The new login parameter was added to support the new CDSSO scheme, but its inclusion in the AUTOLOGIN cookie was causing SSO to fail under certain cases.

NOTE: if using automatic login and CDSSO in the same environment, you must update your policy server and web agents to a release on/after February 8, 2013.

SQL Data Access Control Rule Support Callable Store Procedures

Previous versions of the SQL data access control rule supported calling of stored procedures from with SQL SELECT and UPDATE statements. With this update, you can now call stored procedures directly that return a single, scalar OUT parameter that indicates failure (0) or success (1). To call stored procedures, use the "{? = call dbo.myStatement()}" syntax, where the leading question mark declares the OUT parameter and the text in red is exactly as shown.

Release 3.2.6 Details

Date: December 19, 2012

This is the first Cams 3.2 policy server production release containing a significant redesign of Cams Cross DNS Domain Single Sign-On, new Single Log-Out functionality, updated LDAP libraries a corresponding LoginModules and ManagedSessionEventHandlers and various other bug fixes and enhancements.

Redesigned Cross DNS Web Single Sign-On (CDSSO) Implementation

The Cams policy server and web agents now support Just-in-time cross DNS web single sign-on (CDSSO) using an identity (IdP) and service provider (SP) paradigm. Support for single sign-on to multiple cookie domains is provided by new Cams policy server components and enhanced web agents.

The original Cams CDSSO design used a sequence of redirects to every registered cookie domain cookie provider to create the necessary Cams session cookies. On occasion, network latency would cause timeouts leaving the CDSSO sequence incomplete and users confused as the originally requested content was not displayed after successful login.

The new CDSSO design avoids this potential problem. After a Cams session is established within a designated IdP cookie domain, session cookies are automatically created for other SP cookie domains as users visit them, or just-in-time. If a user without an existing Cams session visits a SP cookie domain first, he is redirected to the IdP cookie domain to login, then redirected to the originally requested SP URL after successful login.

The Cams 3.2 CDSSO functionality is implemented by the following new components:

  1. A Cams policy server service (StandardJITHttpCDSSOService)
  2. A Just-in-time Cams policy server authentication valve (CamsJITHttpCDSSOAuthValve)
  3. A Cams policy server access control valve (CamsJITHttpCDSSOAccessControlValve)
  4. Cams version 3.2 web agents

Cams 3.1 CDSSO functionality was provided by the following components:

  1. A Cams policy server authentication valve (CamsHttpCDSSOAuthValve)
  2. Cams version 3.1 web agents

The new Cams 3.2 IdP/SP model protocol involves both authentication and access control requests. Though additional components are used, the main configuration settings are centralized to the Cams policy server StandrdJITHttpCDSSOService component. Support for cross DNS single logout is also now provided.

Please see Migrating to Cams 3.2 from Cams 3.1 in these release notes and Configuring Cams Cross DNS Domain Web Single Sign-On for configuration instructions.

New Cross DNS Domain Single Log-Out (SLO) Feature

This new feature works in conjunction with Cams CDSSO and the existing Cams logout service to close a Cams user session and delete Cams session cookies in all cookie domains. The functionality is provided by agent-specific scripts, which may be customized as needed.

NOTE: only a single script is needed to implement this functionality and example environment-specific Perl, JSP, and ASP.NET scripts ship with Cams 3.2 web agents.

Deprecated Active Directory and LDAP Login Module SSL Protocol Handler

With the inclusion of a default JSSE SSL protocol handler in JDK SE 1.5 and greater, deprecated Cams Active Directory and LDAP login modules no longer require the System properity java.protocol.handler.pkgs to be set to com.sun.net.ssl.internal.www.protocol. The Windows runcams.conf and Linux/UNIX runcams.sh files have been modified to exclude loading of this System property. The javax.net.ssl.trustStore System property is still required for deprecated Active Directory and LDAP login modules that are configured to use SSL. This property remains but is commented out by default. The effected login modules are:

  • ActiveDirectoryLoginModule
  • AESOActiveDirectoryLoginModule
  • AESOLdapLoginModule
  • AESOX509CertLdapLoginModule
  • LdapLoginModule
  • X509CertificateLdapLoginModule

These login modules no longer log a warning if the Java System property java.protocol.handler.pkgs is not found. No configuration change is required if you are using the deprecated login modules. However, we recommend you upgrade to the current UnboundID version of the deprecated login module.

UnboundID LDAP User Attribute Managed Session Event Handler

Added validation for the universe of know configuration parameters and the following new parameter:

  • includeUsersInRoles - (optional) A comma-delimited list of one or more user roles that, if supplied, a user must have at least one for this session event handler to attempt the search for attributes.

AESO UnboundID Active Directory Login Module

You use this login module with Cams AESO to confirm user identity and lookup group memberships stored in Active Directory. This login module improves upon the deprecated AESO Active Directory login module using the UnboundID LDAP SDK for Java for implementation, which enables additional features to be configured, such as:

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

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

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

New Cams Authentication Log File Callback Value Logging

This standard Cams Policy Server authentication logging valve now supports logging of callback values. This enables logging of site or environment-specific callback values (like a site identifier, user community identifier, etc), which maybe useful for debugging, reporting and analysis.

NOTE: specific private/sensitive callback values cannot be logged, like passwords, certficiates, etc.

Release 3.2.4-beta Details

Date: November 20, 2012

This release fixes a number of Cross DNS Domain Single Sign-On bugs and includes stability, performance and documentation enhancements.

Bug: Multiple HTTP Redirect Obligations added in some CDSSO-related access control responses

When multiple Cams security domains were used, both security domains enabled Cross DNS Domain Web Single Sign-On (CDSSO) and one security domain delegated access controls to another, the Cams policy server returned multiple HTTP redirect obligations to web agent. Web agents would honor the first HTTP redirect obligation and log an error message on the second.

The Cams policy server CDSSO Access Control Service now checks the security domain responsible for the access control response and adds an HTTP Redirect obligation only in the responsible security domain.

Bug: CDSSO SSOContext Parse Exceptions Under Heavy Load

Under heavy load the symmetric key cipher used to decrypt the cams_sso_context value reported "Bad Padding" and other decryption errors. The problem was caused by use of a single, non-thread-safe symmetric cipher instance by multiple concurrent worker threads. The Cams policy server SSO service has been enhanced with a dynamic pool of symmetric ciphers so that each worker thread requesting cams_sso_context decryption uses its own instance.

Bug: SSOContext Memory Leak

Expired SSOContext instances are now purged from the internal time-sensitive cache on all error conditions.

Documentation: Cams 3.1 to Cams 3.2 Migration Information

Details on migrating from Cams 3.1 to Cams 3.2 were added to this document.

Release 3.2.1-beta Details

Date: September 18, 2012

This release includes a significant redesign of cross DNS web single sign-on (CDSSO), which also now supports single logout. The release also includes other enhancements and bug fixes as documented below.

Redesigned Cross DNS Web Single Sign-On (CDSSO) Implementation

The Cams policy server and web agents now support Just-in-time cross DNS web single sign-on (CDSSO) using an identity (IdP) and service provider (SP) paradigm. Support for single sign-on to multiple cookie domains is provided by new Cams policy server components and enhanced web agents.

The original Cams CDSSO design used a sequence of redirects to every registered cookie domain cookie provider to create the necessary Cams session cookies. On occasion, network latency would cause timeouts leaving the CDSSO sequence incomplete and users confused as the originally requested content was not displayed after successful login.

The new CDSSO design avoids this potential problem. After a Cams session is established within a designated IdP cookie domain, session cookies are automatically created for other SP cookie domains as users visit them, or just-in-time. If a user without an existing Cams session visits a SP cookie domain first, he is redirected to the IdP cookie domain to login, then redirected to the originally requested SP URL after successful login.

The Cams 3.2 CDSSO functionality is implemented by the following new components:

  1. A Cams policy server service (StandardJITHttpCDSSOService)
  2. A Just-in-time Cams policy server authentication valve (CamsJITHttpCDSSOAuthValve)
  3. A Cams policy server access control valve (CamsJITHttpCDSSOAccessControlValve)
  4. Cams version 3.2 web agents

Cams 3.1 CDSSO functionality was provided by the following components:

  1. A Cams policy server authentication valve (CamsHttpCDSSOAuthValve)
  2. Cams version 3.1 web agents

The new Cams 3.2 IdP/SP model protocol involves both authentication and access control requests. Though additional components are used, the main configuration settings are centralized to the Cams policy server StandrdJITHttpCDSSOService component. Support for cross DNS single logout is also now provided.

Please see Migrating to Cams 3.2 from Cams 3.1 in these release notes and Configuring Cams Cross DNS Domain Web Single Sign-On for configuration instructions.

Deprecated Active Directory and LDAP Login Module SSL Protocol Handler

With the inclusion of a default JSSE SSL protocol handler in JDK SE 1.5 and greater, deprecated Cams Active Directory and LDAP login modules no longer require the System properity java.protocol.handler.pkgs to be set to com.sun.net.ssl.internal.www.protocol. The Windows runcams.conf and Linux/UNIX runcams.sh files have been modified to exclude loading of this System property. The javax.net.ssl.trustStore System property is still required for deprecated Active Directory and LDAP login modules that are configured to use SSL. This property remains but is commented out by default. The effected login modules are:

  • ActiveDirectoryLoginModule
  • AESOActiveDirectoryLoginModule
  • AESOLdapLoginModule
  • AESOX509CertLdapLoginModule
  • LdapLoginModule
  • X509CertificateLdapLoginModule

These login modules no longer log a warning if the Java System property java.protocol.handler.pkgs is not found. No configuration change is required if you are using the deprecated login modules. However, we recommend you upgrade to the current UnboundID version of the deprecated login module.

UnboundID LDAP User Attribute Managed Session Event Handler

Added validation for the universe of know configuration parameters and the following new parameter:

  • includeUsersInRoles - (optional) A comma-delimited list of one or more user roles that, if supplied, a user must have at least one for this session event handler to attempt the search for attributes.

AESO UnboundID Active Directory Login Module

You use this login module with Cams AESO to confirm user identity and lookup group memberships stored in Active Directory. This login module improves upon the deprecated AESO Active Directory login module using the UnboundID LDAP SDK for Java for implementation, which enables additional features to be configured, such as:

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

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

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

Release 3.1.10 Details

Date: December 15, 2011

This is an enhancement and bug fix release for all Cams policy server operating environments.

JdbcLoginModule and XmlLoginModule Configurable Character Encoding for Digest Passwords

The JdbcLoginModule and XmlLoginModule have been enhanced to support a configurable character set encoding option "charEncoding". If user passwords are stored in the RDBMS or XML file as "digest strings", this optional value causes the user entered password to be encoded in the specified character set before constructing the digest form of the password.

Some customer sites reported problems when user digest passwords were constructed in one character set (e.g. ISO-8859-1, Windows-1252, etc.) and Cams LoginModules used a different character set (e.g. UTF-8). The new configuration option enables the Cams environment to continue using the preferred default, portable UTF-8 character encoding while enabling digest password construction in another customer-preferred character encoding. If the new "charEncoding" value is not populated, then the environment default character encoding is used.

For more information, see the Cams Administrators Guide section on JdbcLoginModule and/or XmlLoginModule configuration options.

New UnboundID LDAP SDK 2.2 Library

The UnboundID LDAP SDK library has been updated from the 2.0.0 to the 2.2.0 release to take advantage of the latest enhancements and fixes. This new library resolves initial directory server connection issues and improves overall connection stability.

UnboundID Active Directory Login Module Regex Matching

A fix has been implemented for the UnboundID Active Directory Login Module, which was not executing role regex pattern matching code when configured.

Java Source Compiled to Version 1.5 Target

The Cams Policy Server java source code now compiles to version 1.5 byte code, which is compatible with Java virtual machine versions 5, 6, and 7. The Cams Policy Server will no longer run under Java virtual machines supporting only prior versions (Java 1.4, 1.3, 1.2, 1.1, 1.0).

This change was deemed a requirement to support the new UnboundID LDAP SDK 2.2 library, which uses Java language features supported under under Java byte code version 1.5 and later. If this change causes problems in your environment, consider upgrading to the latest Oracle/Java virtual machine (Java 6 or Java 7), or contact Cafésoft Support.

Release 3.1.6 Details

Date: April 13, 2011

This is an enhancement and bug fix release for all Cams policy server operating environments.

New UnboundID LDAP SDK Components

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

New Cams policy server login modules, services and examples implementing the UnboundID LDAP SDK for Java are now available. UnboundID provides all the functionality of components implemented using the Novell LDAP Classes for Java (JLDAP), with significant new features including:

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

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

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

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

Cams policy server components implemented using the UnboundID LDAP SDK for Java in this release include:

  • UnboundID LDAP login module - For authentication with LDAPv3 servers. See the Cams Administrator's Guide - Login Configuration for more information.
  • UnboundID Active Directory login module - For authentication with Active Directory. See the Cams Administrator's Guide - Login Configuration for more information.
  • UnboundID user attribute session event handler - For fetching additional user attributes to be stored in user sessions from LDAPv3 servers. See the Cams Administrator's Guide - Examples for more information.
  • UnboundID connection pooling service - For sharing connections to an LDAPv3 server. See the Cams Administrator's Guide - Security Domain Configuration for more information.
  • UnboundID Active Directory group name service - For retrieving Active Directory group names when the tokenGroups attribute is used in the UnboundID Active Directory login module. See the Cams Administrator's Guide - Security Domain Configuration for more information.

When migrating to these UnboundID components from the deprecated components, we recommend copying previous configuration values into the XML snippet provided in examples for the UnboundID components to ensure that parameters names are correct.

Deprecated Novell LDAP Classes for Java Components

The following login modules, services and session event handlers that use the Novell LDAP Classes for Java (JLDAP) have been deprecated:

  • com.cafesoft.cams.auth.login.module.ActiveDirectoryLoginModule
  • com.cafesoft.cams.auth.login.module.LdapLoginModule
  • com.cafesoft.security.engine.service.ActiveDirectoryGroupNameServiceImpl
  • examples.session.LdapUserAttributeManagedSessionEventHandler

You are encouraged to migrate to replacement components using the UnboundID LDAP SDK for Java when convenient.

Login Module Role Pattern Matching

Pattern matching of roles for login modules that use the rolesInACRLibrary option has been changed from a comma-delimited list of exactly match character strings to a regex pattern. For sites using a comma-delimited list, changing commas to the pipe ("|") character is sufficient. This option has also been renamed to roleRegexPattern. For example, change:

<option name="rolesInACRLibrary" value="role1,role2,role3"/>

to:

<option name="roleRegexPattern" value="role1|role2|role3"/>

You can alternatively define a regular expression to perform the match, which is useful when roles used in the Cams access control policy are numerous but may match a similar pattern. For example, the following regex matches all roles that start with cams:

<option name="rolesInACRLibrary" value="^cams.*$"/>

Enable login module debug to display information on role regex pattern match evaluations.

Administrator Email Notification

Cams policy server email notfication configuration parameters: cams.server.smtp.host, cams.server.smtp.from, and cams.server.smtp.to were not propagated to the configuration properties of the internal component that needed them. Consequently, messages related to exceeding Cams policy server concurrent session licensing were not delivered to administrators.

Cams administrators will now receive these messages using the configured properties if they are valid for the deployment environment.

Active Directory Login Module

If the connectTimeout option was not configured, a Java null pointer exception was thrown. If this configuration option is not supplied, the default connection timeout value of 3000 milliseconds is now used.

Release 3.1.3 Details

Date: February 1, 2011

This is an enhancement bug fix release for all Cams policy server operating environments.

Default UTF-8 Character Set Support for Files and Input/Output Streams

The Cams policy server JVM is now configured with startup parameter: -Dfile.encoding=UTF8, which causes configuration files and Cams message framework input/output streams to default to the UTF-8 character set. This enhancement aides customer environment where special characters are needed for user names, email addresses, etc. and ensures that character data read from configuration files is interpreted using the UTF-8 character set.

Customers with site-customized "runcams.sh" scripts (Linux/Unix) or "runcams.conf" file (Windows) are encouraged to add JVM startup parameter -Dfile.encoding=UTF8 to their files. Please see the files shipped with this version of the policy server for the exact file contents required.

Servlet Filter Web Agent in camstest Environment Updated

The Cams Servlet Filter web agent installed for use in the policy server "camstest" environment includes a number of fixed including support for selective secure Cams HTTP request header injection. See the Servlet Filter web agent version 3.1.0 release notes for more details.

Configurable Callback names for RsaSecurIdLoginModule

The callback names expected by the RsaSecurIdLoginModule were hard coded to username and password. New configuration options enable users to set the callback names:
  • username_cb_name - (Optional) By default, a username callback is expected. If the login form uses a different name for the field, then optionally configure it. For example, for cams_cb_uid use:

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


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

    <option name="password_cb_name" value="code"/>

No configuration change is required for customers using the RsaSecurIdLoginModule as previously supplied.

Release 3.1.0 Details

Date: December 1, 2010

This is a stability bug fix release for all Cams policy server operating environments. This release also contains significant enhancments for Windows operating environments including support for 32-bit and 64-bit Java Virtual Machines already installed in the operating environment and Oracle/Sun JRE 1.6 (32-bit), which is now packaged with the "cams-policy-server-jre" download for customers needing a Java virtual machine.

Fixed Java Thread Loss on Connection Timeouts under High Load

Under high load, short connection and/or response timeouts, or response timeouts due to connectivity timeouts from Cams policy server components to LDAP servers or SQL database servers, some threads associated with Cams message frameworks output streams sometimes blocked indefinitely. Eventually, enough thread resources were consumed to cause the Java virtual machine associated with the policy server to exit with an "OutOfMemoryError - unable to create new native thread".

The bug was caused by a combination of factors including insufficient timeout and exception handling, and invalid assumptions on the atomicity of Cams message framework connection startup state.

Oracle/Sun JRE 1.6 packaged with the Windows Policy Server "JRE" Download

The Cams policy server download for Windows including the Java Runtime Environment now ships version Oracle/Sun JRE version 1.6_022. This JRE replaces version 1.4 and includes significant performance, scalability, debugging, and functional enhancments.

Upgrade to Java Service Wrapper 3.5.6 Standard Edition

Cafésoft licensees the Java Service Wrapper to manage Cams policy server startup services on Windows. An upgrade of the Java Service Wrapper was required to support startup using the Java Service Wrapper on Windows 64-bit operating systems. This update also includes new features to monitor the Java Service Wrapper log file (found in CAMS_HOME/logs/console.log) for Java system errors and to detect thread deadlock conditions. By default, the Cams policy server on Windows will now use these new features to write a heapdump file and restart automatically if either a java.lang.OutOfMemoryError or thread deadlock condition is detected. Customers may also add other conditions and triggers as desired.

The upgrade required changes to the Windows command scripts used to startup the Cams policy server. The primary startup script remains runcams.bat, but is now accepts arguments to run the Cams policy server in a console window or as a service.

  • [no argument] - Usage: runcams [ console {JavaAppArgs} : start : pause : resume : stop :
    restart : install {JavaAppArgs} : update {JavaAppArgs} : remove ]
  • console - Runs an instance of the Cams policy server in a console window
    without an installed service. Enter control-C in the console window
    gracefully stop the Cams policy server. This command is useful during
    integration and when making configuration changes to view issues immediately
    in the console.
  • start - Starts the Cams policy server service. You may also use the
    Windows Services client or enter at the command line:

    net start CamsPolicyServer

  • pause - Pauses the Cams policy server service.
  • resume - Resumes a paused Cams policy server service. You may also use the
    Windows Services client or enter at the command line:

    net stop CamsPolicyServer

  • stop - Stops the Cams policy server service.
  • restart - Stops and then starts the Cams policy server service.
  • install - Installs the Cams policy server service (but does not start it).
  • update - Updates the Cams policy server service configuration. You must update
    the service if you change the location of the configuration, library or executable
    files.
  • remove - Removes the Cams policy server service.

If you are upgrading from a previous release of the Cams policy server installed as a service, use the update argument before starting the service. The following scripts are no longer supplied or used by the Cams policy server:

  • cams-service-install.bat
  • cams-service-remove.bat
  • shutdown.bat

For more information on the Java Service Wrapper, see:

http://wrapper.tanukisoftware.com/doc/english/download.jsp

NOTE: Customer may also upgrade to use the Java Service Wrapper Professional Edition, which adds support for e-mail notification and other other management tools.

Release 3.0.75 Details

Date: October 6, 2010

This is a minor bug fix and enhancements release.

Refactored Login Modules

The Novell JLDAP libraries have been updated to the June 30, 2009 release. This release is backwards compatible with existing login modules. The update includes a new LDAPConnection constructor with a timeout, which enabled refactoring of the getConnection() method in the ActiveDirectoryLoginModule, LdapLoginModule and AESOActiveDirectoryLoginModule. These classes now create LDAP connections more efficiently, especially when using SSL for LDAPS connections. No configuration changes are required to enable use.

All login modules now use the MapCallbackHandler, which was previously only used with the newer Cams AESO login modules. In addition to flexibly handling virtually any callback value type, the MapCallbackHandler also eliminates the requirement to configure a special purpose AutoLoginNamePasswordCallbackHandler when using Cams AUTOLOGIN feature.

A new efficiently option has also been added to the ActiveDirectoryLoginModule, LdapLoginModule and AESOActiveDirectoryLoginModule:

rolesInACRLibrary - (Optional) Limits roles that saved in the user session to a comma-delimited list of one or more roles defined in the access control rules library for this security domain. This option is useful when the role search returns many roles that are not used by the access control policy for the security domain.

Refactored LdapUserAttributeSessionEventHandler

The Novell JLDAP libraries have been updated to the June 30, 2009 release. This release is backwards compatible with existing LdapUserAttributeSessionEventHandler components. The update includes a new LDAPConnection constructor with a timeout, which enabled refactoring of the getConnection() method in the LdapUserAttributeSessionEventHandler. This component now creates LDAP connections more efficiently, especially when using SSL for LDAPS connections. No configuration changes are required to enable use. In addition, this component now detects if the LDAP connection fails before attempting to bind the connection.

Release 3.0.74 Details

Date: August 6, 2010

This is a minor bug fix and enhancements release.

Access Control Policy Supports new Response "reason" Codes

The standard Cams access control policy implementation now supports additional access control response reason codes indicating when the session referenced by an access control request session identifier is expired or closed. The new reason codes enable agents to flush the session if cached in the web agent's session cache. The reason codes associated with "granted" access control responses also enable agents supporting a new "proactive" automatic login mode to detect when the session identifier is no longer valid and attempt to create a new session via "proactive" automatic login.

NOTE: the new access control response codes are returned only to agents that have sent a new agent attribute with a date/time stamp value indicating the response codes are supported. This enables continued use of existing agents without support for new reason code handling to operate using this (and subsequent) version of the policy server.

Changed default value of cams.cookie.secure to false for agent in Jetty test server

The default value of servlet filter web agent configuration property cams.cookie.secure was changed from a default value of "true" to "false" so that Cams session cookies are sent by web browsers in the default Cams Jetty test environment. The value of this property was inadvertenly changed from "false" to "true" during feature testing for Cams secure cookies.

This bug effected Cams policy server version 3.0.71 in which it appeared that Cams authentication had failed because the Cams sesson cookie was not returned to the web browser when a non-SSL connection was used.

Release 3.0.71 Details

Date: June 23, 2010

This is a bug fix release for a Cams policy server "hang" when agents use illegal access control attribute identifiers derived from HTTP query parameters, HTTP request headers and/or HTTP cookie names.

Cams Policy Server Hang on 'Invalid Attribute Id'

When any of the following Cams attribute flags were enabled in Cams native web agents:

cams.attributes.http-param.enable=true
cams.attributes.http-req-headers.enable=true
cams.attributes.http-cookies.enable=true

certain query parameter names, HTTP request header names, and HTTP cookie names would result in illegal Cams attribute identifiers. For example, with HTTP query parameter attributes and HTTP request like the following:

GET http://www.mydomain.com/myservice?one+two+three=6

would result in the following Cams attribute identifier: 'urn:cams:1.0:names:action:http-param:one two three'

Because this value must be a valid Uniform Resource Identifier (URI) as defined by RFC 2386, the Cams policy server was detecting a URISyntaxException. The policy server message translator decoding the access control response was not properly handling this condition by draining the remaining request data, ultimately causing both the agent and policy server to block waiting for IO to complete and finally timeout. When this condition occurred for a requested URL where user authentication was required, the agent would redirect the users browser back the web site, where the condition would repeat.

The Cams message framework access control request message translator now logs a warning message if an invalid attribute identifier is received and access control request processing continues after discarding the invalid attribute.

Native agents now use a regular expression to validate all query parameter names, HTTP request header names, and cookie names before they are added to access control requests as attributes. The length of names is also validated and by default is limited to 128 characters. If a given name is invalid, a warning is written to the web agent log file and the attribute is excluded from the access control request. The following new configuration value shows the default regular expression used to validate query parameter, request header, and cookie names:

cams.attributes.name.validator.regex=^[a-zA-Z0-9\\-_]{1,128}$

This regular expressions limits name to 128 characters in length and the characters: a-z, A-Z, 0-9, - (dash), _ (underscore). NOTE: the two backslash characters are used to escape the special dash character, which is otherise interpreted within reqular expressions as a character or numeric range delimiter. Some additional characters may be valid, though you should consult RFC 2386 before making changes. The length limitation applies only to query parameter name, request header name or cookie name (e.g. "one two three") and not the resulting attribute id (e.g. 'urn:cams:1.0:names:action:http-param:one two three'). See the release notes for native agents for more details.

Release 3.0.70 Details

Date: October 20, 2009

This is a bug fix release supporting improved international character encoding/decoding. This Cams policy server release works in conjunction with changes implemented in all Cams web agents. We recommend updating Cams web agents to the latest version when using this policy server release.

Improved Character Encoding/Decoding Support

Various Cams services and protocols inconsistently handled string values like usernames, passwords, response messages, etc. containing non-ASCII (ISO-8859-1) characters. This resulted in one or more of the following problems:

  • Failed authentication for a valid username/password due to failed comparison of string values with different character encodings
  • Inconsistent display of Cams HTTP request headers and remote usernames in Cams web agent environments
  • Inconsistent results when a Cams policy server is started with different default character encodings
  • Inconsistent logged usernames in Cams policy server and Cams web agent environments

Cams now converts string values to UTF-8 format for use internally and converts back to the configured default character encoding in web agent environments.

Release 3.0.65 Details

This is a general customer release of the web agent supporting Cams Automatic Enterprise Sign-On (AESO) and HTTP URL "path parameter" removal.

Support for Cams Automatic Enterprise Sign-On (AESO)

Cams Automatic Enterprise Sign-On (AESO) enables transparent Cams user authentication by asserting an enterprise user identity established via some method outside of Cams. Cams AESO is generally used within a corporate Intranet to leverage an enterprise identity already established on the local area network via a Windows Domain Controller, Kerberos, NIS, One-Time-Password (OTP) tokens, etc. Using Cams AESO, you can avoid prompting users to login to Cams (e.g. using form-based login) after they've already logged into the network environment by other means.

Use of Cams AESO requires configuration settings in Cams policy servers and in web agent where authentication is handled. See the Cams Admistrator's Guide for details on how to configure Cams for use with popular enterprise authentication mechanisms.

For agent configuration properties related to AESO, look for property names containing "aeso" in the cams-webagent.conf file.

HTTP URL "path parameter" removal

Removal of HTTP path parameters enables simplification of Cams access control policies by normalizing all forms of a URL containing path parameters to the URL with path parameters removed. In most cases, HTTP path parameters are used much like query parameters: they provide extra processing parameters to web applications for conveying state or modulation of request handling.

The following fully-qualified resource identifier (HTTP URL):

http://host:80/foo/bar/index.html

reduces from each of the following URLs when path parameters are removed:

http://host:80/foo/bar/index.html;name
http://host:80/foo/bar/index.html;name=value
http://host:80/foo;name/bar/index.html
http://host:80/foo;name=value/bar/index.html
http://host:80/foo;name/bar;name2/index.html
http://host:80/foo;name=value/bar;name2/index.html
http://host:80/foo;name=value/bar;name2=value2/index.html
http://host:80/foo;name=value/bar;name2=value2/index.html;name3
http://host:80/foo;name=value/bar;name2=value2/index.html;name3=value3

Use of path parameter removal is highly recommended for customers that use "permissive" access control policies, which grant access to all resources by default (defaultBias="granted") except for those with stronger matching permissions. Without path parameter removal, every variation of a base URL containing path parameters is considered a different unique resource, so it is difficult to apply stronger permissions (like requiring user authentication) in a reliable way. In such an environment, users can easily escalate access to resource they might otherwise be denied access to or that they would otherwise need to authenticate before access is granted.

Release 3.0.48-beta Details

Cams policy server version 3.0.48-beta is a general beta release for all customers wanting to test Cams Automatic Enterprise Sign-On (AESO) functionality. The following bug fixes and enhancements have been included since limited beta release 3.0.47.

AESOActiveDirectoryLoginModule Bug Fix

When used with Apache 2.0 mod_auth_kerb (Kerberos login) and the username callback value was in format: username@DOMAIN, the login module failed to find the userPrincipleName attribute in the initial LDAP search. Consequently, login always failed.

The problem resulted from an uninitialized "fully qualified username" variable, which is used internally by the login module depending on the format of the arriving username callback value. This bug was introduced when adding support for UNC-formatted usernames (e.g. username\DOMAIN) for Windows Domain AESO support.

Release 3.0.47-beta Details

Cams policy server version 3.0.47-beta is a general beta release for all customers wanting to test Cams Automatic Enterprise Sign-On (AESO) functionality. The following enhancments have been included since limited beta release 3.0.44.

New AESO Login Modules

Cams AESO login modules now include:

  • AESOActiveDirectoryLoginModule
  • AESOJdbcLoginModule
  • AESOLdapLoginModule
  • AESOXmlLoginModule

A login module to support X.509 client certificate authentication with lookups to LDAP v3 compliant directory servers is still in the works.

New AESO Administrator Documentation

Detailed Cams AESO configuration documentation is now available for administrators in the Cams policy server downloadable documentation bundle. The new configuration documentation is located in the Cams Administrators Guide and follows the section on normal Cams Login Configuration.

New AESO-enabled Web Agents

Cams AESO support is currently limited to the following beta release native web agents:

  • Cams Apache 2.0/prefork Linux 32-bit web agent
  • Cams Apache 2.0/prefork Solaris 32-bit web agent
  • Cams Apache 2.0/prefork Solaris 64-bit web agent
  • Cams Apache 2.0/worker Linux 32-bit web agent
  • Cams Apache 2.0/worker Solaris 32-bit web agent
  • Cams Apache 2.0/worker Solaris 64-bit web agent
  • Cams Apache 2.0/winnt Windows 32-bit web agent
  • Cams Apache 2.2/prefork Linux 32-bit web agent
  • Cams Apache 2.2/prefork Solaris 32-bit web agent
  • Cams Apache 2.2/prefork Solaris 64-bit web agent
  • Cams IIS Windows 32-bit web agent

Cams AESO support for the Sun ONE 6.1 Solaris 32-bit web agent is postponed until required by a customer. Cams AESO support for Java-based web agents is still in progress and will be released in a separate beta release as soon as available.

Release 3.0.44-beta Details

Cams policy server version 3.0.44-beta is a limited beta release for customers waiting for Cams Automatic Enterprise Sign-On (AESO) functionality. Completed AESO administrator documentation is still incomplete and the documentation that does exist is undergoing a radical reorganization to improve clarity.

Support for Cams Automatic Enterprise Sign-On (AESO)

Cams Automatic Enterprise Sign-On (AESO) enables you to transparently authenticate users into Cams by asserting an enterprise user identity established via some method outside of Cams. Cams AESO is generally used within a corporate Intranet to leverage an enterprise identity already established on the local area network via a Windows Domain Controller, Kerberos, NIS, One-Time-Password (OTP) tokens, etc. Using Cams AESO, you can avoid prompting users to login to Cams (e.g. using form-based login) after they've already logged into the network environment by other means.

Support for Cams AESO is provided through the following new Cams components:

  • Cams AESO LoginModules - For this beta release two AESO LoginModule implementations are available: AESOXmlLoginModule and AESOActiveDirectoryLoginModule. Unlike normal Cams LoginModules, which generally require a user password, X.509 certificate, etc., AESO works by trusting an identity that was authenticated outside of Cams. Consequently, a password, certificate, etc., may not be available. See the "sytem" security domain configuration file: login-config.xml for AESO LoginModule configuration examples.
  • MapCallbackHandler, MapCallback - The authentication tokens used by native authentication methods vary widely by authentication type, web server type, implementations, etc. The Cams MapCallbackHandler and MapCallback classes provide flexible support any/all callback values sent via a Cams authentication request.
  • Cams Web Agent Enhancements - Cams web agents have been enhanced to detect and handle the HTTP requests associated with AESO. At the time of this beta release, limited agents have been released with AESO support. Contact Cafésoft Support for agent release status.

Release 3.0.41 Details

The Cams 3.0.41 contains a number of substantial enhancements and bug fixes including:

Automatic Login/Cross DNS Domain Single Sign-On Compatibility

The Cams Automatic Login feature did not work correctly when used in conjunction with Cross DNS Domain Single Sign-On (CDSSO). When both these features were enabled, the Cams AUTOLOGIN cookie was not created for some use cases. Also, Automatic Login did not trigger the CDSSO protocol. To improve compatibility of these features, the following enhancements were completed:

  1. In the Cams policy server security-domain.xml files that ship with the Cams policy server, the order of AuthValves for these two features was reversed. The XML configuration elements for the AUTOLOGIN valve must appear after the XML configuration elements for the CDSSO valve. If you choose to use these features together with an existing security-domain.xml file, be sure to change the order. The order is important because the CDSSO valve needs AUTOLOGIN login parameter values populated in the AuthResponse by the AUTOLOGIN valve.
  2. The CDSSO valve was enhanced to support optional propagation of AUTOLOGIN login parameters, which causes Cams web agents to create an AUTOLOGIN cookie in all CDSSO cookie domains when AUTOLOGIN is enabled and the user successfully logs in.
  3. All Cams web agents were enhanced such that login, logout, cross DNS domain single sign-on, and AUTOLOGIN are attempted before an access control check is attempted. This was necessary because presence of an AUTOLOGIN cookie during CDSSO handling caused CDSSO handling to halt and a new AUTOLOGIN to be peformed. The consequences of this change include: no more access control checks on the cams.login.uri, cams.logout.uri, cams.sso.uri. Any access control rules related to these URIs can be removed from access-control-policy.xml files.

When propagation of login parameters is enabled in the CDSSO auth valve causing creation of AUTOLOGIN cookies in all DNS cookie domains and the user explicitly logs out, only the AUTOLOGIN cookie in the current cookie domain is deleted. Since Cams does not currently support cross DNS domain single logout, there is no way to automate deletion of the AUTOLOGIN cookie or the CAMS_SID cookie in all cookie domains. This issue will be resolved when Cams cross DNS domain single logout is implement. At present, the only remedies are: manual deletion of the AUTOLOGIN cookie using your browser-specific GUI controls, changing the secret key values used for AUTOLOGIN, or simply not using the "propagateAutoLoginParameters" in the CDSSO valve.

Cross DNS Domain Single Sign-On Memory Leak

A memory leak in the Cams Cross DNS Domain Single Sign-On authentication valve was fixed. The leak occurred only when CDSSO was misconfigured or when the user's browser was not redirected to all Cams cookie providers due to a misconfiguration, network outage, interrupted HTTP request, etc.

This valve not removes internally cached SSO context objects used to monitor and control overall progress when CDSSO succeeds and when the context object has expired. A check for expired, cached CDSSO objects is executed no more than once every 60 seconds.

Improved StandardAuthValve Logging Support

Detailed trace log information for AuthRequest and AuthResponse objects was added. Simply add XML attribute debug="true" on the <auth-service ...> element. Detailed contents of the AuthRequest (with callback values masked) and AuthResponse are logged to the enclosing security domain's trace log file.

Active Directory Login Module Enhancements

The Active Directory Login Module has two new, optional configuration values:

  • useRoleSearch - (Optional) A value of "true" (default) indicates that a role search will be attempted [true|false]. This option is useful for sites configuring Cams for single sign-on (sometimes to a SharePoint or OWA server using Cams Windows Impersonation) and not role-based access control.
  • useDomainInRoleSearch - (Optional) A value of "true" (default) indicates that the optionally supplied domain used for authentication will be included in the role search filter's {username} substitution value [true|false]. This option is useful for sites that have migrated from an NT domain to Active Directory, where accounts may not have a userPrincipalName attribute. In such cases, configuring this value to false and using a role search filter that searches on the sAMAccountName attribute instead of the userPrincipalName is suggested.

LDAP User Attribute Managed Session Event Handler

Though Cams login modules support SSL/TLS connections to an LDAP server for secure binds, the previous LDAP User Attribute Management Session Event Handler example did not. Secure SSL/TLS LDAP server connections are now configurable using the similar values and the same keystore as a login module. Three new configuration options were added to specify the LDAP protocol version, a connection timeout and a flag for use of SSL/TLS. See the Cams Administrator's Guide - Examples appendix for configuration information.

Release 3.0.36 Details

The Cams 3.0.36 contains a number of substantial enhancements and documentation bug fixes including:

LdapLoginModule Directory-specific LoginException Handling

The LdapLoginModule now supports custom LoginException handling based on LDAP directory type. A new configuration parameter named "ldapServerType" enables you to declare the type of LDAP server associated with the LoginModule. Knowing the LDAP server type enables directory-specific mapping of error codes to specific LoginException classes, including:

  • javax.security.auth.login.AccountExpiredException
  • javax.security.auth.login.CredentialExpiredException
  • javax.security.auth.login.FailedLoginException
  • javax.security.auth.login.LoginException.

These specific exception classes are mapped to Cams AuthResponse reason codes, which can be used to implement custom workflow based on the Exception subclass.

Configuration parameter "ldapServerType" currently supports values: "ACTIVE_DIRECTORY" and "GENERIC", but will likely include other specific LDAP directory types in the future as needed. If the "ldapServerType" parameter is not specified, then a "GENERIC" LDAP server type is assumed. Additional declarative configuration enhancements supporting mapping of these LoginException classes to specific Cams AuthResponse reason codes will be available in a future release.

Exception codes, the match conditions may not match correctly for all releases of Active Directory and ADAM.

Cams Policy Server Linux/Unix Service Scripts Added

The Cams policy server distribution now includes shell scripts:

  • CAMS_HOME/bin/initd_cams_linux.sh
  • CAMS_HOME/bin/initd_cams_unix.sh

which can be used to start and stop a Cams policy server when the underlying Linux/Unix operating system is booted and shutdown. The same scripts can also be used to start/stop the Cams policy server by directly executing the /etc/init.d/cams script or by using the "service" command on Linux and Unix operating systems where it is available.

The Cams policy server installation instructions have been updated with instructions for installing one of these scripts and customizing it according to your needs. In addition, the documentation on Hardening Cams Security has been updated to include instructions for customizing these scripts to run the Cams policy server as a non-root user.

See the Cams Policy Server Installation documentation for more details.

Cams Client API for Java Released

The Cams Client API for Java enables you to create your own Cams agents for Java-based applications and container environments where Cams agents are not currently available. For example, this API enables you to create agents for standalone Java applications, Java-based web services containers, or Java-based application servers where Cafésoft supported web agents are not currently available.

The Cams Programmers Guide documentation has been updated to provide extensive information on use of the CamsClient API. This document is available online for access by the public. In addition, the downloadable Cams documentation package includes a CamsClientExample.java program that can be executed from a command line for testing. This example shows use of all current Cams services/protocols including: access-control, authentication, session-access, session-control, and ping and the code can be used as the basis for your own custom Cams agents.

Hardening Cams Security Instructions Updated for Linux/Unix

The instructions for Hardening Cams Policy Server Security under Linux and Unix systems has been updated to recommend running the Cams policy server as a non-root user. Though "hacking" the Cams policy server is not likely, running as a non-root account assures that if there is a breach, that the Cams policy server is not running as the highly privileged "root" user that might execute sensitive programs or access confidential files in the underlying operating system.

Cafésoft recommends that customers update exising Cams policy server installations under Linux/Unix to conform with the new security guidelines.

Access Control Response Log Codes Fixed

The following access control log file response codes were incorrectly documented or missing:

Reason code 15: was incorrectly documented indicating that access was denied because authentication was required. The correct reason is that the access control policy "default bias" was applied.

Reason code 16: was incorrectly documentated indicating that the access control policy "default bias" was applied. The correct reason is that authentication is required.

Reason code 22: was not documented. This code indicates that Access was denied because the authentication method is insufficient. This reason code is generally set by the Cam auth-acr when it is configured to require specific a specific strong authentication types, like X.509 certificates, RSA SecurID, etc.

Authentication Response Log Code Documentation Fixed

The following authentication log file response codes were missing:

Reason code 9: The account specified by the user has expired.

Reason code 10: The credential specified by the user has expired.

Release 3.0.34 Details

Cams 3.0.34 is a bug fix release, which contains the following fixes.

Active Directory Login Module Failed Authentication

The Active Directory login module was incorrectly returning a LoginException for normal, failed credential authentication requests. This resulted in the Cams web agent returning a HTTP 500 error instead of a redirect back to the login page specified by the camsLoginUrl in login-config.xml. The Active Directory Login Module now through a FailedLoginException for bad credentials, PasswordExpiredException for expired password and AccountExpiredException for account expired or locked out. As text parsing of the returned Active Directory server message is required for detection of PasswordExpiredException and AccountExpiredException codes, the match conditions may not match correctly for all releases of Active Directory and ADAM.

Release 3.0.33 Details

Cams 3.0.33 is a bug fix release, which contains the following fixes.

SQL Data Access Control Rule Case Sensitivity

Fixed a bug in which a mixed case SQL column name used to create an <sql-data-param-set> parameter (case insensitive) caused an SQLExeption because the parameter name (normalized to lower case) was being used to retrieve the column value. The problem was reported under MySQL and was likely caused by a bug in the associated JDBC driver, which is supposed to handle column names in a case-insensitive manner.

The JDBC result set handling within the code associated with <sql-data-param-set> was fixed to used the column name rather than the lower-cased parameter name.

Release 3.0.32 Details

Cams 3.0.32 contains relatively minor enhancements to support web servers running WebDAV and a way to perform access control based on HTTP request headers.

Support for use with WebDAV

The Cams policy server has been enhanced to support access control with Web-based Distributed Authoring and Versioning (WebDAV), a set of extensions to the Hypertext Transfer Protocol (HTTP 1.1) which allows users to collaboratively edit and manage files on remote World Wide Web servers.

  • The configuration for "http" resource types in cams.conf now supports WebDAV request methods: PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, and UNLOCK. Cams web agents were also enhanced to support the actions associated with these request methods. Environments where WebDAV clients are in use will no longer report "Invalid Resource Request" errors at the agent due to these previously unsupported actions.
  • Information for configuring Cams and the web server have been added as an appendix to the Cams Administrator's Guide.

Support for access control decisions using HTTP request headers

The Cams policy server and all Cams 3.0 agents have been enhanced to send HTTP request headers to Cams policy servers when configuration property:

cams.attributes.http-req-headers.enable=true

This is useful when you wish to apply different access control rules based on: the type or version of web client (user-agent), the referer associated with the request, etc. The HTTP request headers received can vary widely based on web browser, the web server, the requested URL, intervening proxy servers, etc., but the following are common for HTTP 1.1 requests:

  • Accept
  • Accept-Charset
  • Accept-Encoding
  • Accept-Language
  • Authorization
  • Expect
  • From
  • Host
  • Max-Forwards
  • Proxy-Authorization
  • Range
  • Referer
  • User-Agent

A more complete list of standard HTTP request headers and their meanings is available in the HTTP 1.1 specification. To send HTTP request headers with access control requests, you must enable the property documented in the agent's cams-webagent.conf file. Cams web agents cannot send Cams HTTP request headers, because they are generally injected into the HTTP request after access control is completed. If Cams HTTP request headers were sent via an upstream Cams Web Agent, they are excluded from the headers sent with access control checks.

Cams HTTP request header attribute names are normalized to lower case and belong to the "urn:cams:1.0:names:environment:http-req-header" category. For example, the "user-agent" HTTP request header name can be refererenced (usually within a Cams Attribute Access Control Rule) as a Cams attribute using: "urn:cams:1.0:names:environment:http-req-header:user-agent".

Cams 3.0.31 Release Details

Cams 3.0.31 contains relatively minor enhancements to the general Cams 3.0 policy server release, including:

Distribution available in RPM Format

The Cams policy server is available in a "RedHat Package Manager" (.rpm) file format for the Linux/i386 architecture.

  • The RPM package name is "cams-policy-server" and is installed in directory /var/cams by default, but the destination directory can be customized by using the --prefix command line option available with the rpm command.
  • The package includes the Sun Java Runtime Environment version 1.4.2 in a "jre" subdirectory.
  • The .rpm file also installs the Cams policy server as system service that is started automatically when the hosting computer system is started and stopped when the system is shutdown. The shell script that start/stops the Cams policy server is installed in file /etc/init.d/cams
  • On systems supporting the 'service' command, the Cams policy server can be started using: service cams start and stopped using: service cams stop
  • Information about the installed cams-policy-server RPM package can be obtained using command: rpm -iq cams-policy-server
  • When the Cams policy server package is erased (removed) using RPM command: rpm -e cams-policy-server configuration files that have been modified are renamed with a .rpmsave suffix. Added configuration files (like cams-license-keys.xml) are left intact as are any log files written to the logs directory. This enables fairly straight forward updates to a Cams policy server installation.

Cams 3.0.26 Release Details

Cams 3.0.26 contains relatively minor enhancements to the general Cams 3.0 policy server release, including:

Configurable Cams Session Cookie Domain Depth

This enhancement applies to the Cams ServletFilter Webagent installed in the jetty web server that is delivered with the Cams policy server in directory CAMS_HOME/jetty. All other Cams webagents have been enhanced to support this functionality and are currently available for download from www.cafesoft.com.

  • Enhance flexibility was added for the cookie domain associated with Cams session cookies. An optional, comma-separated list of special DNS top-level domains (TLDs) can be configured using cams-webagent.conf property cams.cookie.domain.special.tlds, which allows Cams session cookies with cookie domain of depth of 2. For example, if the TLD us is in the list, then a cookie domain of .foo.us is valid. If a given host's TLD is not in this list, then its cookie domain will have a default depth of 3. For example: www.bar.foo.us will have a cookie domain of .bar.foo.us. The default special DNS top-level domains used if this value is not supplied is:

    aero,biz,com,coop,edu,gov,info,int,mil,museum,name,net,org,pro,mobi,us,eu,at,cc,de,bg,tv,bz

    NOTE: Use of this list prevents corner cases where a Cams session cookie with a depth of 2 might be shared by a browser to unintended sites. For example, some countries such as the United Kingdom often use domain names that end with domains such as .com.uk and .gov.uk. If a Cams session cookie were created with a cookie domain such as .com.uk, then it could be unintentionally shared to other sites that end with this cookie domain. Some web browsers (e.g. Microsoft Internet Explorer version 7 and later) will not send a cookie with cookie domain depth 2 for non-special top level domains).

  • An optional, comma-separated list of cookie domains configured using property cams.cookie.domain.mapto.longest limits Cams session cookie scope to an arbitrary DNS subdomain. The cookie domains in this list are tail matched against the receiving web server's host name and the longest matching cookie domain is used for the Cams session cookie. For example, using setting:

    cams.cookie.domain.mapto.longest=.d3.d2.d1.com

    a successful login to web server host www.d3.d2.d1.com will create a Cams session cookie with cookie domain .d3.d2.d1.com. Web browsers will send such a Cams session cookie to any host in cookie domain .d3.d2.d1.com, but not to a broader cookie domain like .d2.d1.com.

Cams 3.0 Release Details

Cams 3.0 contains many enhancements and fixes. Though the Cams policy server has changed, many of the significant Cams 3.0 changes are found in the Cams web agents. Though some of those changes are referenced here, please see the release notes included in each Cams web agent for more complete information.

1. Authentication Services

  1. Added the ability to add obligations to a Cams authentication response, which is useful for redirecting Cams web agents to different URLs based on fine-grained authentication failure and success. Obligations can only be added to the authentication response programmatically.
  2. Internal authentication requests were modified by adding an additional method: removeCallbackValue(String name). This change will not affect users as this method should only be called on the server side.
  3. Corrected a bug in the AuthMessageTranslator3_0 class. The translator was always reporting that the authentication response contained at least one obligation even when no obligation existed.
  4. Added a new abstract BaseAuthenticationValve. This valve is designed to eventually serve as the base implementation for all authentication valve's that perform authentication. Therefore, it's not fit for an authentication valve that does diagnostic or logging type functions. The user will not experience a change in functionality as the previous authentication valves do not extend this valve.

2. Login Modules

The following new login modules and enhancements to existing login modules have been made.

  1. JDBC Login Module - Has new optional tags for a passwordExpiredPreparedStatement and an accountExpiredPreparedStatement that can be used to determine if a user's password or account have expired.
  2. RSA SecurID Login Module - Provides secure, strong authentication using one-time password generated by RSA SecurID cards, key fobs or disconnected SID800 tokens.
  3. VASCO Digipass Login Module - Used with the VASCO Vacman controller software to verify one-time VASCO Digipass authentication credentials with associated user profiles stored in a relational database such as Oracle, DB2, Microsoft SQL, MySQL, Sybase or any other database with a JDBC driver.
  4. X.509 Certificate LDAP Login Module - Supports client X.509 certificate authentication when submitted to the Cams policy server for authentication by a Cams web agent. Cams web agent are enabled using cams-webagent.conf configuration property cams.login.x509.cert.enable=true. When this option is enabled and an HTTP request is intercepted by the Cams web agent to the configured Cams login URI (e.g. /cams/login), it will populate a Cams callback value named x509_client_cert with the PEM-encoded client certificate if it is available. SSL support must be provided by the web server and must be configured to make the client certificate available to the Cams web agent module. If the client certificate is present, the Cams web agent sends the client X.509 certificate to the Cams policy server as one of possibly many authentication tokens, where a suitably configured login module can verify the certificate and authenticate the user. A sample X.509 Certificate LDAP Login Module is provided for use with X.509 certificates stored in an LDAP server such as Sun ONE Directory Server. The Cams Jetty test web server includes a self-contained X.509 client certificate test environment that uses a Java JKS key store. See CAMS_HOME/jetty/etc/x509/README.txt for complete configuration instructions.

See Cams Administrator's Guide - Login Configuration for more information.

3. Cross DNS Domain Web Single Sign-On

Added components to support cross DNS domain web single sign-on (CDSSO). The Cams web agent works in conjunction with the Cams policy server and other Cams web agents using an HTTP redirect protocol to establish a Cams session cookie for each Cookie Domain configured within an SSO environment. CDSSO is controlled and configured on a security domain by security domain basis with a new CDSSO authentication valve component. See the Cams Administrator's Guide - Login Configuration: Configuring Cams Cross DNS Domain Web Single Sign-On, for more information.

4. Windows Impersonation

Windows impersonation enables a server application to temporarily be the client to access secure Windows resources. The Cams IIS web agent uses this feature to enable just in time sign-on (JITSO), where Cams authenticated users are granted single sign-on access to homegrown and commercial web applications that require Windows authorization. This is especially useful to extend Cams single sign-on services to Microsoft web applications such as Outlook Web Access (OWA) and SharePoint Portal Server (SPS). With Cams JITSO the user name and password credentials used to authenticate a user with Cams are saved in the user's Cams policy server session and then reinserted into each HTTP request by the Cams web agent as it arrives at the web server, or just in time. The following describes the Cams JITSO using HTTP Basic Authorization header insertion with IIS sequence:

  1. On successful Cams user authentication, the user name and password are saved by a Cams login module (usually the Active Directory login module).
  2. On Cams session creation, a Cams policy server managed session event handler retrieves the saved credentials, formats a standard base-64 encoded HTTP Basic Authorization header value and adds it to the user session for access by Cams web agents.
  3. When an authenticated user accesses an HTTP resource protected by a Cams IIS web agent with HTTP Basic Authorization header insertion activated, the Cams IIS web agent checks a list of URI prefixes to determine if HTTP Basic Authorization header insertion should be attempted. If the URI matches and the user has the specified session value, then a HTTP Basic Authorization header is added to the HTTP request.
  4. During the ISAPI authentication processing stage, the Cams IIS web agent retrieves the HTTP Basic Authorization header, base-64 decodes it and sets the user name and password. If these credentials correspond to a valid Windows user, then IIS will impersonate that Windows identity for the remainder of the HTTP request.

5. Secret Key Cryptography

Secret key encryption was enhanced to support the AES (Advanced Encryption Standard) algorithm with a key length of 16 bytes (128 bits). AES was invented by two Belgian cryptographers, Joan Daemen and Vincent Rijmen and was adopted as an encryption standard by the U.S. government in 2002. AES was announced by National Institute of Standards and Technology (NIST) as US FIPS PUB 197 (FIPS 197) in November 26, 2001 after a 5-year standardization process. It uses a 16, 24, or 32 byte key and a 16 byte initialization vector, though Cams supports only the 16 byte US exportable key length. Performance of AES is excellent compared with DESede (Triple DES).

6. Session Management Enhancements

  1. The Cams policy server's session manager service has been modified to allow for ManagedSessionEventListener objects to be added/removed. This replaces the previous mechanism of adding/removing ManagedSessionEventHandlers. This will not affect any custom code written that uses the ManagedSessionEventHandler interface.
  2. A new SessionException object was added to the Cams API. It replaces two versions of the same exception that resided in internal Cams libraries.

7. Additional Services Enhancements

  1. An RMI registry service was added to the Cams policy server, which allows instantiation of an RMI registry on a specified port that is configured in cams.conf. This functionality is useful to implement server-based RMI objects that provide administrative services to RMI clients, such as verifying if a user already has a session on a Cams policy server.
  2. An RMI registry proxy server was added to the Cams policy server. This service provides a central access point for all RMI-based remote objects made available by the Cams policy server.

8. Access Control Rule Enhancements

The SQL data constraint rule DTD has been relaxed to allow for rules instances that don't require <sql-data-param-sets> elements.

9. Third-party Licenses

A single file with third-party licenses for all open source used in the Cams policy server and Cams web agents has been included in CAMS_HOME/THIRD_PARTY_LICENSES. A CAMS_HOME/public directory includes source code for third-party license that require that the associated source code be included with binary distributions.

10. General Cams Web Agent Changes

  1. A new Cams Tomcat 5.5 web agent has been added with this release. This web agent has also been tested and verified to work with the JBoss Web Server (in addition to the JBoss Application Server with Tomcat 5.5).
  2. Cams Apache 1.3 web agents for Linux and Solaris are no longer supported with this release.
  3. Cams web agents now use HTTP 500 general server and 403 forbidden error responses instead of redirects to Cams error or denied pages. This includes removal of all hard coded error pages that would previously display if a Cams web agent could not connect to a Cams policy server or for initialization errors.
  4. Cross site scripting and code injection attack protection is now available on user login via parameter validation, which is enabled by default. Any/all parameters sent to the Cams web agent during user authentication can be validated against a parameter-specific white list pattern implemented using a regular expression. Additionally, the sample Cams login pages have been enhanced to protect against cross site scripting (XSS) and other code injection attacks.

NOTE: Please see the release notes specific to each Cams web agent for more detailed information.

Cams 2.1 Release Details

Cams 2.1 contains many new and exciting features and internal fixes. This section documents the changes. If you are migrating to Cams 2.1 from a previous release, see Migrating to Cams 2.1 from a Previous Release.

The highlights of the 2.1 release include:

1. New Cams Access Control Rules

Four new stardard Cams access control rules have been added. Please reference the the Cams Administrator's Guide - Access Control Policy Tag Reference for complete information.

Attribute-based Access Control <attr-acr>

Cams 2.1 includes flexible and extensible support for access control based on Attributes. A new access control rule provides if-then-else style matching of access control requests based on the requested resource, actions, user identity and many other values. If a given access control request matches a set of conditions, then another referenced access control rule associated with those conditions is evaluated to determine if access is granted or denied.

All existing access control request values, including the resource identifier, resource action(s), user remote address, user identity, etc. are available as attributes on which to base access control decisions.

Cams Web Agent Enhances for Attribute-based Access Control

Cams web agents also now support use of HTTP query parameters as attributes for access control decisions, which enables protection of dynamic web applications based on:

  • The existence or absence of specific parameters
  • Valid combinations of parameters and their permissible values

For example, if a web application requires three HTTP parameters: report_type, report_period and report_format; where:

  1. report_type may have values: sales or cashflow
  2. report_period may have values: annual or monthly
  3. report_format may have values: html or pdf

then access can be denied if an invalid parameter value or combination is specified. Also, the access control rule might be setup so that only authenticated users with the Sales role are granted access to sales report types, users with the Executive role are granted access to all report types, and everybody else is denied access. These HTTP parameters can be communicated as query parameters:

http://www.mycompany.com/reportmanager?report_type=sales&report_period=annual&report_format=html

Obligations Access Control <obligations-acr>

You can now configure access control policies to communicate obligations (or actions) to be fulfilled by Cams web agents. For example, Cams web agents have been enhanced to support HTTP redirect obligations received from a Cams policy server. If a resource requested by a user requires special processing (like user registration), an access control policy can now instruct the Cams web agent to redirect to the URL where membership information can be entered.

SQL Data Access Control <sql-data-acr>

You can use SQL data access control rules to ensure the existance or completeness of required SQL database values (constraints). Each SQL constraint is evaluated and access is granted if all constraints are fulfilled. If any constraint is not fulfilled, then access is denied. One or more optional data parameters may be supplied for evaluation, each of which may contain parameter values that can be referenced from SQL statements. This provides flexible support for context-sensitive SQL statements based on user identity and other request-specific values. For example, you might have a requirement to tranactionally capture user profile data before granting access a high-value content report.

Authentication Method Access Control <auth-method-acr>

You can now distinguish the method of user authentication in an access control policy rule. For example, you might have auto login enabled on your site but desire to require password authentication to access certain resources.

The Cams login module implementations are responsible adding an authentication method to the user sessions. A wide range of industry standard authentication methods are available for use. Currently, standard Cams login modules support the PASSWORD and AUTOLOGIN authentication methods.

2. Multi-homed Support for Cam Policy Server Cluster Nodes

The Cams policy server now requires a command line property (cams.server.bindaddr=IP address) that enables it to bind to one of many possible IP addresses assigned to the local computer system. This enables a single multi-homed system to host multiple Cams policy servers within a cluster, each listening on a different IP address. This feature also ensures that the Cams policy server will be listening for Cams web agent connections only on the specified IP address and not on all IP addresses assigned to a host.

For evaluation purposes, the default value of cams.server.bindaddr is set to 127.0.0.1, which enables Cams web agents to only connecting from the localhost. To enable Cams web agents to connect from remote hosts, you'll need to change this value to the licensed IP address specified in your cams-license-keys.xml file.

Although use of a single system to host multiple Cams policy server cluster nodes is not recommended for production environments, it is useful for QA or pre-production environments whose purpose is to test configuration changes.

For more information on assigning the bind IP address for a Cams policy server, see the Cams Administrator's Guide - Integration QuickStart.

3. Support for Automatic HTTP User Login

An optional authentication valve is now available for the Cams policy server authentication service, which enables transparent user authentication (login) via a persistent HTTP cookie. This feature must be enabled and configured on a security domain by security domain basis and enabled in Cams web agents. It is implemented by:

  1. Adding a checkbox with name cams_cb_auto_login to the Cams login page that enables the user to select future automatic authentication.
    NOTE:
    The checkbox is often presented using a description like Remember Me.
  2. When the checkbox is selected and the user's login credentials are posted to a Cams web agent the value of cams_cb_auto_login is sent along with all other authentication tokens.
  3. If user authentication is successful using whatever login modules are configured for the security domain's login-config-entry and the security domain's authentication service has been configured with the auto authentication valve, then a persistent HTTP auto login cookie is sent to the user's browser. The cookie will have a name like: CAMS_AUTO_LOGIN_<clustername>_<sdname> where <clustername> is the configured Cams cluster name and <sdname> is the security domain name for which authentication succeeded. The value of the cookie is encrypted using parameters specified in the security domain-specific auto authentication valve.
  4. On future visits by the user, if authentication is required and the Cams auto login cookie is available, the Cams web agent will attempt to authenticate the user. If automatic authentication fails, the auto login cookie is deleted.
  5. If the user is provided with a logout option on your site and selects it, the current Cams user session and the auto login cookie are deleted.

The Cams auto login cookie has a configurable expiration period (in days) and the user's browser will automatically delete the cookie once the expiration date/time has been passed. Administrators may also force deletion of auto login cookies by changing the secret key parameters used to encrypt the auto login cookie value. Auto login cookies that cannot be decrypted by the auto login valve will be deleted.

For more information, see the Cams Administrator's Guide - Configuring Automatic HTTP User Login.

4. Case-Sensitive Resource Evaluation

Some web servers and their underlying operating systems provide case-insensitive access to resources. Because Cams access control policy evaluations were always case sensitive, it was very easy to create an access control policy security hole on case-insensitive servers. To prevent this, a new option has been added to the resource-pattern XML element in access-control-policy.xml: ignoreCase="true|false". If not specified, the default behaviour is false, resulting in case-sensitive URI pattern matching.

NOTE: We strongly suggest that customers using Cams with IIS review their current access control policy to determine if there are any case-sensitive security holes.

5. Multiple Juxtaposed Slashes

Previously, if Cams encountered multiple juxtaposed slashes in a URI a security error would be reported. This was to prevent potential security holes where Cams matches a URL such as:

http://www.mycompany.com/mysecure//resource.html

character for character but some web servers would resolve it to:

http://www.mycompany.com/mysecure/resource.html

Rather than report an error, Cams now reduces two or more juxtaposed slashes to one if found in the URI.

6. Miscellaneous

Item Description Notes
Secure LDAP Cams now support SSL/TLS for connections between the Cams policy server and LDAP or Active Directory servers See the Cams Administrators's Guide - Hardening Cams - Using SSL when accessing LDAP user directories for complete information on how to configure support.
New JLDAP library Cams now uses a new implementation of jldap.jar, which is used by the LDAP and Active Directory login modules. If you have a custom LDAP login module (including ActiveDirectory), you made need to change it to support the new library API.
New JDBC Connection Pooling Implementation A new Cams JDBC Connection pooling implementation has been added to provide more reliable support for Connection validation and pool shrinkage.

Use of the pre-Cams 2.1 connection pooling service:

com.cafesoft.security.engine.service.JdbcConnectionPoolServiceImpl

should transition to use of service class:

com.cafesoft.security.engine.service.JakartaJdbcConnectionPoolService

Configuration properties for the new service differ from the old service, so reconfiguration in security-domain.xml is required. See the Cams Administrator's Guide - JDBC Connection Pooling for configuration information.

Login failure redirect to login page Login failures are now redirected to a the configured login page Login failures previously redirected to the configured Cams error page. Beginning with Cams 2.1, login failures resulting from the Cams login module throwing a FailedLoginException now request the Cams web agent to redirect the user's browser to the configured Cams login page again. Sample Cams login pages now include logic to display a cams_login_failed_message query parameter if it exists.
Login module configuration option changes Configuration options for all standard login modules are now more consistent

Options such as specifying default roles to use and whether to allow use of empty passwords or not are now universally supported in all standard Cams login modules.

The LdapLoginModule no longer supports the adminUser, adminPassword or passwordValidationMethod options. We determined that no Cams sites benefited from these options so we simplified the implementation.

Migrating to Cams 2.1 from Cams 2.0

Existing Cams 2.0 configuration files will work without modification in a Cams 2.1 environment. However, please carefully review the information below to determine how it might apply to your site.

You can choose one of two strategies for the migration:

  1. Move cams.conf and security domain configuration files from your previous Cams policy server to the new Cams 2.1 policy server and make any required migration changes as defined below.
  2. Copy Cams 2.1 policy server libraries into your existing Cams policy server installation and make any make any required migration changes as defined below.

We recommend the first option as it will ensure that you have the latest changes in all of your Cams policy server files. If you choose the latter, you must minimally copy all CAMS_HOME/lib files from the Cams 2.1 policy server release into your current Cams policy server configuration. The same options and recommendations apply to Cams web agents (see the release notes included with each Cams web agent for more information).

NOTE: If you are migrating from Cams 1.5, please see Cams 2.0 Release Details first.

  1. You should specify the bind address for each Cams policy server, especially if more than one IP address is assigned to the system. On Windows, open CAMS_HOME/conf/runcams.conf. On Linux/UNIX, open CAMS_HOME/bin/runcams.sh. You'll find the name/value pair:

    -Dcams.server.bindaddr=127.0.0.1

    Set this value to the server assigned IP address you want to use with the Cams policy server. For more information, see the Cams Administrator's Guide - Integration Quick Start and Cams Administrator's Guide - Integration Quick Start.

  2. To use all new access control rules, change from the reference in the access control policy to the 1.3 DTD in access-control-policy.xml:

    <!DOCTYPE access-control-policy SYSTEM "http://cafesoft.com/access-control-policy_1_3.dtd">

  3. The Cams 2.1 policy server now supports both the Cams 2.0 and 1.0 access control protocols. Cams 2.1 web agents initiate access control requests using either version of the protocol (2.0 by default). To ensure you can take advantage of all Cams 2.1 features you should configure your Cams web agents to use the Cams 2.0 access control protocol. To do so, see the Cams 2.1 web agent release notes for changes you must make to cams-webagent.conf. Alternatively, use the new Cams 2.1 web agent cams-webagent.conf file and migrate your site specific values into it.

  4. Authentication failures caused by a invalid credentials (user name or password) will now force a redirect back to the login page, instead of the error page. The redirect is sent with a message as a query parameter, which can optionally be displayed. See the Cams Web Agent Guide - Scripts document, or the reference login page included with each Cams web agent for more information.

  5. If you are using connections to an SQL database for user authentication or within custom access control rules, you should be using JDBC connection pooling. Use of the pre-Cams 2.1 connection pooling service:

    com.cafesoft.security.engine.service.JdbcConnectionPoolServiceImpl

    should transition to use of service class:

    com.cafesoft.security.engine.service.JakartaJdbcConnectionPoolService

    Configuration properties for the new service differ from the old service, so reconfiguration in security-domain.xml is required. See the Cams Administrator's Guide - JDBC Connection Pooling for configuration information.


  6. (Optional) To enable Cams automatic login, change callback handler reference in login-config.xml to:

    com.cafesoft.cams.auth.callback.AutoLoginNamePasswordCallbackHandler

    Enable the Cams automatic login authentication valve in security-domain.xml and configure the required values:

    <param name="enabled" value="true"/>
    <param name="algorithm" value="Blowfish | DES | DESede"/>
    <param name="key" value="secret key"/>
    <param name="iv" value="initialization vector"/>
    <param name="expiration" value="Number of days"/>
    <param name="suffix" value="any random value"/>

    NOTE: You can generate the key and iv using either the CAMS_HOME/bin/secretKeyGen.bat/sh scripts or the web application in the Jetty test server.

    Set the following new property in each cams-webagent.conf:

    cams.autologin.enabled=true

    Include the cams_cb_autologin_flag auto login in the login page. This is usually implemented as a Remember Me checkbox like:

     Remember Me

NOTE: Cams 2.1 web agents are backwards compatible with a Cams 2.0.20 policy server. We strongly encourage you to upgrade both the Cams policy server and web agents to the Cams 2.1 release. However, should you desire to continue to use your Cams 2.0.20 policy server, please contact Cafésoft support for instructions.

Cams 2.0 Release Details

The highlights of the 2.0 release include:

1. Cams Policy Server Clustering

Cams 2.0 policy servers may now be deployed in clusters of one or more servers, enabling policy server failover, recovery, and load balancing. Cams 2.0-compliant agents must be deployed,which implement the required failover, recovery, and load balancing mechanisms. A summary of configuration changes is provided below.

Cams Policy Server Registration

Each Cams policy server must now have a registration file in the CAMS_HOME directory. The default policy server registration file is named: cams-reg-default.conf and is recommended only for clusters of one policy server. When more than one policy server is deployed in a cluster, the naming convention is: cams-reg-<IP address>.conf, where <IP address> is the Internet Protocol address of the host on which the policy server is licensed to run.

For example: cams-reg-192.168.1.1.conf

This file registers the name and cluster associated with the deployed Cams policy server. For example:

cams.server.name=MyCamsServer
cams.cluster.name=MyCamsCluster

WARNING: It is now illegal to use property: cams.server.name in the main Cams policy server configuration file: cams.conf. The Cams server name and cluster name must be specified in the policy server registration file.

See the Policy Server Clustering Quick Start for more information.

Cams Web Agent Clustering Configuration

New clustering-related parameters introduced to cams-webagent.conf include:

  • cams.cluster.name - The name of the Cams policy server cluster associated with the agent
  • cams.server.url.<cams.server.name> - The URL for each Cams policy server in the cluster. For example, if two Cams policy servers named: Orville and Wilbur are available in MyCamsCluster, parameters: cams.server.url.Orville=cams://192.168.1.1:9191 and cams.server.url.Wilbur=cams://192.168.1.2:9191 would be used.
  • cams.heartbeat.interval - The interval (in seconds) the Cams web agent will send heartbeat messages to the Cams policy server to check its availability.
  • cams.cluster.debug - Toggle on/off cluster debug messages.

Cams access-control-policy.xml "lastModifiedTime" Schema Addition

An XML attribute named: lastModifiedTime was added to the <access-control-policy> Element, which helps Cams web agents clear cached access control information in a timely manner if an access control policy is modified.

WARNING: This value is required and should be updated whenever an access-control-policy.xml file is modified.

For example:

<access-control-policy defaultBias="denied" lastModifiedTime="200312191000">

The value must be numeric and the recommended format is: YYYYMMDDhhmm, which enables detection of up to the minute changes. Agents are responsible for caching this value and detecting a larger value (a later time), so consistent precision is important. Future Cams administrative tools will set this value automatically, likely to the nearest second.

Migrating a Cams 1.5 access-control-policy.xml to Cams 2.0

Migrating from a Cams 1.5 access-control-policy.xml file to a Cams 2.0 file is simple and requires two changes:

1. Add the lastModfiedTime to the access-control-policy.xml element as described above

2. Modify the referenced XML DTD from:

<!DOCTYPE access-control-policy SYSTEM "http://cafesoft.com/access-control-policy_1_1.dtd">

to:

<!DOCTYPE access-control-policy SYSTEM "http://cafesoft.com/access-control-policy_1_2.dtd">

2. Cams Web Agent Session Anti-Hijacking Protection

Support for session anti-hijacking protection using HTTP request header values helps ensure that a request comes from the same browser that originated the session. An extra hash value is appended to the base session identifier and validated each time a Cams session id cookie value is received. Unless the request is received from an HTTP browser with the same HTTP request headers (Accept-Language and User-Agent) the session is considered hijacked and is invalidated by the web agent. A WARNING is logged to the Cams web agent log.

New parameters introduced in cams-webagent.conf to support session anti-hijacking are:

  • cams.session.hijacking.protection.enable - Enable/disable session hijacking protection.
  • cams.session.hijacking.protection.algorithm - Algorithm to use for the hash: SHA1 (recommended) or MD5.
  • cams.session.hijacking.protection.salt - A value unique to a site for use in computing a unique hash value

WARNING: Due to the implementation of clustering support, Cams policy server and web agent configuration files have changed.

3. Cams Web Agent HTTP Request Header Naming Convention

The naming convention for Cams HTTP request headers has changed for the J2EE servlet and JSP programming environments. Cams HTTP request headers now use a dash character (-) rather than an underscore character (_). This was done to enable portability of J2EE web applications that use Cams HTTP request headers, whether those applications are protected by a Cams webagent installed in the local J2EE server or use Cams HTTP request headers received via an HTTP proxy server or some other proxy protocol like Tomcat AJP13.

WARNING: All J2EE web applications or web application components, including HTTP servlets and JSPs that use Cams HTTP request headers must be modified to use the Cams 2.0 conventions. This includes use of the new Cams 2.0 login.jsp, denied.jsp, and error.jsp files or your customized version of these files.

Other other web programming environments, including: ASP.NET and cgi-bin are uneffected as these interfaces convert all HTTP request headers containing dash characters to the underscore form and prepend HTTP_ to the name.

Table 2.0.3 summarizes the header name changes for J2EE servlets and JSPs.

New Name Previous Name
CAMS-HTTP-SESSION-ID CAMS_HTTP_SESSION_ID
CAMS-HTTP-SESSION-CREATED CAMS_HTTP_SESSION_CREATED
CAMS-HTTP-SECURITY-DOMAIN CAMS_HTTP_SECURITY_DOMAIN
CAMS-HTTP-USER CAMS_HTTP_USER
CAMS-HTTP-ROLE CAMS_HTTP_ROLE
CAMS-HTTP-ROLES CAMS_HTTP_ROLES
CAMS-HTTP-<attribute-name> CAMS_HTTP_<attribute_name>

Table 2.0.3 - Cams HTTP request header naming convention changes for J2EE servlets and JSPs

4. Cams Policy Server now ships with Jetty HTTP Server

The Cams 2.0 policy server now ships with a Jetty HTTP server, pre-configured with the Cams ServletFilter Web Agent and pre-compiled Java servlets. This enables quick verification of basic Cams policy server installations by postponing the need to deploy a Cams web agent.

After installing, configuring, and starting a Cams policy servers, you can verify its operation by by running the Jetty HTTP test server using the following commands:

Windows

cd CAMS_HOME\bin
																																																																																																																																																																																																																																																																																																																																																									runjetty.bat

Unix

cd CAMS_HOME\bin
																																																																																																																																																																																																																																																																																																																																																									runjetty.sh

Once Jetty is running, simply start a web browser and go to a URL appropriate for the host on which Jetty is running. For example:

http://localhost

If properly configured, a Cams test page will display where you can attempt authentication and various access control checks.

5. Cams web agents support for proxied Cams HTTP request headers

Cams 2.0 web agents have been enhanced to accept Cams HTTP request headers from one or more trusted upstream Cams web agents. Cams web agents prior to version 2.0 that received Cams HTTP request headers interpreted the request as potentially malicious and redirected to the configured Cams error page.

In web server deployment topologies where an upstream web server has a Cams web agent and proxies HTTP requests to a downstream web server also using a Cams web agent, the downstream Cams web agent can now be configured to accept the proxied Cams HTTP request headers. The downstream Cams web agent validates the received Cams HTTP request headers by computing an encrypted value that must match the value of a special Cams request header received from the upstream web agent.

See the description of property: cams.http.headers.accept.proxied available in each Cams 2.0 web agent guide for configuration instructions.

Cams 1.5 Release Details

The highlights of the 1.5 minor release include:

  • Enhanced resource pattern matching to support patterns of form: schemePattern://hostPattern:portPattern/uriPattern. This enables more flexible resource patterns that can significantly reduce the size of access control policies. See the Cams Administrators Guide: Access Control Sevices - Configuring Permissions for more information.
  • The SiteServerLoginModule has been added to provide user authentication support for Microsoft Site Server.
  • The ActiveDirectoryLoginModule has been added to provide user authentication support for Microsoft Active Directory.
  • The general LdapLoginModule has been enhanced to support different password validation methods, including Cams Password Digests, LDAP compare, and LDAP bind. Also, the LDAP connection pooling service is no longer used. The parameter names have changed (for usage examples, see the login-config.xml file in the distribution system or mydomain security domains):

    New Name Previous Name Notes on Value
    host n/a The LDAP server host name or IP address, previously provided with LDAP connection pooling service.
    port n/a The LDAP server port number, previously provided with LDAP connection pooling service.
    passwordValidationMethod n/a Required value: Cams, Compare, or Bind
    adminUsername n/a A user account that has access control privleges that allow it to perform searches against the user and role nodes values in the LDAP directory. This value is required when the passwordValidationMethod of Cams or Compare is used, but optional for the Bind method. The Bind method uses the connection bound to the authenticated user to lookup role values.
    adminPassword n/a The password for the adminUsername account.
    userDN userFilter Same as previous release
    roleBaseDN roleBase Same as previous release
    roleScope roleSubtree Required value: BASE, ONE, or SUB
    roleFilter roleSearch Same as previous release
    roleAttrName roleName Same as previous release

  • Validation testing has been completed for Cams server 1.5 and Cams IIS web agent 1.2 on the Windows 2003 Server platform with IIS 6.0.
  • The Cams ServletFilter web agent is now available with tested support for BEA WebLogic, JBoss, Jetty Oracle 9iAS, and Tomcat.
  • The Cams Apache 1.3 web agent is been completely refactored to make it faster and even more reliable
  • The Cams Tomcat web agent has been enhanced to eliminate the need for a modified CoyoteConnector (to support Cams HTTP request headers).
  • The Cams IIS web agent has been enhanced to "fail-safe" when improperly initialized. This agent also has the ability to initialize after IIS server startup if it failed to initialize properly at server startup.
  • The Cams server has been enhanced to provide more flexible support for pluggable resource/permission types.
  • The Cams server now provides utilities for adding/removing/running as an NT Service. A Cams for Windows packaging also includes a Java Runtime Engine (JRE 1.4.1_03), eliminating the requirement to download and install Java.
  • The Cams server script: runcams.bat (for Windows) now uses a Java launcher program that intercepts CTRL-C to enable graceful server shutdown.
  • Significant additions to the access control policy metadata model, which prepare the Cams server for access control policy administration services in a future release. The Cams server configuration file (CAMS_HOME/conf/cams.conf) contains many new values which are required by Cams server 1.5.

    WARNING: Users of earlier Cams server versions must manually integrate site-specific configuration values into the new cams.conf configuration file. Using an older Cams server configuration file with Cams server 1.5 will fail.

Cams 1.1 Release Details

The highlights of the 1.1 minor release include:

  • Repackaged to make Cams server releases and web agents releases independent.
  • International license manager date issue patches included.
  • URL requests with juxtaposed slashes now generate error.
  • Various fixes to support new agents.

Cams 1.0.1 Release Details

The highlights of the 1.0.1 patch release include:

  • Access control request caching now integrated in Apache web agent.
  • Apache web agent supports configurable lazy load of connections.
  • Tomcat and Apache web agents detect and report spoofing of Cams HTTP request headers by clients.
  • Fixed IP address requirements for sessions that conflicted with some dynamic NATs.
  • Enhancements to messaging framework.

Cams 1.0 Release Details

The highlights of the 1.0 final release include:

  • Numerous performance and memory tuning enhancements.
  • Secret key encryption of sensitive information.
  • SSL agent to Cams server communication enabled.
  • Multiple Cams protocols over a single connection for Cams Apache web agent reducing the number of connections to the Cams server by 75 percent.
  • Cams Agent API for Java: This new API enables users to create custom agents that use the Cams server for security.
  • Web multiple sign-on: A user can now simultaneously sign-on to multiple concurrent security domains within the same DNS domain/subdomains from the same web browser.
  • Cams Tomcat web agent: Performance boost by implementation of access control check caching.
  • Cams Tomcat web agent: Refactored to use Cams client and Cams agent API.
  • Cams Tomcat web agent: Support for Tomcat 4.1 Coyote connector.
  • Cams Tomcat web agent: Enable/disable HTTP request headers and remote session cache.
  • General: Improved log formatting and error reporting.
  • General: Various bug fixes and performance improvements.
  • User/password Single Sign-on across multiple servers and tiers.
  • Support for SQL, LDAP, and XML user repositories.
  • Business policy based access control rules.
  • Fine-grained access control.
  • FORM-based authentication.
  • Developer APIs.
    - Access Control Rules API for creating new rules to protect resources.
    - Callback handlers for creating custom end user interfaces.
    - Login modules for creating custom authenticators.
    - Services API which enables you to create and deploy Cams services.
    - Session API for controlling user sessions and customizing their attributes when they are created, closed, or expired (including sending those attributes with an HTTP request).
    - Webapp Programming APIs for fine-grained access control within your web applications.

Known Issues

Known policy server issues:

  • The UnboundID LDAP Connection Pool Service uses LDAP API calls that are not supported by Active Directory on Windows Server 2003. If you need to use this component with Active Directory on Windows Server 2003, please contact OneLogin support.

Support

For technical support please send email to support@onelogin.com.