Back | Next | Contents Cams Administrator's Guide

Integration Quick Start

This document quickly moves you through Cams integration learning steps and provides hints that might jot down for consideration or follow-up later. You should be familiar with the terminology and concepts addressed in the Introduction and have installed and tested the Cams policy server. The integration steps you'll take in this document include:

  1. Configure authentication
  2. Configure a basic access control policy
  3. Set the Cams policy server bind address
  4. Configure a Cams web agent
  5. Next steps

These instructions use the symbol CAMS_HOME to represent the directory in which you've installed the Cams policy server. Make sure that you follow the instructions closely to ensure that your first Cams integration is successful. Once you've come through the initial integration learning curve, it will be much easier to branch out, make changes specific to your environment and try more advanced options!

NOTE: Most sites use only the required Cams system security domain. This is the default Cams configuration and requires no additional attention unless you want to relocate the security domain files (not recommended) or use multiple Cams security domains to delegate management of resources and user communities. For more information, see Security Domain Registry Configuration. Otherwise, we'll assume you're configuring the system security domains and proceed to the first step.

Step 1 - Configure authentication

Most sites like to configure authentication first and it is advisable to do so before making to many changes like integrating Cams web agents. By default, the Cams XML user directory is configured for HTTP user authentication in the system security domain. In a text editor, open:

CAMS_HOME/conf/domains/system/login-conf.xml

NOTE: Using a text or XML editor that supports XML syntax highlighting will greatly enhance your ability to configure Cams. The free vim editor is an excellent alternative. For those who don't know vi keyboard commands, vim features a Windows notepad editing mode.

The login-config.xml file is divided into three separate <login-config-entry> blocks. Usually, only the top block named http, used for HTTP user authentication, needs configuration (as show in Example 1). The <login-config-entry> block named cams-agent is unique to the system security domain and should be left as is for authentication of Cams web agents.

<login-config-entry name="http">
 <login-module-entry
  className="com.cafesoft.cams.auth.login.module.XmlLoginModule"
  flag="OPTIONAL">
  <options>
   <option name="debug" value="false"/>
   <option name="serviceId" value="cams-directory"/>
  </options>
 </login-module-entry>
 ...
</login-config-entry>

Example 1 - The Cams XML user registry defined in login-config.xml for HTTP user authentication

For now, change the XML login module flag value from REQUIRED to OPTIONAL. This will enable login module stacking when you integrate your user directory, where you can authenticate users with both the Cams XML login module and the one that you'll configure next.

NOTE: It is helpful to leave the Cams XML login module enabled at this point for use with examples below and for Cams web agent integration testing. Once you have completed the exercises in this document and your initial Cams web agent integration, you'll want to disable the XML login module for HTTP user authentication by commenting it out (move the preceding comment end marker ("-->") below the XML tag elements).

Most sites use either Active Directory, an LDAP server or an SQL database for authentication. If you are using something else, please see Login Configuration. The test Jetty web server has login configuration tools to assist with integration using these standard user directories. To configure authentication, start the Cams policy server and the test Jetty web server.

To run the Jetty web server in a Windows console:

cd %CAMS_HOME%\jetty\
camstest.bat

Enter control-C in the console window to stop the Jetty HTTP server.

To start the Jetty test web server on Linux/UNIX:

CD $CAMS_HOME/jetty/
./camstest.sh

