Back | Next | Contents Cams Web Agent Guide

Configuration Properties

Cams web agents are configured with properties found in each Cams web agent's cams-webagent.conf file. As you work with Cams, you'll become more familiar with the critical values, which are common to all Cams web agents.

This document contains information to help you understand Cams web agent configuration properties and which web agents use them, as shown in Table 1 in the order they appear within the cams-webagent.conf file.

NOTE: Generally, the properties you should focus your attention on are found at the top of the cams-webagent.conf file. Properties with values that must have matching Cams policy server configuration or security domain values are highlighted in bold red in Table 1. If not otherwise noted, the properties are common to all Cams web agents.

WARNING: Properties in cams-webagent.conf that are not documented on this page configure debug, loggers and Cams protocols or services. You should not change these values unless instructed to do so by Caf�soft support.

Name Description
cams.debug
cams.cluster.debug
cams.attributes.debug

Toggle Cams policy server, cluster and attributes debug messages on/off [true|false]. If you enable cams.attributes.debug you must also enable cams.debug for attributes debug messages to appear. Debug messages

WARNING: Turning on debug will diminish Cams web agent performance
# and cause the cams-webagent.log file to rapidly grow.

cams.cluster.name

The name of the Cams cluster to which this Cams web agent will delegate requests. This value is used by the Cams web agent to identify Cams session cookies originating from a specific Cams cluster. For example, to use a Cams cluster with the default name MyCamsCluster, use:

  • cams.cluster.name=MyCamsCluster

NOTE: You should change the cluster name as part of a hardening exercise. You might also consider using different cluster names for development, test/qa and production Cams policy servers. This will prevent situations where Cams session cookies for one Cams policy server cluster are submitted by your browser to a Cams web agent associated with a different Cams policy server cluster, which will create a 5100 Cams web agent connection error condition.

cams.server.url.<server-name>

The URL of a Cams policy server to be used. The name of this property will depend on the Cams policy server name. The property value is the Cams policy server bind IP address or hostname and the port. For example, to connect to a Cams policy server with the default name MyCamsServer on bind IP address 192.168.0.10 with the default port 9191, use:

  • cams.server.url.MyCamsServer=cams://192.168.0.10:9191

One property must exist for each Cams policy server in your cluster. For example, the following properties configure a web agent for a two node Cams policy server cluster:

  • cams.server.url.Orville=cams://orville.wrightbrothers.com:9191
  • cams.server.url.Wilbur=cams://wilbur.wrightbrothers.com:9191

Each URL has the form: cams://host:port, where host is a host name or an IP address. For example:

  • cams.server.url.MyCamsServer=cams://myCamsServer.mycompany.com:9191
  • cams.server.url.MyCamsServer=cams://192.168.1.123:9191

WARNING: If the Cams web agent and Cams policy server communicate through a firewall, the firewall must be configured to allow general TCP/IP traffic on the configured Cams policy server port.

cams.heartbeat.interval The number of seconds a Cams web agent will wait between requests to check for the availability of a Cams policy server. The default is 5 seconds.
cams.response.timeout The number of seconds before the Cams web agent will timeout waiting for any response from a Cams policy server.
connection.authentication.type

The type of authentication the Cams web agent will use to authenticate connections that it establishes with the Cams policy server. Supported authentication types include:

  • EncryptedParameters - Used in conjunction with cams.skey.* properties to encrypt the Cams web agent user name, password, Cams cluster name and Cams policy server name sent to the Cams policy server. Authentication is performed on parameters, including the user name, password, agent-configured cluster name and policy server name.
  • EncryptedUsernamePassword - Used in conjunction with cams.skey.* properties to encrypt the Cams web agent user name and password sent to the Cams policy server
  • UsernamePassword - A cleartext user name and password are supplied for authentication (not recommended, but useful for development and debugging)

NOTE: This is NOT the authentication type used to authenticate users, rather it is the authentication type used to authenticate the Cams web agent connections to a Cams policy server.

connection.authentication.principal The principal (or username) the Cams web agent will use to authenticate connections it establishes with the Cams policy server. By default, the system security domain handles web agent authentication with the cams-users.xml user directory configured as the authentication repository.
connection.authentication.credential The credential (or password) the Cams web agent will use to authenticate connections it establishes with the Cams policy server. By default, the system security domain handles Cams web agent authentication with the cams-users.xml user directory configured as the authentication repository.
cams.cookie.prefix

Set the prefix used for all Cams-related cookie names. The Cams session identifier automatic login cookies will use the specified prefix, which may contain any alphanumeric character but must not include punctuation, dash and underscore characters. The default value is CAMS.

Cams session identifier cookies have the following naming convention:

<cookie prefix>_SID_<cluster name>_<security domain name>

Cams automatic login identifier cookies have the following naming convention:

<cookie prefix>_AUTOLOGIN_<cluster name>_<security domain name>

cams.cookie.host-specific

Make the Cams session cookie domain host-specific (true) or DNS domain wide (false).
If true, then login to a web server at www.mydomain.com will create a cookie that is valid only at hosts accessible via fully-qualified host name. For example: www.mydomain.com.

