See wam Menu

Creating New Access Control Rules

This section describes the steps involved in creating and registering a new AccessControlRule with WAM. The example shows how you might write a custom AccessControlRule that can control access by day and time. Specifically, the AccessControlRule class is called BusinessHoursAcr and is available as an example in the WAM examples.acrs package.

Step 1 - Create an AccessControlRule class

The easiest way to create a new AccessControlRule is to extend the com.cafesoft.cams.access.AbstractAccessControlRule class, which provides default implementations for initializing an AccessControlRule and getting/setting common fields.

Here’s an example: BusinessHoursAcr.java

Although the above example does not show it, AccessControlRules have an initialize method that is passed a Config parameter which provides access to the following:

  • Initialization parameters.

  • A ServiceFinder, which enables you to access WAM manageable, reusable, scalable services (see Programming WAM Services).

  • A Logger, which enables you to debug your AccessControlRules and to report initialization errors, etc.

Step 2 - Create an AccessControlRulePersistenceManager class

An AccessControlRulePersistenceManager has methods for:

  • Creating new instances of your AccessControlRule (usually for insertion into an AccessControlPolicy).

  • Loading from persistent storage (like XML or a relational database).

  • Saving to peristent storage.

  • Removing from persistent storage.

Here’s an example AccessControlRulePersistenceManager for the BusinessHoursAcr: XmlBusinessHoursAcrPm.java

Step 3 - Register the AccessControlRule XML Element tree with WAM

In this step, the new AccessControlRule XML elements are registered by creation of a new DTD file, modification of an existing DTD, and installation of classes.

Step 3a - Create/install an XML DTD

In this step, you’ll need to create an XML DTD file that describes the XML elements and attributes used to represent your custom AccessControlRule within an access-control-policy.xml file. If you havn’t developed XML DTDs before, or don’t have a background in formal language notations, this may look a little intimidating at first, but some provided examples and references should help you.

First, you’ll need to decide where you’ll install your custom DTD file: in the system-wide DTD directory or in a security domain-specific DTD directory.

  • If you’d like your custom access control rule to be available to all security domains, put it in directory ${cams.home}/conf/dtd 

  • If you want to limit your custom access control rule to a specific security domain, put the DTD file in directory ${cams.security-domain.home}/dtd 

  • If you are not sure where the home directory for a security domain is located, you’ll find a reference in ${cams.home}/conf/domains/security-domain-registry.xml

Next, you’ll need to create a file of the appropriate name. If the first XML element of your custom access control rule looks like this:

<example:business-hours-acr
  xmlns:example="http://cafesoft.com/example-business-hours-acr_1_0.dtd"
  id="business hours rule"
  desc="Limit access to M-F business hours">

then you’ll need to create a DTD file named example-business-hours-acr_1_0.dtd

For those of you knowledgeable about XML, WAM includes a customized EntityResolver that looks in the WAM installation directories for DTD files and returns them to the XML Parser for processing.

Don’t let the fully-qualified XML namespace http://cafesoft.com/example-business-hours-acr_1_0.dtd fool you. The XML parser will not attempt to load the DTD file over the network from cafesoft.com. This value is simply a unique identifier for the XML namepace used for your XML elements. For your custom access control rules, you may want to use your own company name to distinguish them from third-party DTDs.

For example, if your company domain name is realsecure.com, you might use: http://realsecure.com/mynamespace-my-custom-acr_1_0.dtd. The WAM EntityResolver will look for a file matching the string following the last / character. Whatever you place before that is purely arbitrary, but it’s a good idea to use your own domain name.

A standard convention for the filename itself is to use the short namespace name (in this case, example), followed by the access control rule element name, followed by a version number. The version number enables you to distinguish updated XML schemas for new/improved versions of your access control rules and possibly continue supporting older versions of those access control rules.

Here’s the example DTD file corresponding to the example:business-hours-acr element: example-business-hours-acr_1_0.dtd

Step 3b - Register the new XML elements

Once you’ve created a DTD that defines your custom AccessControlRule XML schema, you’ll need to modify (or copy and modify) the DTD file for the access-control-policy.xml file itself.

  • If your AccessControlRule is to be made available to all security domains hosted under WAM, edit file: ${cams.home}/conf/dtd/access-control-policy_1_0.dtd .

  • If your AccessControlRule is to be deployed only a specific security domain, edit file ${cams.security-domain.home}/dtd/access-control-policy_1_0.dtd

If the security domain-specific file does not exist, then copy the system-wide file to the security domain-specific directory and edit that copy.

Here’s an example that shows changes that were made to support the <example:business-hours-acr...> element: access-control-policy_1_1.dtd

Step 3c - Install the compiled classes

The following commands show how you can compile your WAM access control rule classes and deploy them to a directory where the WAM Policy Server will automatically find and load them.

The examples assume that environment variable CAMS_HOME is defined and points to the "policyServer" directory within the WAM distribution.

  • Unix: javac -classpath .;$CAMS_HOME/lib/cams.jar:$CAMS_HOME/lib/cscore.jar -d $CAMS_HOME/classes *.java

  • Windows: javac -classpath .;%CAMS_HOME%\lib\cams.jar;%CAMS_HOME%\lib\cscore.jar -d %CAMS_HOME%\classes *.java

You’ll need to shutdown and restart the WAM Policy Server for changes to take effect. For production use, you may want to jar your components, drop them in directory $CAMS_HOME/lib, and modify script runcams.sh or runcams.bat to add the jar file to the WAM Policy Server’s classpath.

Step 4 - Declare your AccessControlRule type

This step registers the custom AccessControlRule and AccessControlRulePersistenceManager classes within enclosing the AccessControlRuleLibrary in file access-control-policy.xml.

Here’s an example that shows how to use the <acr-type ...> element and its children to declare the example:business-hours-acr AccessControlRule type: access-control-policy.xml

Step 5 - Create an instance of your AccessControlRule

Instance your custom AccessControlRule within the AccessControlRuleLibrary and reference the newly created rule from a permission for testing within the access-control-policy.xml file.

Here’s an example: access-control-policy.xml

Step 6 - Test your new AccessControlRule

To test loading and execution of a custom AccessControlRule, start the WAM policy server and look in the trace log for the security domain that you’ve modified.

It may be helpful to enable DEBUG level messages (see configuring the trace logger in the WAM Administrator’s Guide - Security Domain Configuration) during development.

At this time, no support is provided for testing AccessControlRulePeristenceManager storage and removal. Comprehensive unit testing with an API like JUnit is highly recommended.


Have a Question?

Have a how-to question? Seeing a weird error? Contact us.

Found a bug? Submit a support ticket.

Have a product idea or request? Share it with us in our Ideas Portal.