Back | Next | Contents Cams Administrator's Guide


As a Cams administrator, a high-level understanding of how Cams is organized is helpful when you begin to configure the components that provide authentication, web single sign-on, access control and session management. This document provides a brief overview of Cams and introduces you to other documents where you'll find more information.

Centralized Web Security

Cams is a centralized web security solution, in which Cams web agents delegate security decisions to a central security authority - the Cams policy server. The Cams policy server is designed to protect any kind of web resource, including web pages, files, dynamic web applications and even non-web resources. When a Cams web agent sends an access control request, an access control service hosted within the Cams policy server decides whether to grant or deny access, and the requesting Cams web agent enforces the decision. If the access to the protected web resource requires authentication, the Cams policy server will notify the Cams web agent, which prompts the user to login by displaying a registered login page. The user will generally enter a user name and password, then submit them to the web server, where the Cams web agent intercepts the credentials and delegates an authentication request to the Cams policy server. If the user is successfully authenticated, the HTTP request is forwarded to the originally requested URL (the one that required successful authentication for access), otherwise an error is displayed.

Figure 1 - Cams web agent and Cams policy server architecture

Figure 1 shows a Cams deployment where two Cams policy servers are configured to provide failover and load balancing. Each Cams policy server uses its own instance of the same security policy and each accesses the same user directory (or multiple user directories configured at a virtual directory) to authenticate users. Cams web agents delegate authentication and access control requests to Cams policy servers on a round robin basis. If one Cams policy server fails, then all requests are routed through the other. Given sufficient hardware resources any number of Cams policy servers can be deployed at a site (including only one) and any number of Cams web agents can connect to a Cams policy server.

Use of Cams enables authentication (via a login configuration) and access control to be implemented within the Cams policy server, which centralizes security administration and security event logging. This server-based approach to web application security simplifies the task of secure web application programming, maintenance and administration, while minimizing vulnerabilities at your site. Additionally, distributed Cams web agents provide users with web single sign-on to multiple web servers reducing the support burden, user frustration and cost of password resets that are imposed by sites with multiple sign-ons (and user accounts).

The Cams Policy Server

The Cams policy server has a service oriented architecture that handles authentication, access control, session management and more. Cams web agents generally access these security services on one TCP/IP port, while administrative services that enable Cams policy server shutdown are available on another port. This enables you to use a firewall to limit access to certain Cams services based on the TCP/IP port. Also, Cams web agent must authenticate to connect to the Cams policy server and use secret keys to encrypt the transmission of sensitive data like user names and passwords.

Security Domains

In the Cams security model, services and resources are owned by a security domain. This division enables security management to be partitioned according to organizational or physical boundaries as shown in Figure 2. Different security domain resources may be configured and managed by different individuals, departments and even companies.

Figure 2 - Security domain services are configured in three required XML files

Cams security domains are declared in a security domain registry. The system security domain is required and is often the only security domain required at many sites. The system security domain handles authentication of Cams web agents and is the root for delegation of access check requests to other security domains. Any number of additional security domains can be created and hierarchically nested as required by your organization's security policy and boundaries.

Each security domain contains its own set of services, which include:

  1. Access control service - grants or denies access to protected resources based on an access control policy
  2. Authentication service - verifies the user's identity and establishes a session that exists until the user logs out or the session times out
  3. Session access service - provides session information to Cams web agents about authenticated users
  4. Session control service - enables session modification and explicit closure (logout)
  5. Session manager service - manages authenticated user sessions and expires them if inactive for a configurable period
  6. Service manager service - manages custom services used by other components or services within a security domains

Each Cams security domain has three configuration files and an optional Cams user directory (cams-users.xml) as shown in Figure 2. These configuration files are persisted to disk in XML format. All security domain services are configured in security-domain.xml. Values in login-config.xml configure user directories (e.g. Active Directory, LDAP and SQL databases) and how Cams requests authentication credentials from users. The access-control-policy.xml file defines the rules that protect web resources and access to the Cams policy server by Cams web agents. As a Cams administrator, the authentication and access control services will be of greatest interest to you. The following sections provide an overview of how each security domain's authentication and access control services are organized.

You learn about configuring Cams security domains in Security Domain Configuration.

The Authentication Service

User authentication is performed against one or more user directories as specified in a security domain's login configuration. By default, a login configuration is stored in a security domain's login-config.xml file. Each login configuration can reference one or more user directories within a login configuration entry, which are accessed in order with specified success/fail dependencies between them as shown in Figure 3 to implement a virtual directory.

Figure 3 - The Cams policy server authentication service integrates with standard user directories