If false, then login to a web server at www.mydomain.com will create a cookie that is valid for all hosts in DNS domain (and sub-domains of) mydomain.com, unless other opitional parameters such as cams.cookie.domain.special.tlds and cams.cookie.domain.mapto.longest are defined. The default value is false (DNS domain-wide cookie created).

cams.cookie.domain.special.tlds

An optional, comma-separated list of special DNS top-level domains (TLDs) that are allowed to have a session cookie domain 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 depth 2 for non-special top level domains).

cams.cookie.domain.mapto.longest

An optional, comma-separated list of cookie domains that 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 name .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.cookie.secure

Make the Cams session cookie secure (true) or not secure (false). This flag tells web browsers to send the Cams session cookie only to SSL-enabled web sites. The default value is false, which tells web browsers to send the cookie to SSL-enable and non-SSL URLs within the configured cookie domain.

NOTE: before setting this value to "true", you should test your web site to ensure that users authenticate with Cams through an SSL-enabled URL and access only SSL-enabled URLs when an authenticated user identity is required.

cams.cookie.secure.enforce-secure-connection.enabled

This propoerty applies when cams.cookie.secure=true, and is used to enable or disable secure connection enforcement. If true, then the web agent will require an incoming TLS or SSL (HTTPS) connection before invoking any service that might create a Cams session cookie, including: normal authentication, CDSSO, AESO, etc. This ensures that a secure Cams session cookie is not exposed to a client connecting via a non-secure connection.

In some deployment topologies, it may be preferrable to disable this secure connection enforcement. For example, when access to a web site is through a TLS/SSL-enabled load balancer or proxy server which proxies HTTP requests to the web server containing a Cams webagent, it may be desirable to disable the web agent secure connection contraint. This enables the web agent to return Cams secure session cookies to browsers via the secure connection browsers initiate to the load balancer/proxy server.

NOTE: when secure Cams session cookies are enabled, disabling web agent enforcement of secure connections must ensure that session cookies are requested ONLY via an upstream secure connection. Otherwise, a secure Cams session cookie may be exposed via a non-secure connection. Reputable web browsers will not accept/cache such cookies, but possibly malicious HTTP clients may gain access to these cookies for use in session hijacking attacks.

cams.cookie.httponly

Make the Cams session cookie "HTTPOnly" (true), which tells web browsers to use the cookie for normal HTTP requests, but not to make the cookie available to client-side scripts like Javascript. The default setting is false.

NOTE: this feature is currently available only for Cams native web agents (Apache, IIS, SunONE) and not Cams Java-based web agents because support for "HTTPOnly" is not available in the Java Servlet API until version 3.0. If you need support for this feature in an environment that uses Servlet API 2.3, 2.4, or 2.5 please contact Cafesoft support.

NOTE: this feature is available only for "modern" web browsers. See Browsers Supporting HTTPOnly maintained at teh OWASP web site. If all your users have browsers supporting "HTTPOnly" and your site has no need to process the Cams session cookie using a client-side scripting language, then this option is recommended to help protect against cross-site scripting attacks.

cams.login.uri

The Cams web agent will interpret HTTP POST requests to this exact URI as a login (authentication) request. Posted parameters (usually hidden fields) MUST include:

  • cams_security_domain
  • cams_login_config
  • cams_original_url

and will also usually include callback parameters used by Cams policy server login modules. For example:

  • cams_cb_username
  • cams_cb_password

The actual callback parameters posted must match those expected by the callback handler login module configured with the specified security domain/login config entry.

cams.sso.uri

The Cams web agent will interpret HTTP GET requests to this exact URI as a cross DNS domain web single sign-on request. The Cams web agent uses this URI in its role as a Cams session Cookie Provider.

Query parameters sent with the HTTP request contain the single sign-on context that is intercepted by the web agent and sent to the Cams Policy Server for validation. On successful SSO context validation a Cams session cookie is returned and the client is either redirected to the next single sign-on cookie provider URL or redirected to the URL that was requested before login was attempted.

For example if a web agent hosted on web server www.mysite.com has:

cams.sso.uri=/cams/sso

then if SSO context validation succeeds a Cams session cookie will be returned for the specified Cams cluster and security domain and the "mysite.com" cookie domain or "www.mysite.com" host depending on the value of cams.cookie.host-specific.

cams.aeso.uri

The Cams web agent will interpret HTTP GET requests to this exact URI as a "Automatic Enterprise Sign-On" (AESO) request. Cams AESO provides "automatic" login to Cams by using an identity already established by some other means: usually a desktop login via Kerberos, X.509 certificates or some other native authentication method.

For AESO to work properly, the web server must authenticate the user when this URI is requested. After successful native authentication, the Cams web agent will be able to get the trusted user identity from the web server's internal data structures and create a Cams SSO session. If properly configured, use of Cams AESO will be invisible to users.

Query parameters sent with the HTTP request designate the Cams security domain, the login configuration entry to be used for AESO login, and the URL to which the user is to be redirected after successful login.

The default value for this property is:

cams.aeso.uri=/cams/aeso

For more information, see Automatic Enterprise Sign-On (AESO) Configuration in the Cams Administrators Guide.

cams.logout.uri

The Cams web agent will interpret HTTP GET and POST requests to this exact URI as a logout request. Because a given user may be logged into multiple security domains simultaneously, the web page referencing this URI must specify the security domain name associated with the logout request as a query parameter. For example, if a web agent hosted on web server www.mysite.com has:

cams.logout.uri=/cams/logout

then the following request will attempt to logout the user that is logged into security domain system:

http://www.mysite.com/cams/logout?cams_security_domain=system

cams.after.logout.url The URL to which a user is directed AFTER successful logout. This might be a web site or portal home page. See Scripts for more information on using this and dynamic Cams after logout URLs in your site's pages.
cams.loginconfig.entry The login-config-entry to use to authenticate clients. This value corresponds to a login-config-entry that is defined in the corresponding security domain's login-config.xml file, which defines the login modules, callback handler and any login parameters to be used. Typically, the default value http is used for web resources.
cams.login.x509.cert.enable

Toggle Cams x509 client certificate authentication on/off [true|false]. If enabled, and a client X509 certificate is available on HTTP requests to the configured Cams login URI (e.g., /cams/login), then send the client certificate to the Cams policy server as a callback value named x509_client_cert.

This property is required for all Cams web agents EXCEPT:

  • Apache 2.0 on Windows
cams.autologin.enabled

Toggle Cams automatic login handling on/off [true|false]. Automatic login enables a persistent cookie with encrypted user name and password value to be stored in a user's browser. This cookie is detected by the Cams web agent on subsequent visits to automatically and transparently authenticate the user.

NOTE: This property requires configuration changes to the associated Cams policy server security domain's security-domain.xml file. See the Cams Administrator's Guide - Configuring Automatic HTTP User Login for more details.

cams.autologin.mode

Sets the automatic login handling mode to "reactive" (default) or "proactive". Valid values include:

  • reactive - automatic login is attempted when autologin is enabled, an access control response from a Cams policy server indicates that access is denied because authentication is required and the current request contains an AUTOLOGIN cookie for the applicable security domain. If this property is not specified, the default mode is reactive.
  • proactive - automatic login is attempted by the agent whenever an HTTP request contains an AUTOLOGIN cookie for a security domain, but no corresponding session identifier cookie. Automatic login is also attempted in various other contexts in which the session corresponding with an existing session identifier is expired or closed and also when access is denied because authentication is required.

NOTE: As of August 6, 2010 this property applies only to native (non-Java) Cams web agents. Proactive AUTOLOGIN mode may be added for Java-based agents in the future if requested by customers.

NOTE: Proactive automatic login requires Cams Policy Server version 3.0.74 or later.

cams.autologin.proactive.security_domains

This configuration property applies when cams.autologin.mode=proactive and indicates the security domain(s) for which the proactive attempt at automatic login is attempted. Multiple security domain names must be separated using the comma (,) character.

NOTE: As of August 6, 2010 this property applies only to native (non-Java) Cams web agents. Proactive AUTOLOGIN mode may be added for Java-based agents in the future if requested by customers.

NOTE: Proactive automatic login requires Cams Policy Server version 3.0.74 or later.

cams.autologin.proactive.loginconfig.entry.<security_domain_name>

Sets the login configuration entry to be used for a given security domain when the automatic login mode is proactive. If not specified for a given security domain, the value of cams.loginconfig.entry is used instead.

NOTE: As of August 6, 2010 this property applies only to native (non-Java) Cams web agents. Proactive AUTOLOGIN mode may be added for Java-based agents in the future if requested by customers.

NOTE: Proactive automatic login requires Cams Policy Server version 3.0.74 or later.

cams.autologin.cookie.host-specific

Make the Cams AUTOLOGIN cookie domain host-specific (true) or DNS domain wide (false).
If true, then login to a web server at www.mydomain.com will create a cookie that is valid only at hosts accessible via fully-qualified host name. For example: www.mydomain.com.

If false, then login to a web server at www.mydomain.com with Cams automatic login enabled and requested by the user will create an AUTOLOGIN cookie that is valid for all hosts in DNS domain (and sub-domains of) mydomain.com, unless other opitional parameters such as cams.autologin.cookie.domain.special.tlds and cams.autologin.cookie.domain.mapto.longest are defined. The default value is false (DNS domain-wide cookie created).

cams.autologin.cookie.domain.special.tlds

An optional, comma-separated list of special DNS top-level domains (TLDs) that are allowed to have a Cams AUTOLOGIN cookie domain 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 AUTOLOGIN 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 AUTOLOGIN 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 depth 2 for non-special top level domains).

cams.autologin.cookie.domain.mapto.longest

An optional, comma-separated list of cookie domains that limits Cams AUTOLOGIN 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 AUTOLOGIN cookie. For example, using setting:

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

a successful login to web server host www.d3.d2.d1.com with Cams automatic login enabled and requested by the user will create a Cams AUTOLOGIN cookie with cookie domain name .d3.d2.d1.com. Web browsers will send such a Cams AUTOLOGIN cookie to any host in cookie domain .d3.d2.d1.com, but not to a broader cookie domain like .d2.d1.com.

cams.autologin.cookie.secure

Make the Cams AUTOLOGIN cookie secure (true) or not secure (false). This flag tells web browsers to send the Cams AUTOLOGIN cookie only to SSL-enabled web sites. The default value is false, which tells web browsers to send the cookie to SSL-enable and non-SSL URLs within the configured cookie domain.

