Access Control Rules API Reference
The following classes make up the Access Control Rule API:
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.
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
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.
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.
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
A factory class (registered within
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
is available as an example in the WAM
Example 1 shows how you might declare the AccessControlRuleType for an
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
file declaring a custom AccessControlRule type and instance
Table 1 summarizes these example XML elements and attributes.
|Element or Attribute||Description|
||Declares a new AccessControlRuleType, which is unique type name and className.|
||Declares the AccessControlRulePersistenceManager for the AccessControlRuleType.|
||An optional list of initialization parameters that can be used to configure the AccessControlRulePersistenceManager instance.|
||Declares an instance of the
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):
or you can install it in a security domain-specific configuration subdirectory:
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).
This case-sensitive attribute declares the unique identifier used to
reference this access control rule from
NOTE: It is also possible to instance an AccessControlRule
without giving it an
||This optional attribute gives more information on the nature of the access control rule during debugging, error logging, etc.|
This element is also within the
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
||This element defines the end of the
Table 1 - Summary of the
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.