Each login configuration entry references one or more login modules, which enable authentication using most industry standard user directories. Cams provides configurable login modules that support Microsoft Active Directory, LDAP v3 servers, SQL databases, X.509 certificates, RSA SecurID, VASCO Digipass and a Cams XML user repository (cams-users.xml). Developers can also use a Cams programmer's API to create custom login modules that implement authentication for user directories not currently supported.

Cams supports user name/password, X.509 digital certificate, RSA SecurID and VASCO Digipass authentication methods. User name and password is often sufficient, however, security policies are driving organizations towards use of strong, multi-factor authentication (something you know and something you have). Cams enables you to easily adjust as your authentication requirements evolve, or even configure Cams to require different authentication methods for different resources. A Cams automatic login feature similar to Yahoo! site authentication logs users in without prompting on return visits. If automatic login is not enabled, unauthenticated users are always prompted by Cams to supply credentials using a login page when accessing protected resources (known as lazy authentication).

Figure 4 - Cams authentication methods

Figure 4 shows the use of the Cams login page on a web server with a Cams web agent. This dynamic page enables Cams to prompt for and submit their user credentials. In a farm of web servers protected by Cams, any or all Cams web agents can be configured to serve this page. Example JSP, ASP.NET and Perl login pages are provided with Cams web agents. You can customize the login page or provide your own in any dynamic scripting language supported by your web server. Cams also supports proactive authentication, where users login before accessing secure resources. Login pages are dynamic scripts you customize to the look and feel of your site..

You learn about configuring Cams authentication in Login Configuration.

The Access Control Service

Each security domain protects resources it owns using an access control policy, which is a list of permissions and access control rules. The access control policy is stored in a security domain's access-control-policy.xml file. Standard Cams access control rules include:

  • authenticated user role (Role Based Access Control)
  • remote host/ip address
  • confidentiality (SSL/TLS connection)
  • day/time
  • sql data (ensures completeness of required database values)
  • obligations (obligates Cams web agents to perform actions such as HTTP redirects)
  • attributes (access control based on almost any HTTP request value such as query parameter values)

Figure 5 - A Cams security domain's access control policy is defined by rules and permissions

Existing access control rules can be combined into new, reusable rules using AND, OR and NOT operators. Custom access control rules can also be created using a Cams programmer's API. For example, a site might create a custom rule to grant access to a resource based on a user specific value returned by a web service.

Cams access control policy permissions associate resources (e.g. web URLs) with one of two possible actions: an access control rule that will be evaluated to grant or deny access or a security domain to which access control will be delegated. For HTTP resources, a permission is comprised of three elements:

  1. An HTTP URL resource pattern to match (e.g.*)
  2. A list of 0 or more HTTP methods (e.g. GET, POST, PUT, HEAD, TRACE, DELETE, OPTIONS)
  3. An access control rule to apply or the name of another security domain to delegate to

The access control service matches the request resource pattern (e.g. URL) and actions (e.g. HTTP method) to a permission and then evaluates the linked access control rule or delegates the decision to another security domain. The required system security domain receives all access control requests and may delegate them to other security domains if specified by a permission. Permission delegation is a powerful concept that allows access control management to be distributed throughout an organization or across organizational boundaries.

Access Control Requests/Responses

A Cams web agent sends an access control request to a Cams policy server to check a user's access to a resource. The access control request contains information about the requested resource including a resource type, a unique resource identifier and one or more requested actions. For example, the following resource request parameters correspond to a user accessing via a web browser:

  1. Resource type: http
  2. Resource id:
  3. Action: GET

The access control request also contains other parameters that may be important for deciding whether to grant or deny access like:

  • The IP address/host name of the client attempting to access the resource
  • A Cams session identifier (if the user has already authenticated)
  • A flag indicating whether or not a confidential network connection is being used by the client
  • The date/time at the resource provider

Ultimately an access control service within a security domain will handle the request and populate an access control response, which will be returned to the Cams web agent to enforce.

You learn about configuring Cams access control services in Access Control Services.

Cams Auditing

Cams keeps accurate tabs on authentication, access control and session transactions (also called events). Each Cams security domain writes up to five comma-delimited text files as show below. Logs are also maintained by the Cams policy server for system-level information and by Cams web agents.

Figure 6 - Cams security events are written to log files and can trigger actions

Cams components known internally to the Cams engine as logger valves do the logging work. To meet your business requirements, existing valves can be readily customized or new ones created that plug into Cams services to tap into Cams security events. For example, valves can be used to send messages (via SMTP, Message Queues, etc.) or to write to a database based on successful/failed logins, resource accesses, session modifications and more. Cams also provides industry leading use of log files to facilitate integration diagnostics, which is extremely powerful when requesting Cafésoft support.

NOTE: Cams logs are extremely valuable during site configuration and debugging. Look in console.log, system-trace.log and cams-server.log to see system-level output. Look in the system-authentication.log to see if authentication occurs as expected. Each service-level log file name is prepended with the name of the security domain to which it belongs. You can also set debug flags in many locations within a security domain's configuration file, the Cams policy server configuration file and Cams web agent configuration files to see more verbose output.

