Cams Administrator's Guide

Security Domain Registry Configuration

Cams uses security domains to logically partition the management of access control, authentication, and logging. Each Cams server will usually have multiple security domains, each of which must be declared in the security domain registry. Each Cams security domain includes at least the following configuration files:

access-control-policy.xml
login-config.xml
security-domain.xml

The Cams security domain registry maintains basic information about each security domain known to Cams, including the name and location of configuration metadata. The security domain registry also enables you to define global varialbes that are passed to all security domains and can be referenced within their configuration files.

This document describes the values you will use to edit the Cams security domain registry. See also the Security Domain Registry Tag Reference for a complete listing of and reference information on all the XML tags used in the security-domain-registry.xml file.

Configuring the Security Domain Registry Factory

A Cams security domain registry factory is a Java class that loads information about the security domains known to Cams from the security-domain-registry.xml file. This factory is configured in the Cams CAMS_HOME/conf/cams.conf file with the values shown in Example 1.

#
#---	The factory class used to create the SecurityDomainRegistry
#---	and it's configuration parameter(s)
#
security.domain.registry.factory=\
	com.cafesoft.security.engine.domain.XmlSecurityDomainRegistryFactory
security.domain.registry.factory.params=\
	${cams.home}/conf/domains/security-domain-registry.xml

Example 1 - The default Cams server security domain registry factory configuration

The default Cams security domain registry factory (XmlSecurityDomainRegistryFactory), loads an XML registry file located in the directory specified by the parameter. The parameter's ${cams.home} substitution value is specified by the CAMS_HOME environment variable to the Cams Server via the startup script.

Normally, you will only need to change this configuration if you move the security-domain-registry.xml file to another directory. The use of a factory provides the flexibility to store the Cams security domain registry in other document formats or databases should it be required.

Configuring the Cams XML Security Domain Registry

Example 2 shows a Cams XML security domain registry file. This file defines two security domains, system and mydomain, which you'll see at the bottom of the file. To add a new security domain, copy and paste an existing security domain and change the values to reflect the name and location of the new security domain configuration files.

NOTE: Only the system security domain is required, but most installations should delegate resource permissions from the system security domain to one or more custom security domains for adminstrative purposes.

<?xml version="1.0"?>
<!DOCTYPE security-domain-registry SYSTEM 
 "http://cafesoft.com/security-domain-registry_1_0.dtd">

<security-domain-registry>

 <!-- Global variables (you can define your own as required)

  http.resource.base.id - the fully qualified root domain (including port)
                          for the connection to resources protected by a
                          Cams http agent
 https.resource.base.id - the fully qualified root domain (including port)
                          for the SSL/TLS connection to resources protected
                          by a Cams http agent

     cams.logs.base.dir - the directory for the Cams Server log files
 -->

  <var-list>
    <var name="http.resource.base.id" value="http://localhost:8080"/>
    <var name="https.resource.base.id" value="https://localhost:8443"/>
    <var name="cams.logs.base.dir" value="${cams.home}/logs"/>
  </var-list>

  <!-- System security domain -->
  <security-domain enable="true">
    <name>system</name>
    <home>${cams.home}/conf/domains/system</home>
  </security-domain>

  <!-- Mydomain security domain -->
 	<security-domain enable="true">
    <name>mydomain</name>
    <home>${cams.home}/conf/domains/mydomain</home>
  </security-domain>

</security-domain-registry>

Example 2 - A Cams server security domain registry configuration

As you can see in Example 2, var-list/var elements can be used to define global variables for use throughout the Cams server environment. These variables make it easier for you to work with resource permissions and other values found throughout the security domain configuration files. You can define as many variables as you require.

Variables defined in the security domain registry are inherited by every security domain, where they are available for use within every XML configuration file. You can also define global variables for use only within a specific security domain configuration file (or to override a global variable set in security-domain-registry.xml).

In addition to global variables you define, the following global variables are provided by the Cams server and are always available in every security domain:

cams.home - The fully qualified path to the Cams server installation directory (set based on an environment variable defined within "runcams.bat" or "runcams.sh").
cams.server.name - The name assigned to the Cams server installation within configuration file: ${cams.home}/conf/cams.conf. This value is used primarily within the system security domain, which control access to services used by Cams agents.
cams.server.port - The TCP/IP port number on which the Cams server listens for connection by agents as configured in ${cams.home}/conf/cams.conf. This value is used primarily within the system security domain, which control access to services used by Cams agents.
cams.security-domain.name - The security domain-specific name (set based on the <name> element of a <security-domain> registration).
cams.security-domain.home - The security domain-specific home directory (set based on the <home> element of a <security-domain> registration).

The variable cams.logs.base.dir is defined within security-domain-registry.xml and used throughout the default security domain configuration files shipped with Cams. This variable is used to centralize the location where each security domain writes its log files. If you want security domain log files to be written to different, security-domain-specific directories, you can override the value of this variable within the desired security-domain.xml file, or you can hard-code the log file path within security-domain.xml. See Security Domain Configuration for more information.

Back | Next | Contents