| Back | Next | Contents | Cams Web Agent Guide |
Cams web agents are integrated with web and application servers to provide security policy enforcement services. When a user makes a request to the web or application server, a Cams web agent determines if the resource is protected. If it is, access control and authentication requests are delegated to a Cams policy server and the Cams web agent enforces the answers it receives. This document provides instructions on common issues you should consider when deploying a Cams web agent. In addition, you should reference the specific installation and configuration documentation for each Cams web agent you install.
Each Cams web agent is custom for the web or application 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. From a high level, the components associated with a Cams web agent include:
Program executables and libraries may be Java byte code, native, or stand-alone applications that define the Cams web agent programmatic logic and its integration into the web server. The installation process described in each Cams web agent document will describe how to copy these files into the correct locations. You will not need to modify the Cams web agent, but you may need to configure them. Please refer to the Cams web agent specific documentation for details.
Each Cams web agent includes a cams-webagent.conf configuration file. This file is typically located 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 policy server name, and the credentials that are required for the Cams web agent to authenticate.
The Cams web agent documentation describes how you'll need to configure each of the properties found in this file (the file also contains informative comments). In addition, each web server has a native configuration. You'll typically need to edit a configuration file (e.g., httpd.conf for Apache or server.xml for Tomcat) to inform the web server of the existence of the Cams web agent. Again, you'll want to refer to the Cams web agent specific document for values you'll need to configure.
Cams web agents work in conjunction with three dynamic HTML pages that prompt users for login credentials and report errors. The scripting language may be JSP, Perl, PHP, Cold Fusion, or Active Server Pages depending upon the web server and your requirements. Hence, you can even create your own if needed! The language of the pages is not important, they just need to use certain conventions in order to work with Cams web agents. Let's take a closer look at each page/script.
When a user requests a resource and access is denied because authentication is required, Cams web agents redirect users to a configured login page. The login page can be configured to be the same web or application server as the request or a different web or application server. The login page is generally implemented in a scripting language, like JSP, Perl, PHP, sh, ASP, etc. so that it can display dynamic information and maintain some simple state. It is also security domain specific and is configured in the login-config.xml file. For example:
<!-- Specify the default login page --> <login-parameters> <login-parameter name="camsLoginUrl" value="/cams/login.jsp"/> </login-parameters>
The following steps summarize the responsibilities of a login page and it's interactions with a Cams web agent:
When user authentication is required, a Cams web agent redirects an HTTP request to the configured login page. Three query parameters accompany the request:
The login page is responsible for parsing these query parameters and storing them in the HTML page as hidden fields within an HTML form.
The login page also includes fields for capturing authentication information from the end user. These values typically represent username and password values on a form but might be other values such as account numbers, pins, social security numbers, etc. In the default username and password case, these parameters are:
Ultimately, the form will be posted to a Cams web agent, which will recognize parameters starting with "cams_cb" and send them to a Cams policy server as part of an authentication request. Within the Cams policy server, these values will be sent to the callback handler configured with the defined login module(s).
Finally, each login page must have a form action that corresponds to a login request. By default, this value is configured to be action=/cams/login. The value can be any you choose, so long as it matches the value specified in the Cams web agent's cams-webagent.conf file. The Cams web agent is programmed to intercept this request and forward the contents of the HTTP post to the Cams policy server for processing. If the authentication values are valid, a browser memory resident cookie with the user's session token is created and the user's browser is redirected to the originally-requested resource. If the authentication values are not valid, the user is redirected to the Cams error page.
NOTE: You can create a static login page by hardcoding the cams_security_domain, cams_login_config, and cams_orginal_url hidden values.
The error page displays any error conditions encountered by the Cams web agent. Messages may originate from a Cams policy server or the Cams web agent. A query parameter named message is sent to the error page, which generally displays the message and provides other site-specific support or help desk information.
The error page is configured in cams-webagent.conf, making it a Cams web agent specific resource.
In the example above, the user's browser was redirected back to the originally requested URL after successful authentication. This, however, does not guarantee that he will be able to access the resource. Now that his identity is known, the Cams policy server can make that determination. If he doesn't have permission to access the requested resource, the user's browser is redirected to the configured Cams access denied page.
Like the error page, the primary function of the access denied page is to display information sent by Cams. However, there is more information available to display including:
As with the error page, the location of the access denied page is specified in cams-webagent.conf, making the access denied page Cams web agent specific rather than security domain specific.
To ensure correct operation, your Cams access control policy should unconditionally grant user access for each of the dynamic Cams pages. For example, denying access to the error page would result in redirection to the access denied page. This can obscure the real error and be very challenging to debug. If access is denied to the access denied page, Cams web agents will automatically detect this condition and return a hard-coded HTML message. This avoids an infinite loop of redirections to the access denied page. Denying access to the login page would place a firewall between the user and the form required to authenticate. Even authorized users would not be able to authenticate! By default, permissions to grant access to Cams dynamic pages are defined in the system security domain's access-control.xml file:
<permission desc="Cams IIS/J2EE login, denied, error pages" actions="GET,POST"> <resource-pattern id="*://*:*/cams/*"/> <acr-ref id="granted"/> </permission> <permission desc="Cams Apache login, denied, error pages" actions="GET,POST"> <resource-pattern id="*://*:*/cgi-bin/cams-*"/> <acr-ref id="granted"/> </permission>
NOTE: You may want to place restrictions on the login page that don't require authentication. For example, you might create a rule that allows only users on your internal network or a specified Internet domain to access the login page. Also, if each security domain has it's own login page, permissions controlling them should be moved to their respective security domain's access control policy.
Now that you know how to login, what about logging out? There's no need to create a logout page, you simply supply a logout hyperlink from within any page.
The logout URL, like the error and access denied pages is specified in cams-webagent.conf. The Cams web agent knows to intercept the logout URL request and forward it to the Cams policy server with the user's session identity and the security domain name. Cams allows simultaneous login into multiple security domains, so you must inform the Cams server of the security domain from which you are requesting logout. For example, if the cams-webagent.conf logout property is:
cams.logout.uri=/cams/logout
and the security domain is example_domain, then a properly formed relative logout URL might look like:
/cams/logout?cams_security_domain="example_domain"
You can make the logout action dynamic by using Cams HTTP request headers to populate the security domain parameter.
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. There are very strict rules that 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. After a user authenticates with a Cams policy server, his session identity is persisted in a hash stored in a cookie. Each subsequent request is sent by the browser with the cookie enabling Cams to identify the user and authorize requests for protected resources. The session identity is stored 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.
To further enhance security, Cams web agents provide session anti-hijacking protection. When a user first authenticates and a Cams session is created, a unique value is computed from standard HTTP request headers and unique site values. If a hacker somehow intercepted the Cams session cookie, he would also need to provide the exact HTTP request headers used by the original user's browser.
Table 1 lists Cams web agent properties for configuring session hijacking protection.
NOTE: All Cams web agents deployed in the same environment must use the same settings for all session hijacking parameters.
| Name | Description |
|---|---|
| cams.session.hijacking.protection.enable |
Enable/disable Cams session hijacking protection. Use true to enable and false to disable hijacking protection. When using Cams web agents on the internet, session hijacking protection is recommended. The default value is: true |
| cams.session.hijacking.protection.algorithm |
The message digest algorithm used to compute a unique hash value for hijacking protection. The following algorithms are supported:
The default value is: sha1 (and is recommended) |
| cams.session.hijacking.protection.salt |
A unique site value combined as an ingredient with all other session and HTTP request header parameters to ensure that the message digest hash value is unique for a given deployment environment. The default value is: epsom NOTE: You must choose a value unique to your site for maximum protection. |
Table 1 - Cams session hijacking protection parameters in cams-webagent.conf
End users can choose to disable cookies in their browsers. You must ensure that they are enabled for sites protected by Cams.
Cams web agents install with default configuration properties. However, you may find it beneficial to configure your installation to more adequately meet the requirements of your environment. This section presents optimizations that you should consider. All configuration optimizations specified in this document are common to all Cams web agents. For options specific to a given Cams web agent, see the Cams web agent-specific documentation.
Access check caching improves performance by enabling the Cams web agent to remember a previous access control check responses from a Cams policy server for a specified period of time. Only unconditionally granted and denied resources are cached. If your site uses a large number of unprotected pages, gifs, etc., then enabling access control check caching can substantially reduce the number of access control checks to the Cams policy server.
Table 2 lists Cams web agent properties for configuring access check caching:
| Name | Description |
|---|---|
| cams.access.check.cache | Enable/disable the access control check cache. Caching improves performance by enabling the web agent to remember a previous access control check Cams policy server response for a specified period of time. This enables general resources, like GIF and JPEG image files, javascript, style sheets, to avoid unnecessary access control checks. |
| cams.access.check.cache.size | The maximum number of access control responses that can be cached at a given time. Once the cache is full, newly cached responses will eject the least recently used cached response. |
| cams.access.check.cache.refreshTime | The amount of time, in minutes, that is allowed before an access control request is sent to the Cams policy server to check if the cache should be cleared. This ensures that Cams web agents can detect changes to a Cams access control policy within this period, forcing the cache to be flushed if necessary. |
Table 2 - General access check caching parameters in cams-webagent.conf
Some Cams web agent access check caches may have additional implementation-specific properties. Please refer to the Cams web agent-specific documentation for more details.
By default, Cams web agents retrieve remote user session information from the Cams policy server with each request. However, they only need to retrieve remote sessions if web applications access Cams HTTP request headers (see the Cam's Programmer's Guide - Accessing HTTP Headers). If you are not using remote session resources, you can increase performance by setting the cams.http.headers property to false.
Cams web agents obtain remote session data from the Cams policy server for each access control request. To increase performance you can enable remote session caching. When you enable remote session caching, the Cams web agent obtains the remote session data from the Cams policy server at session creation time and then uses local cached session data for subsequent requests throughout the user session.
NOTE: Using cached session information is only valid if you do not expect the session data to change during the lifetime of the session. For example, you may use a Cams session event handler to obtain database values that are stored in the user session. If this database value is dynamic, you may not want to cache remote sessions.
Table 3 summarizes the general configuration remote session caching parameters for Cams web agents.
| Name | Description |
|---|---|
| cams.session.cache |
Enable/disable session caching using values true or false. Session information is needed by a Cams web agent only if web server-based applications wish to make use of Cams HTTP request header values. (This is controlled by the independent configuration parameter: cams.http.headers). If cams.http.headers=true and a session is cached by the Cams web agent, then the cached information is used to populate Cams HTTP request headers. If the session is not currently cached, the Cams web agent will retrieve it from the Cams policy server. If session caching is disabled and cams.http.headers=true, then the session information is accessed from the Cams policy server for every HTTP request. For this reason, use of Cams session caching is recommended. |
Table 3 - General session caching parameters in cams-webagent.conf
Before you start the web or application server containing a Cams web agent, you'll need to ensure that the Cams policy server knows about it. This is a two step process:
When a Cams web agent starts up, it must authenticate with a Cams policy server. To accomplish this, it sends the principal and credential values supplied in cams-webagent.conf, which by default are:
By default, the Cams policy server includes the cams-web-agent username in the system security domain's cams-user.xml file as shown in Example 1.
<cams-users> <!-- Cams http agent connection authentication accounts --> <user name="cams-web-agent" password="password" roles="cams-agent"/> <!-- Default Cams administrator account --> |
| Example 1 - Default system security domain's cams-users.xml content |
If you make changes to the cams.webagent.conf principal or credential properties, you need to make sure that the values in the system security domain's cams-users.xml file correspond.
You must setup access control rules and permissions for the HTTP resources accessible from your web or application server, otherwise the default bias of the system security domain will apply. The default bias specifies if resources not explicitly protected within a security domain should be granted or denied access. The default bias of the system security domain is always deny.
Rather than presenting a discussion on security domain administration, access control rules, and permissions, you are advised to reference the corresponding documents in the Cams Adminstrator's Guide on:
That's it, you should now be able to start your web or application server to test your Cams web agent configuration. After you've started both the web and/or application server with the Cams web agent and the Cams policy server, test the configuration using the appropriate cams-webagent-test script. See web agent-specific documentation for more details.
http://[hostname:port]/cgi-bin/cams-webagent-test.sh (Apache 1.3/2.0 web agent on Linux)
http://[hostname:port]/cams/cams-webagent-test.jsp (Tomcat, ServletFilter web agents on any J2SDK 1.3/1.4 supported OS)
http://[hostname:port]/cams/cams-webagent-test.asp (IIS web agent on Windows)
Login to an account in the security domain that you've established. See the test page for more configuration and testing information.
© Copyright 1996-2004 Cafésoft LLC. All rights reserved.