You learn about Cams security domain logging options in Security Domain Configuration.

Cams Web Agents

Cams web agents are native C and Java software components that are integrated with web servers (like Apache, Microsoft IIS and Sun ONE) and application servers (like BEA WebLogic, IBM WebSphere and Tomcat) to delegate access control checks to a Cams policy server and enforce the associated responses. References throughout this documentation to web servers generally means both web and application servers.

When a user makes a request to a web server configured with a Cams web agent, the Cams web agent sends an access check request to a Cams policy to determine if the resource is protected. If it is, the Cams web agent enforces the grant or deny answer it receives. Any Cams web agent may also be configured as an authentication proxy to prompt users for authentication credentials using a login form and forward the credentials to a Cams policy server as an authentication request. If the user is authenticated, the Cams web agent redirects the user's browser to the originally requested URL and the access check is performed again, this time with the known user identity. Cams web agents also provide many other services when configured to do so using the proprieties defined in cams-webagent.conf.

Cams Web Agent Components

Each Cams web agent is custom for the web server that it supports. Consequently, the components and files included with different Cams web agents may vary, even though each Cams web agent is similar in purpose and share common libraries and configuration properties. From a high level, the components associated with a Cams web agent include:

  • Executables and libraries
  • Configuration files
  • Dynamic HTML scripts

NOTE: Each Cams web agent includes installation and configuration instructions. Most configuration values are the same for all Cams web agents. Once you become familiar with the most important values, you'll find Cams web agent integration easy.

Executables and Libraries

Program executables and libraries may be Java byte code or native libraries that define the Cams web agent programmatic logic and its integration into the web server. The installation section of each Cams web agent document describes how to install these files into the correct locations. You will not need to modify the Cams web agent, but you will need to configure them.

Configuration Files

Each Cams web agent includes a cams-webagent.conf configuration file. This file is often placed in the same directory with other configuration files for the web server. You use this file to configure the Cams web agent values specific to your installation. For example, you need to inform each Cams web agent of the Cams policy server location, the Cams cluster name, Cams policy server name and the credentials that are required for the Cams web agent to authenticate.

The Cams web agent documentation describes how to configure each of the properties found in this file (the cams-webagent.conf file also contains informative comments). In addition, each web server has specific configuration instructions. You'll typically edit a configuration file (e.g. httpd.conf for Apache, server.xml for Tomcat or web.xml for BEA WebLogic) to inform the web server of the existence of the Cams web agent.

See the Cams web agent guide for each Cams web agent for more information. Make sure that you review and use the Configuration Properties appendix to understand the configuration properties you'll need to update.

Dynamic HTML Pages

Cams web agents use dynamic HTML pages to prompt users for login credentials and POST those credentials to a reserved URI that the Cams web agent intercepts as an authentication request. Any scripting language may be used like ASP.NET, JSP, Perl, PHP or ColdFusion. You can use and modify the login page supplied with each Cams web agent or create your own. Example login pages are available using ASP.NET, JSP and Perl. The language of the page is not important, but you must use specific conventions. The Cams web agent Scripts document provides instructions on programming login pages along with information on how to embed a logout URL on any page on your site. The Cams login page examples also show how to validate query parameter input to prevent cross scripting attacks.

When users are denied access to a resource by Cams, the Cams web agent sends an HTTP 403 forbidden or access denied message, which causes the web server to display its configured HTTP error page. Similarly, if an unexpected run-time Cams error occurs, the Cams web agent sends an HTTP 500 general server error. See your web server documentation for information on how to customize the pages displayed for HTTP 403 and 500 messages.

Additional Cams Web Agent Responsibilities

Cams web agents are easily customized using configuration values in cams-webagent-conf. Here's a list of Cams web agent responsibilities that are enabled by default or can be enabled:

  • Secure Cams HTTP request headers - Securely injects Cams user session values into HTTP requests enabling page personalization and fine-grained access control (remote clients are not permitted to set these values at any time)
  • Proxied headers - Enables on a web or application server with a Cams web agent to proxy requests to another web or application server with a Cams web agent, including sending secure Cams HTTP request headers
  • Access check caching - Increases performance for access control requests for unconditionally granted or denied resources by remembering them in a Cams web agent
  • Session caching - Increases performance for injecting secure Cams HTTP request headers by remembering them in a Cams web agent
  • Session hijacking - Protects against hackers stealing a Cams session cookie and using it in another browser by hashing additional values specific to a browser in the Cams session identifier
  • Login/Logout URIs - Provides customization of URIs against which login and logout instructions are submitted from browser pages
  • Error/Denied URIs - Displays site customized pages when errors occur or access is denied to a resource by the Cams policy server
  • Autologin - Enables a user's credentials to be remembered in a persistent cookie and automatically logs the user in on the next visit
  • Attributes - Instructs the Cams web agent to send HTTP query parameters and Cams web agent attributes to be used by the Cams policy server for an access control check
  • Obligations - Requires or obligates the Cams web agent to performs actions such as an HTTP redirect based upon an access control decision by the Cams policy server
  • Agent login - Increases security enabling customization of the user name and password used by a web agent
  • Encryption keys - Provides secure communication by encrypting sensitive values sent from the Cams web agent to the Cams policy server by using shared secret keys
  • Cookie customization - Enables configuration of certain Cams session cookie properties such as the cookie name prefix for site customization
  • Parameter validation - Values submitted with Cams authentication requests are validated to prevent cross scripting or other attacks to you site

