Back | Next | Contents Cams Administrator's Guide

Integration Quick Start

This document guides you through a simple Cams integration assuming that you've already installed and tested the Cams policy server. Before proceeding, you should be familiar with the terminology and concepts addressed in the Cams Tour and the Introduction.

Most of the activity associated with a Cams integration is centered on the XML files containing configuration parameters for each security domain you deploy. In summary, the steps you'll take are:

  1. Configure the security domain registry
  2. Configure the system security domain
  3. Configure a rule and permission
  4. Set the Cams policy server bind address
  5. Configure a Cams web agent
  6. Test

These instructions use the symbol CAMS_HOME to represent the directory in which you've installed the Cams policy server.

WARNING: Make sure that you follow the instructions in this document closely to ensure that your first Cams integration is successful. Once you've come through the initial learning curve and integration, it will be much easier to branch out, make changes specific to your environment and try more advanced options!

Step 1 - Configure the security domain registry

The file security-domain-registry.xml defines the security domains available within a Cams policy server. By default, the security domain registry is in located in CAMS_HOME/conf/domains. You can change the location by editing the CAMS_HOME/conf/cams.conf value:

security.domain.registry.factory.params=${cams.home}/conf/domains/security-domain-registry.xml

These instructions assume that you leave the security domains in their default location. Open the file CAMS_HOME/conf/domains/security-domain-registry.xml in a text editor. The default Cams policy server includes two security domains:

In the default security-domain-registry.xml file contents shown in example 1.

<!-- User-defined variables that apply across all security domains -->
<var-list>
 <var name="cams.logs.base.dir" value="${cams.home}/logs"/>
</var-list>

<!-- The system security domain (required) -->
<security-domain enabled="true">
 <name>system</name>
 <home>${cams.home}/conf/domains/system</home>
</security-domain>
<!-- The mydomain security domain (template) -->
<security-domain enabled="false">
 <name>mydomain</name>
 <home>${cams.home}/conf/domains/mydomain</home>
</security-domain>

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

To disable a security domain, set the enabled flag to false. To completely remove a security domain, delete the references in security-domain-registry.xml and remove the corresponding directory and files. To add a new security domain, create a reference to it in security-domain-registry.xml similar to those shown above but using the new name. Then, create a new subdirectory with the corresponding security domain name and copy the template XML files from the default mydomain template to the new security domain.

The system security domain should never be deleted or disabled. By default, it protects all HTTP/HTTPS resources, is used for Cams web agent authentication and is always the initial point of permission delegation to other security domains.

Generally, most Cams sites use only the system security domain. You can create and nest as many user security domains as required for your administrative purposes. For example, you might consider creating and nesting user security domains when:

  1. You are managing different user communities from the same Cams policy server. For example, a company may want to manage its intranet and extranet users and resources separately. Or, an ISP may have multiple customers where each would have their own security domain with their own user communities and protected resources.
  2. You want to delegate management of the access control policy for resources to multiple individuals within your organization.
  3. You have auditing or other configuration needs that are facilitated by partitioning resources. For example, you might want to log all Cams web agent authentications within a particular security domain and user authentication and access control events in another.

NOTE: Cams web single sign-on is currently supported for resources managed by a single security domain and within the same DNS domain. If you delegate resources to more than one security domain, users must authenticate with each security domain (even if the security domains use the same web server, DNS domain and user directory). A future release of Cams will support web single sign-on across Cams security domains and DNS domains.

Example 1 shows use of the value ${cams.home}, which is a security domain substitution value. You can create your own substitution values in any security domain configuration file using the syntax shown. Substitution values are hierarchically inherited from the security domain registry by other security domain configuration files. Additionally, the following substitution values are provided by Cams and are always available in any security domain configuration file:

Step 2 - Configure the system security domain

Each security domain configuration requires three configuration files:

