See wam Menu

Access Control Rules API Reference

The following classes make up the Access Control Rule API:

  • interface: com.cafesoft.cams.access.AccessControlRule

  • abstract class: com.cafesoft.cams.access.Abstract AccessControlRule

  • interface: com.cafesoft.cams.Internal AccessControlRequest

  • interface: com.cafesoft.cams.Internal AccessControlResponse

  • class: com.cafesoft.cams.AccessControlException

  • interface: com.cafesoft.cams.access.AccessControlRulePersistenceManager

  • exception: com.cafesoft.cams.PersistenceException

Before getting into more detail on these classes, you’ll need a little more context on the environment within which access control rules are executed and managed.

Access control rules are defined within the scope of a WAM security domain’s access control policy, which defines the resources being protected and the rules that control access to them. Within each access control policy, an access control rule library manages access control rule types and instances.

Figure 1 shows the relationships between some internal WAM classes and Access Control Rule API classes. The interfaces shown in green are the ones you’ll implement to plug a new access control rule into WAM.

Figure 1 - Relationships between WAM Access Control Rule API classes

Summarizing these relationships: a SecurityDomain has an AccessControlService, which loads an AccessControlPolicy (by default from an XML file). Within the AccessControlPolicy, an AccessControlRuleLibrary stores information about AccessControlRuleTypes and AccessControlRule instances. An AccessControlRule is an instance of an AccessControlRuleType, which has an AccessControlRulePersistenceManager, which is responsible for creating, loading, storing, and removing AccessControlRules from persistent storage.

Access Control Rule API Classes Overview

This section summarizes the roles of Access Control Rule API classes.

com.cafesoft.cams.access.AccessControlRule and com.cafesoft.cams.access.AbstractAccessControlRule

AccessControlRule is the basic interface that must be implemented by all AccessControlRules. Methods include:

  • A way to set/get an AccessControlRule’s identifier (which must be unique within a security domain’s AccessControlPolicy).
  • A way to set/get a textual description.
  • A method to evaluate the rule using InternalAccessControlRequest/InternalAccessControlResponse parameters.

For convenience, you can extend AbstractAccessControlRule to implement your own AccessControlRules. AbstractAccessControlRule implements the generic AccessControlRule accessors and mutators, leaving the evaluate method (and any other custom methods) for your implementation.

com.cafesoft.cams.access.InternalAccessControlRequest and com.cafesoft.cams.access.InternalAccessControlResponse

InternalAccessControlRequest and InternalAccessControlResponse are the interfaces to parameters passed to AccessControlRules during evaluation.

The InternalAccessControlRequest provides access to information about the resource being accessed including: the resource type, resource identifier, requested action, remote host information, authenticated user session, and more.

The InternalAccessControlResponse interface provides AccessControlRules with the means to customize certain responses to the WAM security engine.

com.cafesoft.cams.access.EvaluationException

If an AccessControlRule experiences a serious error condition during evaluation, it should throw an EvaluationException. This Exception may indicate that a major precondition to evaluating the AccessControlRule is not met or that some other critical runtime state is not correct.

com.cafesoft.cams.access.AccessControlRulePersistenceManager and com.cafesoft.cams.PersistenceException

AccessControlRulePersistenceManager is an interface for Objects that are responsible for:

  • Creating new instances of an AccessControlRule type, usually for insertion into an AccessControlPolicy.
  • Loading from persistent storage, such as an XML file or relational database.
  • Saving to persistent storage.
  • Removing from persistent storage.

PersistenceException is used to communicate errors that might be encountered during use of an AccessControlRulePersistenceManager.

Access Control Rules Persistence

By default, WAM uses an XML-formatted file to persist an access control policy and the access control rules within it. However, WAM design also enables persistence to relational databases, LDAP servers, and more. Although access control rule implementations are independent of storage type, AccessControlRulePersistenceManager implementations are not.

For XML storage, AccessControlRules are defined within a security domain-specific XML file named access-control-policy.xml. A factory class (registered within security-domain.xml) parses access-control-policy.xml and creates an XML DOM (Document Object Model) tree. When an access control rule is encountered, its corresponding AccessControlRulePersistenceManager acrLoad method is invoked to populate an AccessControlRule instance. As a parameter, the acrLoad method is given the XML DOM element node corresponding to the AccessControlRule.