To learn about Cams web agent installation and configuration, please read the Cams web agent guide included with each Cams web agent (and found at the Cafésoft Documentation Center).

Web Single Sign-On

HTTP cookies save server side information within a user's browser. The browser maintains a table of cookies and sends them with each request ONLY to sites from which they originated. Strict Internet-standard rules define cookie creation, modification and use.

Cams uses cookies that are maintained only in the browsers memory and never written to disk to securely store session identifiers. Upon successful authentication, the Cams policy server creates a user session and the Cams web agent sends an HTTP cookie with a secure, hashed session identifier to your browser in a format that can only be deciphered by the Cams policy server from which it originated using a site and security domain specific key. Other values are optionally hashed with the session identifier to provide greater security such as the IP address of the remote user, the browser user agent, etc.

Each subsequent request is sent by the browser with the cookie enabling the Cams web agent to send it to the Cams policy server, which uses the cookie value to identify the user and authorize requests for protected resources. The cookie remains in browser memory until you logout, exit your browser or your session expires.

With a single Cams session cookie, a valid Cams policy server session provides single sign-on access to secure resources for which you have permission within a single DNS domain, including subdomains. You can use the two right most dots of a fully-qualifed DNS name to determined the hosts that will get a Cams session cookie (for example, any host in would receive a Cams session cookie created within that domain, such as and

NOTE: End users can choose to disable cookies in their browsers. You must ensure that cookies are enabled to access sites protected by Cams. If they are not, authentication may be valid but the session state is not maintained resulting in redisplay of the Cams login page as if the user had not authenticated.

Cross DNS Domain Web Single Sign-On

Cams supports web single sign-on across web servers in multiple DNS domains and servers that can be accessed only by IP address or non-fully-qualified host names. To understand how Cams cross DNS domain web single sign-on (CDSSO) works, it is necessary to understand the following strict rules that web browsers must adhere to as specified by Internet security standards:

  • If a web server returns a cookie with a specified DNS domain scope (e.g., then the browser may only accept the cookie if the HTTP request was for a host in that domain (e.g.,, etc.). If the cookie returned by the web server is not in the requested domain, the browser must discard it.
  • A browser can send a cookie accepted for a given DNS domain scope (e.g. with all subsequent HTTP requests to any host in that domain. For example, a cookie accepted from host for DNS domain "" can subsequently be sent to web servers at and
  • If a web server returns a cookie without a DNS domain scope, then the cookie is valid only for the host name or IP address of the original HTTP request. For example, if a browser requests URL and receives a host-specific cookie, then the cookie will only be sent back to web servers accessible via the fully-qualified host name Likewise, if a browser requests a URL using an IP address or a non-fully-qualified host name (e.g. or http://localhost/), then any cookie returned is valid only for that specific IP address or host name.

Based on these HTTP cookie handling constraints, Cams defines the following concepts and CDSSO system roles:

  • A Cookie Domain is the set of all web servers for which a cookie is valid based on its DNS domain, host name or IP address. For example, if a cookie is defined for DNS domain then its cookie domain is all hosts in DNS domain, including subdomains of If a cookie is defined for a specific host name or IP address, then the cookie domain is that host name or IP address.
  • A Cookie Provider is an HTTP service accessible from a URL within a cookie domain. It is used to setup the Cams session cookie within a user's browser for its associated cookie domain. To provide CDSSO, a Cams session cookie must be established for each cookie domain visited by a user's browser. This is accomplished by redirecting the browser to a registered "identity provider" where the user authenticates and to designed a designed cookie provider URL for each "service provider" cookie domain. All Cams web agents can be configured to serve as CDSSO cookie providers.

The Cams CDSSO solution protects against possible replay attacks (in which the URL for given CDSSO request might be intercepted by a hacker and used to hijack an existing Cams session) by using one-time tokens and short expiration periods (usually 5 or 10 seconds).

Back | Next | Contents