NOTE: The cams-users.xml user directory is optionally included in each security domain. This user directory is loaded into memory and only recommended for development/test, Cams web agent authentication and small production user communities. Most production security domains will configure Active Directory, LDAP or an SQL database as the user directory.

Access Control Policy

The access-control-policy.xml file configures a Cams access control policy, which consists of a default bias, permissions and rules. Rules define how an access control policy will protect resources. Some of the rules you'll use are supplied with Cams (they're called intrinsic rules). You can also create custom rules and/or combine existing rules to create new ones. A permission is the binding of a rule to a specific resource pattern (e.g. a URL pattern for HTTP resources). The default bias specifies if access to resources without matching permissions will be granted or denied.

Open CAMS_HOME/conf/domains/system/access-control-policy.xml in a text editor. At the top of the file you see the declaration of an access control policy, the default bias setting and the last modified time:

<access-control-policy defaultBias="denied" lastModifiedTime="200504011200">

It is recommended that you set the default bias to denied and grant access as required to specific resources. This helps prevent situations where access is accidentally granted due to a misconfiguration or omission in the access control policy. Also, you must increment the lastModifiedTime to have a running Cams policy server attempt to reload access-control-policy.xml.

Example 2 shows the system security domain's default HTTP permissions. The permission that applies to a given access control check is determined by:

  1. A matching action - The HTTP action(s) specified in the access control check must match a permission's HTTP action(s). Valid HTTP actions include GET, POST, HEAD, PUT, DELETE, TRACE and OPTIONS. If a permission does not specify any actions (actions="" or the actions attribute is missing), then all HTTP actions are implied.
  2. The most specific matching resource pattern - For HTTP permissions, the most specific pattern is weighted in order of URI, port, host and scheme.

If no permission contains a matching action and resource pattern for a given access control check, then the default bias determines whether access to the resource is granted or denied.

Cams URL-based resource patterns have the following general form:

schemePattern :// hostPattern : portPattern / uriPattern

Hard values can be specified as well as wildcards to match in any of the four components (scheme, host, port or URI). For example, the following are all valid permission resource patterns:

See the Configuring Cams Access Control Policy for more information on resource pattern matching.

In Example 2, the first two permissions unconditionally grant access to the cams and cgi-bin/cams- resources. This ensures that Cams login/logout URIs and the login, denied and error pages can always be accessed. The next permission unconditionally grants access to all HTTP/HTTPS resources. A permission always has either an <acr-ref> or <owner> tag. The <acr-ref> references an access control rule that will be evaluated when the permission is applied because it best matches a resource request. In this permission, the intrinsic Cams granted rule always grants access. The next permission is not active but is included to show use of the <owner> tag, which would delegate access control to the mydomain security domain for matching resources, if uncommented. The last permission, used for testing Cam web agents, is also not active by default.

NOTE: You activate the last two permissions by uncommenting them (move the trailing "-->" above the XML tag elements). You must also enable the mydomain security domain in the security domain registry before you use a permission that delegates to it.

<!-- HTTP and HTTPS resource permissions -->
<permission-collection type="http" desc="HTTP/HTTPS permissions">

  <!-- Grant access to the Cams login/logout URIs and the Cams login,
       denied, and error pages. 

       WARNING: You MUST grant access to these Cams resources or the 
       user will not be able to login/logout, or be redirected
       to the error or denied pages.
  -->
 <permission desc="Cams default pages" actions="GET,POST">
  <resource-pattern id="*://*:*/cams/*"/>
  <acr-ref id="granted"/>
 </permission>		

 <permission desc="Cams Apache default pages" actions="GET,POST">
  <resource-pattern id="*://*:*/CGI-bin/cams-*"/>
  <acr-ref id="granted"/>
 </permission>	

 <!-- Default permission: Unconditionally grant access to all HTTP/HTTPS
      resources -->
 <permission desc="All HTTP/HTTPS requests" actions="">
  <resource-pattern id="*://*:*/*"/>
  <acr-ref id="granted"/>
 </permission>
 <!-- Example: Delegate all HTTP/HTTPS permissions for "/myresource/*" to 
      another security domain. Uncomment to enable.
 <permission desc="Delegate all HTTP/HTTPS requests" actions="">
  <resource-pattern id="*://*:*/myresource/*"/>
  <owner id="mydomain"/>
 </permission>
 -->
 <!-- Example: Apply an access control rule to the Cams test
      page that only grants access to authenticated users with the 
      administrator role. Uncomment to enable. 
 <Permission desc="allow administrators to access Cams test page" actions="">
  <resource-pattern id="*://*:*/cams/camstest*"/>
  <acr-ref id="cams administrator rule"/>
 </permission>
 -->