As we’ll show, WAM provides various utilities for processing the XML DOM sub-tree while loading or storing your custom AccessControlRule. The AccessControlRule type is registered by use of the <acr-type ...> Element hierarchy.

The examples that follow show 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.

Example 1 shows how you might declare the AccessControlRuleType for an examples:business-hours-acr within a security domain’s access-control-policy.xml file and how to create an instance called business hours rule that can be referenced from other parts of the access control policy.

<access-control-policy>
  ...
  <acr-lib>
    ...
   <!--
      Declare the AccessControlRuleType for our example "business-hours-acr".
      (Registers this type of AccessControlRule with WAM).
    -->
    <acr-type
        name="example:business-hours-acr"
        className="examples.acrs.BusinessHoursAcr"
        desc="Control access by business hours">
      <acr-persistence-manager className="examples.acrs.XmlBusinessHoursAcrPm">
        <param-list>
          <param name="debug" value="false"/>
        </param-list>
      </acr-persistence-manager>
    </acr-type>

    <!--
      Define an AccessControlRule that controls access by
      "normal business hours": Monday-Friday 8:00 AM to 5:00 PM.
    -->
    <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">
      <example:business-hours start-hour="8" end-hour="17"/>
    </example:business-hours-acr>

    ...
  </acr-lib>
</access-control-policy>

Example 1 - An example WAM access-control-policy.xml file declaring a custom AccessControlRule type and instance

Table 1 summarizes these example XML elements and attributes.

Element or Attribute Description
<acr-type> Declares a new AccessControlRuleType, which is unique type name and className.
<acr-persistence-manager> Declares the AccessControlRulePersistenceManager for the AccessControlRuleType.
<param-list> An optional list of initialization parameters that can be used to configure the AccessControlRulePersistenceManager instance.
<example:business-hours-acr ...> Declares an instance of the business-hours-acr AccessControlRule. It uses an XML namespace of example to distinguish it from intrinsic WAM access control rules or those obtained from other organizations.
xmlns:example="http://cafesoft.com/ example-business-hours-acr_1_0.dtd"

Declares the acme XML namespace and specifies the file containing the Document Type Definition (DTD) for this element. Although the format for the DTD file reference is an HTTP URL, it’s a unique identifier that can be resolved to a local file. WAM is setup to resolve the location of these DTD files, so for this example you’ll need to create/install the DTD file at either the WAM system-wide DTD directory (which will make it available to all security domains):

${cams.home}/conf/dtd/acme-business-hours- acr_1_0.dtd

or you can install it in a security domain-specific configuration subdirectory:

${cams.security-domain.home}/dtd/ example-business-hours-acr_1_0.dtd

The contents of this file declares the valid elements and attributes for this access control rule (you’ll find more information on the contents of this file below).

id="business hours rule"

This case-sensitive attribute declares the unique identifier used to reference this access control rule from <permission ...> elements.

NOTE: It is also possible to instance an AccessControlRule without giving it an id within an <acr ...> element. This is useful if you want to limit the scope of the AccessControlRule instance.

desc="Limit access to M-F business hours" This optional attribute gives more information on the nature of the access control rule during debugging, error logging, etc.
<example:business-hours start-hour="8" end-hour="17"/>

This element is also within the example namespace and has two attributes: start-hour and end-hour, which define normal business hours for this rule instance. You might also define separate elements like this:

<example:start-hour>8</example:start-hour>
<example:end-hour>17</example:end-hour>

enabling you to get the hour values as XML element data, but in this case using element attributes is more convenient.

NOTE: The slash at the end of the element declaration (/>) marks this element as EMPTY, which means that it cannot contain other elements.

</acme:business-hours> This element defines the end of the example:business-hours access control rule. Once this element is processed, the example XML namespace is no longer in effect, although it can be used again in subsequent elements, even for different element types, simply by using the xmlns:example="DTD URI attribute declaration.

Table 1 - Summary of the example:business-hours-acr XML elements

Access Control Rule Multithreading Considerations

AccessControlRule instances must be thread-safe because the WAM access control system handles many access requests simultaneously. So, you’ll want to be sure that you avoid the use of thread-specific instance variables within your custom AccessControlRules or that you make use of java.lang.ThreadLocal if you must associate state with specific threads.

The discussion of thread safety is beyond the scope of this documentation, but a number of references are provided in Related Resources, if you need more guidance.


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.