NOTE: before setting this value to "true", you should test your web site to ensure that users access only SSL-enabled URLs when an authenticated user identity is required.

cams.autologin.cookie.httponly

Make the Cams AUTOLOGIN cookie "HTTPOnly" (true), which tells web browsers to use the cookie for normal HTTP requests, but not to make the cookie available to client-side scripts like Javascript. The default setting is false.

NOTE: this feature is currently available only for Cams native web agents (Apache, IIS, SunONE) and not Cams Java-based web agents because support for "HTTPOnly" is not available in the Java Servlet API until version 3.0. If you need support for this feature in an environment that uses Servlet API 2.3, 2.4, or 2.5 please contact Cafesoft support.

NOTE: this feature is available only for "modern" web browsers. See Browsers Supporting HTTPOnly maintained at teh OWASP web site. If all your users have browsers supporting "HTTPOnly" and your site has no need to process the Cams AUTOLOGIN cookie using a client-side scripting language, then this option is recommended to help protect against cross-site scripting attacks.

cams.access.check.cache

Toggle access control check caching on/off [true|false]. Access control check caching improves performance by enabling the Cams web agent to remember a previous access control check response from the Cams policy server for a specified period of time. Cams web agents ONLY cache responses associated with unconditionally granted or denied resources. This enables public resources like GIF and JPEG image files, Javascript, style sheets, etc. to avoid repeated access control checks. The Cams policy server unconditionally grants or denies access to a resouce if the permission matching the resource directly references a Cams intrinsic access control rule (e.g. granted, denied or confidential).

cams.access.check.cache.size The maximum number of access control check responses that can be cached at a given time. Once the cache is full, newly cached responses will force removal of the least recently used response in the cache.
cams.access.check.cache.max_record_size

The maximum number of bytes that can be used to cache an access cotnrol response. Currently, the only variable length value returned from an access control response and saved to the cache is the security domain name. Consequently, 20 bytes plus the maximum security domain name length is large enough for a cache record, which is stored in shared memory for access by all child processes. A value of 50 (bytes) should be sufficient for most installations.

This property is only available on:

  • Apache 2.0 Linux and Solaris
  • Apache 2.2 Linux and Solaris
cams.access.check.cache.refreshTime The number of minutes 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.
cams.access.url.remove.path.parameters

Toggle removal of HTTP "path parameters" from URL on/off [true|false]. 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. From a Cams access control perspective this has the effect of saying that a single resource is identified by all forms of a URL when path parameters are removed. For example, the following fully-qualified resource identifier (URL):

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

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

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

cams.aeso.enabled

Toggle Cams automatic enterprise sign-on (AESO) on/off [true|false]. If enabled, requests to the configured cams.aeso.uri will be interpreted as AESO requests.

Default value: cams.aeso.enabled=false

For more information, see Automatic Enterprise Sign-On (AESO) Configuration in the Cams Administrators Guide.

cams.aeso.security_domains

A comma-separated list of security domains for which Cams automatic enterprise sign-on (AESO) is configured.

This property is used only if cams.aeso.enabled=true and an HTTP GET request is received on the configured cams.aeso.uri with a query parameter cams_security_domain=domain where domain is a security domain on the list.

Default value: cams.aeso.security_domains=system

If Cams security domains "system" and "mydomain" are both configured for Cams AESO, this property should have value:

cams.aeso.security_domains=system,mydomain

For more information, see Automatic Enterprise Sign-On (AESO) Configuration in the Cams Administrators Guide.

cams.aeso.callback.names.<security_domain>

A comma-separated list of callback value names defined for a given Cams security domain. The security domain name must match one of the names configured in property: cams.aeso.security_domains

For example:

cams.aeso.callback.names.system=username,agent_secret

references two callback values "username" and "agent_secret" for the "system" security domain. Each callback named in this property requires another property that configures how the callback value is propulated from data within the HTTP request. For example:

cams.aeso.callback.value.system.username={http_request:REMOTE_USER}
cams.aeso.callback.value.system.agent_secret=foobar

indicates that the "username" callback value is populated using the "REMOTE_USER" value from the HTTP request, and the "agent_secret" callback value is populated with literal string "foobar".

For more information, see Automatic Enterprise Sign-On (AESO) Configuration in the Cams Administrators Guide.

cams.aeso.callback.value.<security_domain>.<cb_name>

A Cams automatic enterprise sign-on (AESO) callback value specification for a given security domain and callback name. The security domain name must match one of the names configured in property: cams.aeso.security_domains and the callback name must match one of the values defined in property: cams.aeso.callback.names.<security_domain>

A property of this form must be defined for each security domain/callback combination. Consider the following set of configuration properties, which enables Cams AESO processing by the agent, sets the URI where AESO requests are expected, specified two security domains "system" and "mydomain" using AESO, and configures the callback values for each security domain:

cams.aeso.enabled=true
cams.aeso.uri=/cams/aeso
cams.aeso.security_domains=system,mydomain

cams.aeso.callback.names.system=username,agent_secret
cams.aeso.callback.value.system.username={http_request:REMOTE_USER}
cams.aeso.callback.value.system.agent_secret=foobar