</permission-collection>

Example 2 - Permissions from the default system security domain

Before exiting access-control-policy.xml, look at the <permission-collection type="cams">. This permission collection defines the permissions for Cams web agent connections. You'll see the access control rule reference:

<acr-ref id="cams agent rule"/>

Example 3 shows the access control rules section of the file, marked by the <acr-lib> tags. You see that the cams agent rule requires that authenticated Cams web agents have the cams-agent role. Now, open the cams-users.xml user directory to see that the cams-web-agent user has the cams-agent role. Without it, an authenticated Cams web agent would be denied access to the Cams policy server.

NOTE: If you decide to configure the system security domain to use and LDAP or SQL database for the user directory, you'll need to create an account for cams-web-agent with the cams-agent role to ensure that Cams web agents can authenticate. You could alternatively stack login modules.

The cams administrator rule grants access to resources that require the authenticated user to have the administrator role. By uncommenting the last default permission, this rule will require authentication to access the Cams web agent test page. 

<!-- Library of access control rules -->
<acr-lib>
 <!-- Cams administrators must have the "administrator" role	-->
 <auth-acr id="cams administrator rule">
  <role-constraint>
   <role-name>administrator</role-name>
   <role-class>com.cafesoft.cams.auth.CSRolePrincipal</role-class>
  </role-constraint>
 </auth-acr>
 <!-- Cams agents must have the "cams-agent" role -->
 <auth-acr id="cams agent rule">
  <role-constraint>
   <role-name>cams-agent</role-name>
   <role-class>com.cafesoft.cams.auth.CSRolePrincipal</role-class>
  </role-constraint>
 </auth-acr>

</acr-lib>

Example 3 - Rules from the default system security domain

You should experiment with the permissions and rules explained in this section to get a feel for how to configure a Cams access control policy. Remember, you can dynamically reload the access-control-policy.xml file by incrementing the lastModifiedTime and saving the file. Make sure you check in the console where you start the Cams policy server to determine if any parsing errors occur. If they do, the Cams policy server will not reload the access-control-policy.xml file.

Login Configuration

These instructions assume that you are using for now the XML-based Cams user directory with the system security domain, which is already configured by default. Hence, you only need to ensure that the login URL is correctly defined in login-config.xml file.

Open CAMS_HOME/conf/domains/system/login-conf.xml in a text editor. Scroll to the bottom of the file where you will see the XML tag elements shown in example 4.

<!-- The Cams policy server sends the camsLoginUrl value to a Cams web agent when an
     access check requires user authentication. The Cams web agent then redirects
     the user's browser to the camsLoginUrl, which must always reference an HTML 
     form that:
				 
     1) Prompts the user for login credentials (e.g., the default 
        NamePasswordCallbackHandler requires form field values "cams_cb_username" 
        and "cams_cb_password" for the username and password respectively.
     2) POSTs the credentials to the login URL configured by the Cams web agent 
        ("/cams/login" by default).
     The value of camsLoginUrl can be an absolute or relative URL. Any
     server with a Cams web agent can be used provided the server is in the
     same Internet domain as the web server that made the original request.
 				
     NOTE: You must change camsLoginUrl to reference a login page at your site.  				
     For example, IIS sites might use "/cams/login.asp" and Apache sites might 
     use "/CGI-bin/cams-login.sh". -->
