Configuration Properties

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.

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.

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.

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>

The relative or fully qualified URL to redirect to (known as the Cams error page) if an error occurs during authentication or when accessing a protected resource. See Scripts for more information on Cams error page creation and integration.

WARNING: The access control policy must ensure that access to the error page is granted.

The relative or fully qualified URL to redirect to (known as the Cams access denied page) if access to a protected resource is denied by the Cams policy server. See Scripts for more information on Cams access denied page creation and integration.

WARNING: The access control policy must ensure that access to the denied page is granted.

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.

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

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.

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

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 1.3 Linux and Solaris
• Apache 2.0 Linux and Solaris

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.

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 1.3 all supported platforms
• Apache 2.0 all supported platforms
• Sun ONE 6.1 on Solaris

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 1.3 Linux and Solaris
• Apache 2.0 Linux and Solaris

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.

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

• sha1 (recommended)
• md5

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.

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.

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.

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.

The algorithm, secret key and initialization vector for encrypting and decrypting selected values sent to/received from the Cams policy server. Valid algorithms are Blowfish, DES and DESede (triple DES). Blowfish uses a 16 byte encryption key, DES uses an 8 byte key and DESede uses a 24 byte key. 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.

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