cams.aeso.callback.names.mydomain=x509_client_cert,agent_secret
cams.aeso.callback.value.mydomain.x509_client_cert={http_request:x509_client_cert}
cams.aeso.callback.value.mydomain.agent_secret=foobaz

In this example, the "system" security domain is using the "REMOTE_USER" value from the HTTP request to populate the "username" callback value the "mydomain" security domain is using a client X.509 certificate to populate the "x509_client_cert" callback value. Each security domain is using a different literal value for the "agent_secret" callback value, which is used by standard Cams AESO login modules.

For more information, see Automatic Enterprise Sign-On (AESO) Configuration in the Cams Administrators Guide.

cams.session.cache

Toggle user session caching on/off [true|false]. Cams web agents can retrieve user session information from the Cams policy server to inject into HTTP requests as Cams secure HTTP request headers by enabling the cams.http.headers proptery (see also the Cam's Programmer's Guide - Accessing HTTP Headers). Session caching enables the Cams web agent to remember these values so subsequent requests will not need to get the session information from the Cams policy server for a specified period of time.

cams.session.cache.max_sessions

The maximum number of sessions to cache. After this number is exceeded, addition will force deletion of the least recently accessed session first. The cache size should be made at least as large as the number of concurrently authenticated users that typically access your site.

This property is only available on:

  • Apache 2.0 all supported platforms
  • Apache 2.2 all supported platforms
  • IIS 6.0, 7.0 all supported platforms
  • Sun ONE 6.1 on Solaris
cams.session.cache.max_record_size

The maximum number of bytes used for storing a session. If the maximum is exceeded, a warning message is displayed and data is truncated (e.g. some session attributes may be lost).

This property is only available on:

  • Apache 2.0 Linux and Solaris
  • Apache 2.2 Linux and Solaris
cams.session.hijacking.protection.enable

Toggle Cams session hijacking protection on/off [true|false]. Session hijacking is where a hacker steals a session identifier and uses it in another client to gain access to a site. When a user first authenticates and a Cams session is created, a unique hash is computed from using standard browser HTTP request headers (Accept-Language and User-Agent) and unique site values. If a hacker somehow intercepts the Cams session cookie, he would also need to provide the exact HTTP request headers used by the original user's browser to gain access when session hijacking is enabled. A session that is considered hijacked is invalidated by the Cams web agent and a WARNING is written to cams-webagent.log.

NOTE: Cams session hijacking is disabled by default to prevent situations where false positives will cause Cams to ALWAYS deny access to resources that are displayed by browser plugins. You should enable session hijacking as part of a hardening exercise and thoroughly test your site before deploying in a production environment.

WARNING: All Cams web agents in a Cams policy server cluster must be configured with the exact same session hijacking properties. If not, Cams session cookies will not work consistently across all Cams web agents and access to some resources will ALWAYS be denied.

cams.session.hijacking.protection.algorithm

The algorithm used to compute a unique hash value for session hijacking protection. The following algorithms are supported:

  • sha1 (recommended)
  • md5
cams.session.hijacking.protection.salt

A unique, site-specific value that is combined with the other session hijacking protection values to further prevent decoding of the hash. The default value is epsom.

NOTE: You should change this value as part of a hardening exercise.

cams.http.headers

Toggle Cams secure HTTP request headers on/off [true|false]. If enabled then dynamic web page scripts will have access to secure Cams HTTP request headers. See the Cams Programmer's Guide - Webapp Programming for a full list of the Cams secure HTTP request header names and site-specific user attribute values that can be made available to web applications. Disabling Cams request headers when not used improves performance.

NOTE: To improve performance, Cams user session information can be cached by the Cams web agent using the cams.session.cache property. If Cams secure HTTP request headers are disabled, then you should also disable session caching.

cams.http.headers.accept.proxied Toggle proxied Cams secure HTTP request headers on/off [true|false]. If true, then Cams web agents accept Cams secure HTTP request headers that have been proxied to this web agent via another Cams web agent. For example, it is quite common to configure a web server to proxy requests to a J2EE server (e.g. Apache/IIS with Tomcat). If a Cams web agent is configured in both, then you'll need to enable this value in the proxied to web server (e.g. Tomcat in this example) to prevent the Cams web agent from identifying Cams secure HTTP request headers as spoofed by a client. The default value is false.

The value is a Cams cluster constant available in HTTP header cams-http-proxy-signature as a hash:

SHA1(cams.cluster.name + cams.skey.key)

If a Cams web agent is configured to trust proxied Cams HTTP request headers, it will check this value to ensure the received headers were received from another Cams web agent configured for the same cluster. The value should not be revealed via a web page to untrusted users.
cams.http.headers.uri.filter.enable

Toggle filtering of URIs for which Cams secure HTTP request headers will be injected. [true|false]. When this feature is enabled, request URIs are matched against "include" and "exclude" regular expressions. Requests with URIs that match at least one "include" regular expression and don't match any "exclude" regular expressions will have Cams secure HTTP request headers injected.

NOTE: this feature applies only when cams.http.headers=true

cams.http.headers.uri.filter.regex.include.N

Configure a regular expression used to include URIs (file paths) for which Cams secure HTTP request headers will be injected. Configuration options of this form are used only when: cams.http.headers=true and cams.http.headers.uri.filter.enable=true