<login-parameters>
 <login-parameter name="camsLoginUrl" value="/cams/login.jsp"/>
</login-parameters>

Example 4 - Defining the login URL in login-config.xml

The comment in example 4 describes the importance of ensuring this value is correct. When the Cams policy server requires a user to be authenticated, a message is sent to the corresponding Cams web agent with the camsLoginURL value. The Cams web agent then redirects the user's browser to the page specified by the camsLoginURL value, which prompts the user for authentication credentials. If this value is not correct, Cams will not be able to authenticate users.

WARNING: Do not forget to configure this value, it is easily overlooked but essential to correct operation of Cams!

Step 3 - Configure a rule and permission

This step will guide you through the creation of a custom rule and permission in the system security domain.

Open CAMS_HOME/conf/domains/system/access-control-policy.xml in a text editor. By default, access is granted to all HTTP/HTTPS requests with any HTTP actions (e.g., GET, POST, HEAD, PUT, DELETE, TRACE, OPTIONS). Specifying HTTP actions enables access control to be specific to a resource and action(s). So, you could have multiple permissions that apply to the same HTTP URL, but differ according to the requested action. For example, you could unconditionally grant access to a URL for the GET action, but require an authenticated user with the webmaster role for DELETE and PUT actions.

The access control rule reference to granted, <acr-ref id="granted"/>, is an intrinsic Cams rule that grants public access to the matched resource. In this case, it is applied to the root directory for all HTTP and HTTPS resource requests. To tighten security for a system HTTP resource request, first, define an access control rule that requires a user to have the myrole role. Between the <acr-lib> and </acr-lib> tags, create the new rule by inserting:

<!-- Requires authenticated users to have the "myrole" role -->
<auth-acr id="require myrole">
 	<role-constraint>
 	  <role-name>myrole</role-name>
 	</role-constraint>
</auth-acr>

Now, edit the HTTP resource permission by changing the tag <acr-ref id="granted"/> to:

<acr-ref id="require myrole"/>

The permission should now look like:

<!-- Grant GET and POST permission to all HTTP resources -->
<permission desc="HTTP Permissions" actions="GET,POST">
 	<resource-pattern id="*://*:*/*"/>
 	<acr-ref id="require myrole"/>
</permission>

Alternatively, you might leave the default permissions intact and add a new permission to protect only a specific directory. For example, to secure a directory (and all of its contents) on your web server named mysecuredir, add the following permission:

<!-- Grant GET and POST permission to all HTTP resources -->
<permission desc="HTTP Permissions" actions="GET,POST">
 	<resource-pattern id="*://*:*/mysecuredir/*"/>
 	<acr-ref id="require myrole"/>
</permission>

Save and exit the file. Next, you need to add a user with the myrole role to the cams-user.xml file in the system security domain. Using a text editor, add the following line to CAMS_HOME/conf/domains/mydomain/cams-user.xml:

<user name="myuser" password="myuser" roles="myrole"/>

Save the file.

Cams is now configured to require users to authenticate with the myrole role to access the HTTP/HTTPS resources protected in the system security domain by myrule. If you want to use an LDAP or SQL user directory instead of cams-users.xml, you'll need to configure authentication in login-config.xml file. To learn more, read the Login Configuration document.

Step 4 - Set the Cams policy server bind address

By default the Cams policy server listens for network connections on the loopback IP address (127.0.0.1). However, only Cams web agents running on the same Cams policy server can connect using this address. Because you'll probably use a Cams web agent that is installed on a different system, you'll need to set the Cams policy server bind address to an IP address that is accessible from the Cams web agent's host.

The Cams policy server bind addresss is specified as a command-line parameter when Cams is started. For example, if the system on which the Cams policy server is installed is 192.168.1.101, then:

-Dcams.server.bindaddr="192.168.1.101"