Enter http://localhost:8080/ if your web browser is on the same system as the Cams policy server and Jetty web server and http://hostname:8080/ (where hostname is the DNS name or IP address of the system) if your web browser is on a remote system. Then:

  1. Click the link to the login configurator for your user directory.
  2. Follow the instructions on the login configurator page to interactively define the input fields required to generate the XML snippet. NOTE: SQL database configuration requires installation of a JDBC driver in the CAMS_HOME/jetty/ext directory and restarting the Jetty test server.
  3. Generate the XML, cut and paste into the system security domain's login-config.xml directly below the XML login module snippet shown in Example 1.
  4. Change the flag from REQUIRED to OPTIONAL in the generated XML to enable stacked authentication with the XML login module.
  5. Restart the Cams policy server.
  6. Using your browser, navigate to the Cams web agent test page (http://hostname:8080/cams/camstest.jsp) on the Jetty web server. You should now be able to authenticate using either users from your user directory or the default accounts in the system security domain's Cams XML user directory.

For additional information on configuration of these and other login modules, please see Login Configuration.

NOTE: Sites using SQL databases for user authentication should configure the Cams JDBC connection pooling service to maximize performance.

Cams Login URL

When the Cams policy server requires a user to be authenticated, a login page must be served that prompts for user credentials to be sent to the configured login module(s). The Cams policy server requests the Cams web agent to redirect the user's browser to the page specified by the camsLoginURL value.

WARNING: If the configured camsLoginURL is not available on the target web server, a HTTP 404 page not found error will be displayed by your web server instead.

<login-parameters>
 <login-parameter name="camsLoginUrl" value="/cams/login.jsp"/>
</login-parameters>

Example 2 - The Cams login URL is defined in login-config.xml

While you have the system security domain's login-config.xml open, locate the camsLoginUrl value at the bottom of the <login-config-entry> block named http (shown in Example 2). Make sure you review the preceding comment. You don't need to change this now to test with Jetty, which servers the Cams JSP login page. Supplying the camsLoginUrl with the relative path /cams/login.jsp enables the Cams web agent in the Jetty test web server to redirect your browser to that login page.

If you change your Cams integration to use non-Java IIS or Apache web servers, you'll need to reference an ASP or Perl login page. We strongly recommend use of a fully-qualified URL using the secure HTTPS protocol. By specifying use of HTTPS for this URL and for the subsequent POST to the Cams login URI (which is set to /cams/login by default in cams-webagent.conf), you ensure that users see that the login page is secure and that the user's credentials are encrypted when transported to the web server. For example:

NOTE: As an alternative strategy to use ASP and Perl pages, you can configure IIS and Apache with a Java web server like Tomcat using mod_jk to serve JSP pages. Other Java application servers like BEA WebLogic and IBM WebSphere usually use the JSP login page.

Step 2 - Configure a basic 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 protects resources. Some of the rules you'll use are supplied with Cams (called intrinsic rules). You can reference and combine existing rules to create new ones or create entirely new, custom rules. A permission is the binding of a rule to a specific resource pattern (e.g. a URL pattern). The default bias specifies if access to resources without matching permissions will be granted or denied.

Open the system security domain's access control policy in a text editor:

CAMS_HOME/conf/domains/system/access-control-policy.xml

At the top of the file you see the access control policy declaration, the default bias and the last modified time:

<access-control-policy defaultBias="granted" lastModifiedTime="200701011200">

The default bias grants access to all resources unless you specify permissions that grant access to requests that meet the associated rule evaluation criteria. You can conversely set the default bias to denied, which denies all resource access unless specifically granted by permissions. As you make changes to access-control-policy.xml while the Cams policy server is running, you can increment the lastModifiedTime and save the file to attempt a reload. If you make edits and save without incrementing, a running Cams policy server will display an error message and the access control policy changes will not reload. The access control policy never loads if there are XML syntax errors.

A Cams access control policy is divided into XML blocks of one or more <permission-collection> and one <acr-lib> (access control rule library). The permissions you'll work with are in the top <permission-collection> of type http. The <permission-collection> blocks for type cams is for Cams web agents and should not be altered unless instructed to do so by Cafésoft support.

When a Cams policy server receives an access check request, the system security domain always does the initial evaluation. The permission that matches a given access check request is determined by:

  1. The most specific matching resource pattern - For HTTP permissions, the most specific URL pattern is weighted in order of URI, port, host and scheme:

    schemePattern :// hostPattern : portPattern / uriPattern

    Generally, the longest URL is the most specific.

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

If no permission has a matching resource pattern and action, then the default bias determines whether access to the resource is granted or denied. Hard values can be specified as well as a wild card (*) to match in any of the four HTTP resource pattern components (scheme, host, port or URI). For example, the following are all valid permission resource patterns:

Generally, wild cards are recommended for the scheme, host and port values to maximize access control policy portability between development, staging and production systems. See the Configuring Cams Access Control Policy for more information on resource pattern matching.

A permission always has either an <acr-ref> or <owner> tag. The <acr-ref> tag references an access control rule that will be evaluated when the permission's resource is matched. The <owner> tag references a valid security domain to which the resource request will be forwarded. Example 3 shows examples (similar to those in the file you have open but uncommented) of a permission that references the intrinsic Cams granted rule (to always grant access), delegation of a resource to another security domain and a reference to a role-based access control rule defined in <acr-lib>.

NOTE: You activate and deactivate permissions and rules by commenting or uncommenting them using the XML start comment "<!--" and end comment "-->" markers.

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

 <!-- Example: Grant access to the Cams login/logout URIs and login  
      page. Should you change the defaultBias to "denied", you MUST 
      grant access to Cams login/logout resources. -->
 <permission desc="Cams default pages" actions="GET,POST">
  <resource-pattern id="*://*:*/cams/*"/>
  <acr-ref id="granted"/>
 </permission>

 <!-- Example: Delegate HTTP/HTTPS resource requests for "/myresource*" 
      to another security domain.  -->
 <permission desc="Delegate all HTTP/HTTPS requests" actions="">
  <resource-pattern id="*://*:*/myresource*"/>
  <owner id="mydomain"/>
 </permission>
 <!-- Example: Grant access to the Cams test page to authenticated 
      users with the "administrator" role.  -->
 <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 3 - Sample Cams access control policy permissions

Example 4 shows the default system security domain's access control rule library, which is enclosed by the <acr-lib> tags. You see two defined rules:

  1. The "cams administrator rule" grants access to resources that require the authenticated user to have the administrator role.
  2. The "cams agent rule" requires that authenticated Cams web agents have the cams-agent role. If you open the system security domain's cams-users.xml user directory, you'll see that the cams-web-agent user has the cams-agent role. Without it, an authenticated Cams web agent would be denied access to authentication connection with a Cams policy server. 
<!-- 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-constraint>
 </auth-acr>
 <!-- Cams web agents must have the "cams-agent" role. 
		  WARNING: Do not remove unless replaced by equivalent or Cams web
			agents will not be able to connect to the Cams policy server.-->
 <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 4 - Rules from the default system security domain

As you start to work with the Cams access control policy, remember that 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 started the Cams policy server to determine if any XML syntax errors occur. If they do, the Cams policy server will not reload the access-control-policy.xml file.

Configure a custom rule and permission

If not already open, open CAMS_HOME/conf/domains/system/access-control-policy.xml in a text editor. By default, access is granted to all HTTP/HTTPS 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 with "myrole" -->
<auth-acr id="require myrole">
 	<role-constraint>
 	  <role-name>myrole</role-name>
 	</role-constraint>
</auth-acr>

Now, add a permission to protect the secure directory by inserting it in the type http <permission-collection> block. For example, to only allow users with myrole to access the content of secure (and its subdirectories), add the following permission:

<!-- Requires authenticated users with "myrole" -->
<permission desc="Requires user to have myrole for access">
 	<resource-pattern id="*://*:*/secure/*"/>
 	<acr-ref id="require myrole"/>
</permission>

Update the lastModifiedDate and save the file. Your Cams security policy will now require that users authenticate and have the role myrole to access the contents in secure and look like this. Next, you need a user with myrole role in the cams-user.xml file in the system security domain (or in the user directory you configured in Step 1). Using a text editor, open:

CAMS_HOME/conf/domains/mydomain/cams-user.xml

and add myrole to the guest user:

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

Save the file. The Jetty web server includes a secure directory for your convenience. You can try testing by browsing to http://localhost:8080/secure/ and entering when prompted:

User name: guest
Password: password

WARNING: When working with access control policies, caching by both your browser and the Cams web agent can adversely effect the expected results. It is best to disable browser page caching and to disable Cams web agent access control check caching (set cams.access.check.cache=false in cams-webagent.conf and restart your web server).

You should create a security policy document before starting work on a Cams access control policy. This is typically a short document that includes definition of the resources in your environment and what access rights are required to access them. You can then use the Cams access control policy to define the permissions and rules that will enforce your security policy. As you implement the security policy, the Access Control Policy Tag Reference is extremely helpful to learn more about Cams permissions and rules you can use and to clone examples.

Step 3 - 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 system as the Cams policy server can connect using this address. Because you'll probably use one or more Cams web agents installed on different network systems, you'll need to set the Cams policy server bind address to an IP address that is network accessible.

The Cams policy server bind address 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 not an IP address assigned to the local system, then a fatal configuration error will be reported and the Cams policy server will fail to 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="${P} -Dcams.server.bindaddr=192.168.1.101"

NOTE: Though you may use a DNS host name for the bind address, it is recommended that you use an IP address for best performance.

WARNING: The Cams web agent in your test Jetty web server will no longer connect after you change the Cams policy server bind address. If you make this change and desire to use the test Jetty web server, see Step 4 for instructions on how to change the Cams web agent server URL value found in CAMS_HOME/jetty/etc/cams-webagent.conf.

Step 4 - Configure a Cams web agent

Download the Cams web agent(s) and documentation you will need and follow the installation instructions in the Cams web agent guide. Cams web agent guides are also available online in the Cafésoft Documentation Center.

Many configuration values are similar across all Cams web agents and found in each web agent's configuration file: cams-webagent.conf. Most default values work as is and only need to be changed to enable specific features or as part of a hardening exercise. However, the following cams-webagent.conf value must be changed if you changed the bind address in step 3:

cams.server.url.MyCamsServer - set to the IP address 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). For example:

cams.server.url.MyCamsServer=cams://192.168.1.101:9191

You should review the Cams web agent guide Configuration Properties appendix to see a full list of all properties and features. Each Cams web agent also includes a sample login page and Cams web agent test page written in the scripting language most appropriate for the target web server. After you install a Cams web agent, use the Cams web agent test page to test correct installation. Also, see the Scripts appendix in each Cams web agent guide for documentation on the structure and use of the login page.

WARNING: Your Cams access control policy must grant unconditional access to the Cams login/logout URIs and login page for correct operation. You must also ensure that the Cams login URL, which is configured in login-config.xml, references a page that is available on your web server (see Cams Login URL in Step 1).

NOTE: You can start and stop the Cams policy server and web agents in any order and connections will be established and cleaned up automatically. However, there is a benefit to using the following order:

  1. Start the Cams policy server first and then the web servers with Cams web agents. That prevents connection errors in Cams web agent logs that result from a Cams web agent trying to connect before the Cams policy server is started (and will prevent users from possibly experiencing Cams web agent connection during startup).
  2. Gracefully stop the web servers with Cams web agents first and then the Cams policy server. The Cams web agents will close their connections, which will reduce the time is takes the Cams policy server to gracefully shutdown to between 5 to 10 seconds. Otherwise, the Cams policy server will serially wait up to 5 seconds for each Cams web agent connection to close. This can take a long time when using more than one multi-process web server like Apache, which can have hundreds of connections to the Cams policy server.

Step 5 - Next steps

You now understand the various integration components that need to be configured for Cams to secure your web resources. To continue to learn more about and customize Cams to meet your integration requirements, see:

Back | Next | Contents

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