Multiple properties of this form must have names in sequence from 1 to N, where N is the number of properties. For example:

cams.http.headers.uri.filter.regex.include.1=^/.*\\.pl$
cams.http.headers.uri.filter.regex.include.2=^/.*\\.php$
cams.http.headers.uri.filter.regex.include.3=^/.*\\.sh$

specify include patterns that select Perl scripts (ends with ".pl"), PHP scripts (ends with ".php"), and shell scripts (ends with ".sh"). The default values are specific to the typical environments in which each web agent are deployed.

NOTE: an HTTP request URI must match at least one "include" pattern, but cannot match any "exclude" patterns to have secure Cams HTTP request headers injected.

cams.http.headers.uri.filter.regex.exclude.N

Configure a regular expression used to exclude URIs (file paths) for which Cams secure HTTP request headers will be injected. Configuration options of this form are used only when: cams.http.headers=true and cams.http.headers.uri.filter.enable=true

Multiple properties of this form must have names in sequence from 1 to N, where N is the number of properties. For example:

cams.http.headers.uri.filter.regex.exclude.1=^/proxy/.*$
cams.http.headers.uri.filter.regex.exclude.2=^/docs/.*$

specify exclude patterns that select URIs proxied to another web server (starts with URI "/proxy/") and URIs for static document (starts with URI "/docs/"). The default values are specific to the typical environments in which each web agent are deployed.

NOTE: an HTTP request URI must match at least one "include" pattern, but cannot match any "exclude" patterns to have secure Cams HTTP request headers injected.

cams.attributes.http-param.enable Toggle sending of HTTP query parameter attributes with access control checks on/off [true|false]. Sending HTTP query parameter attributes allows a Cams access control policy to use them for access control rule decisions. The default value is false.
cams.attributes.http-req-headers.enable Toggle sending of HTTP request header attributes with access control checks on/off [true|false]. Sending HTTP request headers attributes allows a Cams access control policy to use them for access control rule decisions. The default value is false.
cams.attributes.http-cookies.enable Toggle sending of HTTP cookie attributes with access control checks on/off [true|false]. Sending HTTP cookie attributes allows a Cams access control policy to use them for access control rule decisions. The default value is false.
cams.attributes.agent.enable

Toggle sending of Cams web agent attributes with access control checks on/off [true|false]. Cams web agent-specific attributes include:

  • urn:cams:1.0:names:access-subject:agent-type (e.g. "web")
  • urn:cams:1.0:names:access-subject:agent-impl (e.g. "apache13")
  • urn:cams:1.0:names:access-subject:agent-version (e.g. "2.1.1")
  • urn:cams:1.0:names:access-subject:agent-id (e.g. "MyWebAgent1")
  • urn:cams:1.0:names:access-subject:agent-os (e.g. "Windows2000")

A Cams access control policy can use these values for access control rule decisions. The default value is false.

cams.attributes.name.validator.regex

A regular expression used to validate http-param, http-req-header, and http-cookie attribute names to ensure they meet conditions for constructing attribute identifiers. Attribute identifiers must be valid Uniform Resource Identifiers (URIs) as defined by RFC 2396. Names that don't match this regular expression are discarded and not sent as attributes within Cams access control requests. If this value is not present, the following default regex is used: ^[a-zA-Z0-9\\-_]{1,128}$

NOTE: This property is applicable to all native (non-Java) Cams web agents. Java-based web agents already validate attribute identifiers via the java.net.URI class, which throws a URISyntaxException for invalid identifiers.

cams.agent.id

An optional value that can be used in conjunction with the property cams.attributes.agent.enable to uniquely identify Cams web agents. If specified, and cams.attributes.agent.enable=true, the value of this property is used to populate the value of attribute:

urn:cams:1.0:names:access-subject:agent-id

This can be used to distinguish requests from and customize access control rules based on a unique Cams web agent identity. If not specified, cams.agent.id defaults to MyCamsAgent.

cams.skey.algorithm
cams.skey.key
cams.skey.iv

The algorithm, secret key and initialization vector for encrypting and decrypting selected values sent between the Cams policy server and Cams web agent. Valid algorithms are AES, Blowfish, DES and DESede (triple DES). AES uses a 16 byte encryption key, Blowfish uses a 16 byte encryption key, DES uses an 8 byte key and DESede uses a 24 byte key. Blowfish is recommended. The number of secret key bytes used depends on the algorithm, although it is legal to supply more key bytes than needed. The initialization vector should be an 8 byte (16 hex digit) value. For more information, see: Cams Administrator's Guide - Securing Cams Communications using Secret Keys.

NOTE: Use CAMS_HOME/bin/camsSecretKeyGen.bat/.sh or the web application
in the Cams Jetty test server to select the algorithm and generate the key and initialization vector values. This should be part of a hardening exercise.

logger.file.path

The fully-qualified path to the Cams web agent log file. If the directory or log file is missing, it will be created. This property is required on most Cams web agents, but not those listed below, where the log file is written to a default location (usually relative to where the Cams web agent binaries are installed).

This property is required for all Cams web agents EXCEPT:

  • Apache 2.0 on Windows
  • IIS
  • Sun ONE 6.1 on Solaris

 