will tell the Cams policy server to bind to that IP address. If the value of this parameter is not a valid IP address or is not an IP address assigned to the local system, then a fatal configuration error will be reported and the Cams policy server will fail on startup. If this parameter is not specified, the Cams policy server will bind to the first IP address returned from the list of IP addresses assigned to the local system.

To set the Cams policy server bind address:

Windows

Edit CAMS_HOME\conf\runcams.conf and set -Dcams.server.bindaddr to your server's IP address:

wrapper.java.additional.4=-Dcams.server.bindaddr=192.168.1.101

Linux/UNIX

Edit CAMS_HOME/bin/runcams.sh and set -Dcams.server.bindaddr to your server's IP address:

P="-Dcams.home=${CAMS_HOME}"
P="${P} -DvalidateXML=\"true\""
P="${P} -Dcams.server.bindaddr=192.168.1.101" 
if [ -n "${SECURITY_POLICY_FILE}"    ] ; then 
   P="${P} -Djava.security.manager"
   P="${P} -Djava.security.policy==${SECURITY_POLICY_FILE}"
fi

Step 5 - Configure a Cams web agent

Follow the instructions in the Cams web agent guide to install and configure a Cams web agent of your choice (Cams web agent guides can be found at the Cafésoft Documentation Center). Make sure that you follow the configuration instructions to ensure that the values in cams-webagent.conf are correct for your Cams policy server installation. Specifically, make sure that the following values are correctly defined in the cams-webagent.conf file:

  1. cams.server.url.MyCamsServer - set to the IP address (configured in Step 4) or host name and port of the Cams policy server to connect to (the substring MyCamsServer must match the cams.server.name value specified in CAMS_HOME/conf/cams-reg-default.conf)
  2. cams.after.logout.url - set to the default page to redirect to after logout (can be a relative or fully qualified URL to another system)
  3. cams.client.authentication.principal and cams.client.authentication.credential - set to values that match the authentication credentials in the system security domain user directory (by default, the system security domain's cams-user.xml includes username cams-web-agent for this purpose)
  4. cams.skey.algorithm, cams.skey.key, and cams.skey.iv - set to the same values that are defined in the Cams policy server CAMS_HOME/conf/cams.conf file

This document assumes that you have placed at least one file, named index.html, at the root level of the protected web server's document tree. Furthermore, the document assumes that you have installed and configured the Cams login, error and denied pages or scripts. See the Cams web agent-specific installation and configuration instructions for information on these pages.

WARNING: Your Cams access control policy must grant unconditional access to the Cams login, error and denied pages as well as the Cams login and logout URIs for correct operation. The default system security domain's access-control-policy.xml file provides examples.

Step 6 - Test

You're now ready to test the configuration by starting the Cams policy server.

NOTE: If you have installed the Cams policy server as a Windows service, it is recommended that you use the console command shown below during development to see output on the screen.

Windows

%CAMS_HOME%\bin\runcams.bat

Linux/UNIX

$CAMS_HOME/bin/runcams.sh

This document assumes you are using the Tomcat web server. To start Tomcat with the Cams web agent:

Windows

%CATALINA_HOME%\bin\startup.bat

Linux/UNIX

$CATALINA_HOME/bin/startup.sh

NOTE: The order in which you start Cams policy servers with Cams web agents are not order dependent, you can start or restart the Cams policy server and Cams web agents in any order.

To test the integration, try to access:

http://localhost:8080/index.html

or

http//localhost:8080/mysecuredir/index.html

You should see be prompted with the Cams login page where you can login as:

username: myuser
password: myuser

After clicking submit, you should see index.html in your browser.

Congratulations, you have now completed your first Cams security domain configuration. You can find more information in the Security Domain Registry Configuration, Security Domain Configuration, Access Control Services, and Login Configuration and their associated tag references in the appendix.

Back | Next | Contents

© Copyright 1996-2005 Cafésoft LLC. All rights reserved.