logger.file.append If true new log messages will be appended to the current log file. If false the current log file will be deleted and a new log file will be created. The default value is true.
cams.basic.auth.insertion.enabled

Toggle Cams HTTP Basic Authorization header insertion on/off [true|false]. If true the Cams web agent will add an HTTP Basic Authorization header to the HTTP request if the requested URL has a file path (URI) starting with a configured prefix (see cams.basic.auth.insertion.uri-list) and the authenticated user has the specified session attribute (see cams.basic.auth.insertion.session-attr.namespace and cams.basic.auth.insertion.session-attr.name).

This property is only available on:

  • IIS
cams.basic.auth.insertion.uri-list

A comma-delimited list of URI prefixes for which Basic Authorization
headers will be inserted if cams.basic.auth.insertion.enabled is enabled. We recommend you define the URI patterns as narrowly as possibly to minimize HTTP Basic Authorization header injection to only those web applications for which it is required. You do not need to use a wild card at the end of each prefix.

This property is only available on:

  • IIS
cams.basic.auth.insertion.session-attr.namespace

A Cams session attribute namespace where the web agent will look for the Basic Authorization header attribute value if cams.basic.auth.insertion.enabled is enabled. This value must match the session-attr-namespace value set by the HTTP Basic Authorization managed session event handler.

This property is only available on:

  • IIS
cams.basic.auth.insertion.session-attr.name

A Cams session attribute name where the web agent will look for the Basic Authorization header value if cams.basic.auth.insertion.enabled is enabled. This value must match the session-attr-name value set by the HTTP Basic Authorization managed session event handler.

This property is only available on:

  • IIS
cams.login.param.validator.enable

Toggle validation of login parameters on login requests on/off [true|false]. HTTP parameters sent via the POST method to the URI specified by configuration property cams.login.uri will be validated against an optional parameter-specific regular expression defined by properties of the form:

cams.login.param.validator.regex.<param-name>=<regular expression>

Parameter validation is useful for detecting and thwarting cross site scripting, SQL injection, buffer overflow and other attacks by invalidating parameters containing potentially dangerous character sequences. In particular, values that might ultimately be embedded into a dynamic HTML page should be validated to deny use of certain characters used to tag HTML elements. If one or more login parameters are invalid during a login attempt, Cams 5007 error (invalid login parameter value) is returned, an error is logged to the associated web server's cams-webagent.log and HTTP response status 500 is returned to the client.

cams.login.param.validator.valid-on-unknown

Indicates whether an unknown login parameter (has no validator regular expression defined) is valid (true) or invalid (false). For maximum protection, this value should be set to false and a validator regular expression should be defined for every possible login parameter (form field) that might be received during login, including the value associated with the form's Submit button.

cams.login.param.validator.regex.<param-name>

Define a regular expression that is used to validate the parameter value associated with name <param-name> when posted to the Cams web agent during a login request and the value cams.login.param.validator.enable=true. For example:

cams.login.param.validator.regex.cams_security_domain=^[a-z0-9]{1,12}$

See Table 2 for the default values defined for standard Cams login page parameters. Additional or custom field values can be protected by adding a property that ends with the HTTP parameter name (HTML form field) to be protected and a white list regular expression that matches all valid field values. For example, if your site uses a four digit numeric PIN entered in a form field named cams_cb_pin, then the following property might be used:

cams.login.param.validator.regex.cams_cb_pin=^[0-9]{4}$

NOTE: All login parameters received by the Cams web agent must either have a validator regular expression defined or be declared valid-on-unknown using the cams.login.param.validator.valid-on-unknown configuration option.

Additional information on regular expressions can be found in Regular Expressions. Also, a useful, free application named PCRE Workbench (Perl Compatible Regular Expression Workbench) is recommended for testing regular expressions.

cams.logout.param.validator.enable

Toggle validation of logout parameters on logout requests on/off [true|false]. HTTP query parameters sent via the GET method to the URI specified by configuration property cams.logout.uri will be validated against an optional parameter-specific regular expression defined by properties of the form:

cams.logout.param.validator.regex.<param-name>=<regular expression>

Parameter validation is useful for detecting and thwarting cross site scripting, SQL injection, buffer overflow and other attacks by invalidating parameters containing potentially dangerous character sequences. In particular, values that might ultimately be embedded into a dynamic HTML page should be validated to deny use of certain characters used to tag HTML elements. If one or more logout parameters are invalid during a logout attempt, Cams 5308 error (invalid logout parameter value) is returned, an error is logged to the associated web server's cams-webagent.log and HTTP response status 500 is returned to the client.

cams.logout.param.validator.valid-on-unknown

Indicates whether an unknown logout parameter (has no validator regular expression defined) is valid (true) or invalid (false). For maximum protection, this value should be set to false and a validator regular expression should be defined for every possible logout parameter that might be received during logout.

cams.logout.param.validator.regex.<param-name>

Define a regular expression that is used to validate the parameter value associated with name <param-name> when sent to the Cams web agent during a logout request and the value cams.logout.param.validator.enable=true. For example:

cams.logout.param.validator.regex.cams_security_domain=^[a-z0-9]{1,12}$

The default values for a standard Cams logout request include:

  1. cams_security_domain
  2. cams_after_logout_url

Additional or custom field values may also be sent, though Cams web agents will ignore them. The standard validation regular expression for the standard logout parameters may look like the following:

cams.logout.param.validator.regex.cams_security_domain=^[a-z0-9]{1,12}$

cams.logout.param.validator.regex.cams_after_logout_url=^(https?:(//([a-zA-Z0-9\\-._~%]+)(:[0-9]+)?(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?|(/?[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?)?)|([a-zA-Z0-9\\-._~%!$&'()*+,;=@]+(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?|(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)+/?))(\\?[a-zA-Z0-9\\-._~%!$&'()*+,;=:@/?]*)?(#[a-zA-Z0-9\\-._~%!$&'()*+,;=:@/?]*)?$

NOTE: All logout parameters received by the Cams web agent must either have a validator regular expression defined or be declared valid-on-unknown using the cams.logout.param.validator.valid-on-unknown configuration option.

Additional information on regular expressions can be found in Regular Expressions. Also, a useful, free application named PCRE Workbench (Perl Compatible Regular Expression Workbench) is recommended for testing regular expressions.

cams.login.x509.cert.enable

 

Toggle sending X.509 client certificate with authentication request
on/off [true|false]. Enables X509 client certificates to be used within Cams login modules. This property is available for most existing web agents. See web agent-specific documentation and configuration file for more information.

 

cams.login.x509.cert.header.name

The name of the HTTP header in which the base 64 encoded X.509 client # certificate value is stored. The default value is SSL_CLIENT_CERT, which will be populated if mod_ssl is used for X.509 client certificate negotiation.

If a hardware SSL accelerator/load balancer is used, check your manufacturers documentation for the name of the populated HTTP request header.

NOTE: This value is valid only if cams.login.x509.cert.enable=true

This property is only available on:

  • Apache 2.0
  • Apache 2.2

 

cams.login.x509.cert.header.tablename

The name of the internal Apache HTTP request header table in which to look for the specified X.509 client certificate header value. Valid values include:

  • subprocess_env - lookup the cert value in the subprocess_env header table. Use this value if mod_ssl and the Cams client cert lookup module are in use.
  • headers_in - lookup the cert value in the headers_in header table.
    Use this value if an SSL accelerator/load balancer is used.

NOTE: This value is valid only if cams.login.x509.cert.enable=true

This property is only available on:

  • Apache 2.0
  • Apache 2.2

 

Table 1 - Values you may need to edit in cams-webagent.conf

Parameter Regular Expression
cams_security_domain

^[a-z0-9]{1,12}$

Allows lower case a to z, integers 0 to 9 and 1 to 12 characters in length (supports any valid Cams policy server security domain name). Alternative value: ^(system)$ for sites only using the default system security domain. Alternative value: ^(system|mydomain)$ for sites using a small list of security domains.

cams_login_config

^[a-z0-9]{3,12}$

Allows lower case a to z, integers 0 to 9 and 3 to 12 characters in length (supports any valid Cams policy server <login-config-entry> name). Alternative value: ^(http)$ for sites only using the default http login config entry. Alternative value: ^(http|http2)$ for sites using a small number of <login-config-entry>.

cams_original_url

^(https?:(//([a-zA-Z0-9\\-._~%]+)(:[0-9]+)?(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?|(/?[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?)?)|([a-zA-Z0-9\\-._~%!$&'()*+,;=@]+(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)*/?|(/[a-zA-Z0-9\\-._~%!$&'()*+,;=:@]+)+/?))(\\?[a-zA-Z0-9\\-._~%!$&'()*+,;=:@/?]*)?(#[a-zA-Z0-9\\-._~%!$&'()*+,;=:@/?]*)?$

Enforces RFC 3986 URLs with:

  1. An absolute path within the current web host context:
    absolute_path [[fragment] ? query ]
  2. A fully qualified http or https URL:

    scheme :// host [:port] [ absolute_path [[fragment] ? query ]]

    NOTE: Square brackets enclose optional entities.
cams_cb_username

^[a-zA-Z0-9\\-_@.]{0,20}$

Allows any case a to z, integers 0 to 9, characters "-_@." and 0 to 20 characters in length. For example: admin, john.doe@company.com.

WARNING: If a user enters invalid characters and attempts login, they will see an HTTP 500 error instead of being redirected back to the login page with a failed authentication message. As this might be confusing to users, this regular expression should minimally allow any characters found in the user names at your site. Also, you should ensure that the maximum length is sufficient for all user names in use at your site.

cams_cb_password

^[a-zA-Z0-9\\-_@!$+%#]{0,20}$

Allows any case a to z, integers 0 to 9, characters "-_@!$+%#" and 0 to 20 characters in length.

WARNING: If a user enters invalid characters and attempts login, they will see an HTTP 500 error instead of being redirected back to the login page with a failed authentication message. As this might be confusing to users, this regular expression should minimally allow any characters found in passwords at your site. Also, you should ensure that the maximum length is sufficient for all passwords in use at your site.

cams_cb_autologin_flag

^(true)$

Always "true" (case-sensitive) when used.

Submit

^(Login)$

Always "Login" (case-sensitive) for default Cams login pages.

Table 2 - Regular expressions used to validate default dynamic values submitted by a Cams login page

Back | Next | Contents