Back | Next | Contents Cams Administrator's Guide

Access Control Policy Tag Reference

A security domain's access control policy declares the resources protected within a security domain and the access control rules that protect them. Specifically, each access control policy contains permission collections and an access control rule library, which are containers for permissions and access control rules. This document contains reference information for each of the tags that can be used within a Cams access-control-policy.xml file. The following table shows the file structure with links to each of the possible elements.

Tag Name Instances Description

access-control-policy

1

declares an access control policy

[permission-collection]

0 ... N

a collection of permissions

[permission]
0 ... N

a specific permission that associates a set of resources and access control rule or owner

resource-pattern
1

a pattern for matching resources

acr-ref | owner
1

a reference to an access control rule or a security domain to which access control is delegated

acr-lib
1

a library of access control rules

[acr-type]
0 ... N

a custom type of access control rule registered with the access control rule library

acr-persistence-manager
1

defines the class responsible for creating, loading, storing, and removing access control rule instances for a given type

param-list
0 ... 1

a list of initialization/configuration parameters

param
0 ... N

a generic name/value pair

[acr]
0 ... N

an access control rule expression

[granted]
0 ... N

a Cams instrinsic access control rule that always grants access

[denied]
0 ... N

a Cams instrinsic access control rule that always denies access

[confidential]
0 ... N

a Cams instrinsic access control rule that requires that a resource be accessed via an encrypted connection (usually means SSL/TLS)

[and | or | not]
0 ... N

boolean operators for use between access control rule invocations

[acr-ref]
0 ... N

a reference to another access control rule to be invoked

[auth-acr]
0 ... N

an authentication access control rule embedded in this rule

[host-acr]
0 ... N

a remote host access control rule embedded in this rule

[custom-acr]
0 ... N

a custom access control rule of a type declared by acr-type and embedded in this rule

[auth-acr]
0 ... N

an authentication access control rule that implements role-based access control

[role-constraint]
0 ... N

grants or denies access based on a role name and optionally a class

role-name
1

a role name

role-class
0 ... 1

a role class

[host-acr]
0 ... N

a remote host access control rule

allow-host
0 ... 1

a list of remote hosts to allow access

[host]
0 ... N

a remote host name pattern

deny-host
0 ... 1

a list of remote hosts to deny access

[host]
0 ... N

a remote host name pattern

allow-address
0 ... 1

a list of remote addresses to allow access

[address]
0 ... N

a remote host IP address pattern

deny-address
0 ... 1

a list of remote addresses to deny access

[address]
0 ... N

a remote host IP address pattern

[custom-acr]
0 ... N

a custom access control rule of a type declared by acr-type (see also acr-persistence-manager).

<access-control-policy>

The <access-control-policy> element is the top-level element for a security domain's access control policy.

Item Description
Syntax 
<access-control-policy 
  lastModified="2003110400" 
  defaulBias="granted | denied"
  debug="true|false">
  <permission-collection>
    ...
  </permission-collection>
  ...
  <acr-lib>
    ...
  </acr-lib>
</access-control-policy>
Attributes
lastModified Req

Specify the date/time at which the access control policy was last modified. The value of this attribute must be a number. Recommended format is: YYYYMMHHMM

NOTE: It is very important to increase this value whenever access-control-policy.xml is modified because it will cause Cams agents to clear cached access control responses.
defaultBias Opt Specify the security domain default bias to either grant or deny access to resources (granted or denied). If not specified, the default bias is denied.
debug Opt Activate debug for the access control policy (true or false).
Data None
Parent Elements

None
Child Elements
<permission-collection> Opt A type-specific collection of permissions. Any number of permission-collections may exist within an access-control-policy, but each must have a unique type (currently http or cams). The permission-collection/permission types are dicated by the unique types of agents enforcing the access control policy in your Cams deployment.
<acr-lib> Req A container for all security domain-specific access control rule types and references. Only one library is permitted.
Example 
<access-control-policy lastModified="2003110400">
 
  <!-- HTTP (Web) Resource Permissions -->
  <permission-collection type="http" desc="HTTP (Web) Resources">
    <permission desc="ACME Local Area Network Resources"> 
      <resource-pattern id="http://www.acme.com/employee*"/>
      <acr-ref id="ACME LAN Rule"/>
    </permission>
  </permission-collection>

	<!-- Allow http agents to connect -->
  <permission-collection type="cams" desc="Agent Permissions">
    <permission desc="Cams Agent Connections" actions="ACCESS">
      <resource-pattern id="${cams.resource.base.id}/"/>
      <acr-ref id="cams agent rule"/>
    </permission>
  </permission-collection>

  <!-- Access Control Rule Library -->
  <acr-lib> 
    <host-acr id="ACME LAN Rule"> 
      <accept-address-constraint>
        <address>192.168.0.*</address>
      </accept-address-constraint>
    </host-acr>
  </acr-lib>

</access-control-policy>

<permission-collection>

A security domain's access control policy contains one permission collection for each unique type of permission. For example, all http permissions are stored in a single http-specific permission collection. Permission collections organize Cams access control policies and optimize access control performance.

There can be any number of permission-collections within an access-control-policy, once for each unique type of permission.

Item Description
Syntax 
<permission-collection 
  type="type code" 
  desc="text description"
  debug="true | false">
  <permission ... >
    ...
  </permission>
  ...
</permission-collection>
Attributes
type Req A code indicating the type of permission contained within the permission collection. Currently http or cams.
desc Opt A description used for readability and for context-sensitive messages. Use unique, descriptive names to facilitate message comprehension and debugging.
debug Opt Activate debug for the permission collection (true or false).
Data None
Parent Elements

1. <access-control-policy>
Child Elements
<permission> Opt A type-specific resource and rules for controlling access.
Example 
<permission-collection type="http" desc="HTTP (Web) Resources">

  <!-- Declare web pages available to all ACME employees -->
  <permission desc="ACME Employee Web Resources"> 
    <resource-pattern id="http://www.acme.com/employee*"/>
    <acr-ref id="ACME Employee Rule"/>
  </permission>
			
  <!-- Declare web pages available only to ACME management -->
  <permission desc="ACME Management Web Resources"> 
    <resource-pattern id="http://www.acme.com/management*"/>
    <acr-ref id="ACME Management Resources Rule"/>
  </permission>
		
</permission-collection>

<permission>

A permission identifies a set of resources via a resource pattern and either an access control rule to protect those resources or an owner security domain to which access control is to be delegated. The rules for defining resource patterns vary with the type of permission.

Any number of permissions may be added to a permission-collection provided the resource pattern and action(s) are valid for the enclosing permission collection and the permissions don't overlap. Two permissions overlap if their fully-qualified resource patterns are identical and they have at least one action in common. Cams will not allow addition of an overlapping permission and an access control policy referencing an overlapping permission will fail to load.

Item Description
Syntax 
<permission 
  desc="text description"
  actions"GET,POST,PUT,DELETE,HEAD,OPTIONS,TRACE"
  debug="true | false">
  <resource-pattern ... />
  <acr-ref ... /> | <owner ... />
  ...
</permission>
Attributes
desc Opt A description used for readability and for context-sensitive messages about the permission.
actions Opt

A pattern for matching actions on incoming access control requests. The list of possible actions is dependent on the type of resource being protected. Here are some example action patterns for different types of permissions:

  • type="http" -> GET, POST, PUT, DELETE, HEAD, OPTIONS, TRACE
  • type="cams" -> ACCESS, START, STOP

An access control request will match the actions part of a resource pattern if all of the actions it requests are present in the resource pattern's actions list. If a resource-pattern does not specify a list of actions, the convention is to match any/all actions.
debug Opt Activate debug for the permission (true or false).
Data None
Parent Elements

1. <permission-collection>
Child Elements
<resource-pattern>
Req
 A type-specific pattern for resource identifiers that match this permission.
<acr-ref>
Opt
 A reference to an access control rule that protects the resources. Although optional, either <acr-ref> or <owner> must be referenced within a permission.
<owner>
Opt
 The name of a security domain to which access control is to be delegated. Although optional, either <acr-ref> or <owner> must be referenced within a permission.
Example 
<!-- Declare web pages available to the public -->
<permission desc="ACME Public Web Resources" actions="GET"> 
   <resource-pattern id="http://www.acme.com/*"/>
   <acr-ref id="granted"/>
</permission>

<!-- Delegate human resources content to the "Human Resources" 
     security domain -->
<permission desc="ACME Public Web Resources"> 
   <resource-pattern id="http://www.acme.com/human-resources*"/>
   <owner id="Human Resources"/>
</permission>

<resource-pattern>

A resource-pattern identifies the resources associated with a permission. When a permission receives an access control request, it will compare the requested resource's identifier and action against it's identifer pattern and actions pattern. If the pattern matches and it is the most specific pattern for the request, then the permission matches and the access control policy will use it to enforce access control.

Item Description
Syntax 
<resource-pattern id="type-specific resource id pattern"/>
Attributes
id Req

A pattern for matching resources identifiers. The actual syntax of this pattern depends on the type of resource being protected. Here are some example resource id patterns for different types of permissions:

  • type="http" -> http://www.acme.com/*
  • type="cams" -> cams://www.acme.com:9191

Support for pattern wild card matching and range matching can vary by permission type.
Data None
Parent Elements

1. <permission>
Child Elements None
Example 
<!-- Declare the public web pages -->
<permission desc="ACME Public Web Resources" actions="GET,POST"> 
  <resource-pattern id="http://www.acme.com/*"/>
  <acr-ref id="granted"/>
</permission>

<acr-ref>

A reference to an existing access control rule within the enclosing security domain's access control rule library. Access control rules can be referenced from:

  1. permissions to assign the access control rule that protects matching resources
  2. other access control rule expressions to be create (combined) custom access control rules
Item Description
Syntax 
<acr-ref id="identifier of existing access control rule"/>
Attributes
id Req

The identifier of an access control rule within the access control rule library. Cams intrinsic access control rules, which are always available for use from permissions and other rules, are:

  • granted
  • denied
  • confidential

Cams also ships with standard access control rule types, such as auth-acr and host-acr, that can be referenced within the access control rule library, then by this attribute.
Data None
Parent Elements

1. <permission>
2. <acr>

Child Elements None
Example 
<!-- Declare web pages available to the public -->
<permission desc="ACME Public Web Resources" actions="GET"> 
  <resource-pattern id="http://www.acme.com/*"/>
  <acr-ref id="granted"/>
</permission>

...

<!-- Rule for accessing LAN requires either the
     user authenticate or the workstation be on 
     the LAN -->
<acr id="Local Channel Access Rule"> 
  <acr-ref id="LAN User Auth Rule"/>
  <or/>
  <acr-ref id="LAN User Address Rule"/>
</acr>

<owner>

A reference to an existing security domain to which access control for a permission is delegated.

Item Description
Syntax 
<owner id="security domain identifier"/>
Attributes
id Req

the name of an existing security domain.
Data None
Parent Elements

1. <permission>

Child Elements None
Example 
<!-- Delegate ACME web server access control to 
     the ACME security domain -->
<permission desc="ACME Web Server"> 
   <resource-pattern id="http://www.acme.com/*"/>
   <owner id="ACME"/>
</permission>

<acr-lib>

An access control rule library, which can only be referenced once within an access control policy. It serves as a container for all access control rule references and types available within a security domain.

Item Description
Syntax 
<acr-lib debug="true|false">
  ...
</acr-lib>
Attributes
debug Opt Activate debug for the library. The default is false.
Data None
Parent Elements

1. <access-control-policy>
Child Elements
<acr-type> Opt A declaration for a custom access control rule type. This tag registers new access control rule types created using the Cams Access Control Rule API. See the Cams Programmer's Guide for more details.
<acr> Opt An access control rule reference.
<auth-acr> Opt An authentication rule.
<host-acr> Opt A remote host access control rule.
[custom-acr] Opt If one or more custom access control rule types are declared, create and use a custom acr tag within the access control rule library. (The actual tag name for custom access control rules is specified as part of the acr-type).
Example 
<acr-lib>

<!-- Require an authenticated user to have "employee" role -->
  <auth-acr id="ACME Employee Rule">
     <role-constraint>
       <role-name>employee</role-name>
     </role-constraint>
  </auth-acr>

<!-- Require hosts to be on the ACME Local Area Network -->
  <host-acr id="ACME LAN Rule">
    <accept-address-constraint>
      <address>192.168.0.*</address>
    </accept-address-constraint>
  </host-acr>

<!-- Require an authenticated user to have the "manager" role
     that is implemented by a particular role class  -->
  <auth-acr id="ACME Manager Rule">
    <role-constraint>
      <role-name>manager</role-name>
      <role-class>com.cafesoft.cams.auth.CSRolePrincipal</role-class>
    </role-constraint>
  </auth-acr>

<!--  Require:
         1. the host to be on the ACME Local Area Network
         2. the user to be authenticated with "manager" role
         3. a confidential (SSL) connection for privacy  -->
  <acr id="ACME Manager Resources Rule">
    <acr-ref id="ACME LAN Rule"/>
    <and/>
    <acr-ref id="ACME Management Rule"/>
    <and/>
    <confidential/>
  </acr>

<!-- Declare a custom Access Control Rule type for limiting
     access by company business hours -->
   <acr-type			
      name="example:business-hours-acr"			
      className="examples.acrs.BusinessHoursAcr"
      desc="Control access by normal business hours"
   >
   <acr-persistence-manager className="examples.acrs.XmlBusinessHoursAcrPm">
      <param-list>
        <param name"clockHours" value="0-23"/>
        <param name="useLocalTimeZone" value="true"/>
      </param-list>
    </acr-persistence-manager>
  </acr-type>

<!-- Create an Access Control Rule for limiting access
     by company business hours  -->
  <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>

<acr-type>

An access control rule type declares a custom type of access control rule within an access control rule library. Once defined, access control rules can be used within the access control rule library directly or nested within an access control rule expression.

Item Description
Syntax 
<acr-type>
  ...
</acr-type>
Attributes
name Req The name associated with the access control rule type. In the case of XML, the name corresponds to the element tag name that denotes the beginning of a new reference of the access control rule type.
className Req The fully-qualified Java class name implementing the access control rule.
desc Opt A textual description of the access control rule type.
Data None
Parent Elements

1. <acr-lib>
Child Elements
<acr-persistence-manager> Req Configures the Java class that is responsible for storing, loading, and creating new access control rules.
Example 
<!-- Declare a custom Access Control Rule type for limiting
<acr-type			
   name="example:business-hours-acr"			
   className="examples.acrs.BusinessHoursAcr"
   desc="Control access by normal business hours"
>
   <acr-persistence-manager className="examples.acrs.XmlBusinessHoursAcrPm">
      <param-list>
         <param name"clockHours" value="0-23"/>
         <param name="useLocalTimeZone" value="true"/>
      </param-list>
   </acr-persistence-manager>
</acr-type>

<!-- Create an Access Control Rule for limiting access
     by company business hours -->
<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-persistence-manager>

An access control rule persistence manager is responsible for persisting (storing), loading, and creating new access control rules.

Item Description
Syntax 
<acr-persistence-manager debug="true|false">
  ...
</acr-persistence-manager>
Attributes
className Req The fully-qualified Java class name implementing the access control rule persistence manager.
Data None
Parent Elements

1. <acr-type>
Child Elements
<param-list> Opt An optional list of parameters that can be used to set the default configuration.
Example 
<!-- Declare a custom Access Control Rule type for limiting
     access by company business hours -->
<acr-type			
   name="example:business-hours-acr"			
   className="examples.acrs.BusinessHoursAcr"
   desc="Control access by normal business hours"
>
   <acr-persistence-manager className="examples.acrs.XmlBusinessHoursAcrPm">
      <param-list>
         <param name"clockHours" value="0-23"/>
         <param name="useLocalTimeZone" value="true"/>
      </param-list>
   </acr-persistence-manager>
</acr-type>

<!-- Create an Access Control Rule for limiting access
     by company business hours -->
<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>

<param-list>

A list of parameters that can be used to set the default configuration.

Item Description
Syntax 
<param-list>
  <param ... />
  ...
</param-list>
Attributes None
Data

None
Parent Elements

1. <acr-persistence-manager>
Child Elements
<param> Opt An initialization/configuration parameter as a generic name/value pair.
Example 
<param-list>
  <param name"clockHours" value="0-23"/>
  <param name="useLocalTimeZone" value="true"/>
</param-list>

<param>

A parameter used to set the default configuration.

Item Description
Syntax 
<param name="textual name" value="value"/>
Attributes
name Req The textual param name.
value Req The param value.
Data

None
Parent Elements

1. <param-list>
Child Elements None
Example 
<param-list>
  <param name"clockHours" value="0-23"/>
  <param name="useLocalTimeZone" value="true"/>
</param-list>

<auth-acr>

An authentication access control rule (auth-acr) forces user authentication and controls access by the user's roles. It is composed of one or more role constraints, each of which identifies the name of a role that is assigned at authentication time. Each role constraint may also specify a role-class, which is the Java class implementing the role.

The auth-acr grants access if:

  1. the user is authenticated
  2. and at least one role-constraint that grants access matches a role associated with the authenticated user
  3. and no role-constraints that deny access match the authenticated user

A single auth-acr enables you to grant and deny access to any number of authenticated users by role name and/or role class. When a user is authenticated the Cams authentication configured for the protected resource assigns one or more roles to the user. Let's clarify via the following two scenarios:

Scenario 1: A user authenticates as johndoe

In this scenario, a user logs in with a user name/password. The following identities (roles) are assigned by the Cams authentication system:

  1. user: johndoe
  2. role: employee
  3. role: engineering

Don't let the user designation fool you, johndoe is also a role. He has logged in using his personal identity. Now consider Scenario 2:

Scenario 2: A user authenticates as administrator

In this scenario, a shared user name administrator is used by multiple individuals. After logging in a user has the following identity:

1. user: administrator

The authenticated user has the administrator role, but there's no telling who the real user might be. So, when formulating an auth-acr, a role-name corresponds to either a user or a role. In other words, a user name is also a role name, but a role name is not necessarily a user name.

Item Description
Syntax 
<auth-acr 
  id="authentication rule identifier"
  debug="true | false">
  <role-constraint>
    ...
  </role-constraint>
  ...
</auth-acr>
Attributes
id Opt The auth-acr id is used to improve access control policy readability and for context-sensitive error and debugging messages. Use unique, descriptive ids to improve message comprehension and debugging.
debug Opt Activate debug for the authentication constraint. The default is false.
Data None
Parent Elements

1. <acr-lib>
Child Elements
<role-constraint> Opt A condition placed on a role that the user must have (or not have). Any number of role-constraints may be added to an auth-acr.
Example 
<!-- The following auth-acr is true only if:
   1) the user is authenticated
   2) and the user has the "administrator" role
   3) and the user has the "employee" role
   4) and the user does not have the "contractor" role, 
      implemented by a specific Java class 

   An auth-acr will evaluate to "true" ONLY if: 
   1) at least one role-constraint matches 
      accessGranted="true" and no role-constraints 
      deny access
   2) the auth-acr is completely empty of 
      role-constraints -->
<auth-acr ID="Employee Role Rule">
		
   <role-constraint>
      <role-name>administrator</role-name>
   </role-constraint>

   <role-constraint>
      <role-name>employee</role-name>
   </role-constraint>

   <role-constraint accessGranted="false">
      <role-name>contractor</role-name>
      <role-class>
         com.cafesoft.security.engine.auth.CSRolePrincipal
      </role-class>
   </role-constraint>

</auth-acr>

<role-constraint>

A role-constraint grants or denies an authenticated user access by virtue of the identities (roles) associated at login time. A role-constraint applies to an authenticated user if:

  1. it contains only a <role-name> and the user has that role
  2. if contains a <role-name> and a <role-class> and the user has that role implemented by the specified Java class

A role-constraint grants access if:

  1. it applies to the authenticated user
  2. the role-constraint implicitly or explicitly has attribute: accessGranted="true"

If a role-constraint applies to the user and denies access, then the auth-acr as a whole will immediately deny access. To optimize performance, place any role-constraints that deny access at the beginning of the auth-acr.

Item Description
Syntax 
<role-constraint accessGranted="true|false">
  <role-name> ... </role-name>
  <role-class> ... </role-class>
</role-constraint>
Attributes
accessGranted Opt Indicates whether a matching role-constraint grants or denies access. If not specified, the role-constraint grants access.
Data None
Parent Elements

1. <auth-acr>
Child Elements
<role-name>
Req
 the name of a role
<role-class>
Opt
 the fully-qualified name of the Java class implementing the role. (See documentation on the LoginModules used for authentication to see the role classes they use).
Example 
<!-- Denies access to CSUserPrincipal "richard" -->
<role-constraint accessGranted="false">
  <role-name>richard</role-name>
  <role-class>com.cafesoft.cams.auth.CSUserPrincipal</role-class>
</role-constraint>

<role-name>

An role-name identifies the name of a role possibly assigned to an authenticated user. It is one of two possible criteria (<role-class> is the other) that indicates whether or not a role-constraint applies to the access request.

Item Description
Syntax 
<role-name>role name</role-name>
Attributes None
Data the name of a role or user name assigned to the user when authenticated.
Parent Elements

1. <role-constraint>
Child Elements

None
Example 
<!-- Denies access to "richard" -->
<role-constraint accessGranted="false">
  <role-name>richard</role-name>
</role-constraint>

<role-class>

An role-class identifies the Java class that implements a role possibly assigned to an authenticated user. It is one of two possible criteria (<role-name> is the other) that indicates whether or not a role-constraint applies to the access request. If specified, it must be used in conjunction with role-name and the role-constraint applies only an authenticated user has the role-name that is implemented by the specified role-class.

To determine the classes assigned to authenticated users, you'll need to know the Login Modules that were used to authenticate the user and the classes they use to add principals (roles). For more information, see the Login Configuration document.

Item Description
Syntax 
<role-class>fully.qualified.JavaClassName</role-class>
Attributes None
Data

The name of a role class associated with a role-name at login time. For example:

  • com.cafesoft.security.engine.auth.CSUserPrincipal
  • com.cafesoft.security.engine.auth.CSRolePrincipal
  • com.cafesoft.security.engine.auth.CSDomainPrincipal
Parent Elements

1. <role-constraint>
Child Elements

None
Example 
<!-- Denies access to CSUserPrincipal "richard" -->
<role-constraint accessGranted="false">
  <role-name>richard</role-name>
  <role-class>com.cafesoft.cams.auth.CSUserPrincipal</role-class>
</role-constraint>

<host-acr>

The host-acr grants or denies access to a user based on the host name and/or IP address of the computer from which he's attempting to access a protected resource. This rule does not require that the user be authenticated, but does require that the remote host and/or remote address be known.

WARNING: It is not always possible to resolve a remote host's name using the Internet's Domain Name Service (DNS). Even if a host name can be resolved, performance is sometimes poor, which can adversely effect performance. We recommend that you use host name patterns only in a controlled environments (like an intranet), where you're likely to have more control over DNS configuration and performance.

Item Description
Syntax 
<host-acr 
  id="access control rule identifier"
  debug="true|false">
	...
</host-acr>
Attributes
id Opt Uniquely identifies this rule so it can be referenced from permissions and access control rule expressions. It is required if used directly within an access control rule library, but optional if used within an access control rule expression.
debug Opt Activate debug for the host access control rule. The default is false.
Data None
Parent Elements

1. <acr-lib>
2. <acr>

Child Elements
<allow-host> Opt Lists granted remote hosts by name, 0 or more are permitted.
<deny-host> Opt Lists denied remote hosts by name, 0 or more are permitted.
<allow-address> Opt Lists accepted remote hosts by IP address, 0 or more are permitted.
<deny-address> Opt Lists denied remote hosts by IP address, 0 or more are permitted.
Example 
<!-- The following example shows a host-acr which is
     true only if:
   1) the remote host has a name that ends with 
      ".mycompany.com" or ".partner.com" 
   2) but the remote host does not include: "badcompany.com"
   3) or the remote host has IP address: 208.175.100.5
   4) or the remote host has an IP address that matches 
      pattern: 192.168.0.*
   5) but the remote host does not have IP address: 
      192.168.0.1 
-->
<host-acr ID="Extranet Partners Rule">
		
  <allow-host>
    <host>*.mycompany.com</host>
    <host>*.partner.com</host>
  </allow-host>

  <deny-host>
    <host>*badcompany.com</host>
  </deny-host>

  <allow-address>
    <address>208.175.100.5</address>
    <address>192.168.0.*</address>
  </allow-address>

  <deny-address>
    <address>192.168.0.1</address>
  </deny-address>

</host-acr>

<!-- A more typical example might grant permission to 
 		 remote hosts based on IP address -->
<host-acr ID="Simpler Extranet Partners Rule">

  <allow-address>
    <address>208.175.100.5</address>
    <address>192.168.0.*</address>
  </allow-address>

</host-acr>

A host-acr will evaluate to true ONLY if:

  1. the it contains no constraints whatsoever (i.e. it's empty)
  2. a remote host matches an accept pattern, but does not match a deny pattern

<allow-host>

Defines one or more remote host name patterns. If a remote host attempts to access a resource protected by the security constraint associated with this rule and it's host name matches a pattern within this constraint, then that remote host is eligible to have access granted. Access will be granted by the enclosing rule if the host does not match a deny pattern. If the remote host name is not available, then it cannot match this pattern so this constraint does not apply.

WARNING: It is not always possible to resolve a remote host's name using the Internet's Domain Name Service (DNS). Even if a host name can be resolved, performance is sometimes poor, which can adversely effect performance. We recommend that you use host name patterns only in a controlled environments (like an intranet), where you're likely to have more control over DNS configuration and performance.

Item Description
Syntax 
<allow-host>
  <host> ... </host>
  ...
</allow-host>
Attributes None
Data

None
Parent Elements

1. <host-acr>
Child Elements
<host> Opt The pattern for a remote host name with support for regular expression matching. Zero or more are required. See the Regular Expressions document for more information on pattern matching.
Example 
<!-- Allow connections from know sites -->
<allow-host>
  <host>*.mycompany.com</host>
  <host>*.partner.com</host>
</allow-host>

<deny-host>

Defines one or more remote host name patterns. If a remote host attempts to access a resource protected by the security-constraint associated with this rule and it's host name matches a pattern within this constraint, then that remote host is immediately denied access. If the remote host name is not available, then it cannot match this pattern so this constraint does not apply.

WARNING: It is not always possible to resolve a remote host's name using the Internet's Domain Name Service (DNS). Even if a host name can be resolved, performance is sometimes poor, which can adversely effect performance. We recommend that you use host name patterns only in a controlled environments (like an intranet), where you're likely to have more control over DNS configuration and performance.

Item Description
Syntax 
<deny-host>
  <host> ... </host>
  ...
</deny-host>
Attributes None
Data

None
Parent Elements

1. <host-acr>
Child Elements
<host> Opt The pattern for a remote host name with support for regular expression matching. Zero or more are required. See the Regular Expressions document for more information on pattern matching.
Example 
<!-- Deny all connections from Bad Company -->
<deny-host>
  <host>*badcompany.com</host>
</deny-host>

<host>

The pattern for a remote host name with support for regular expression matching. Zero or more are required. See the Regular Expressions document for more information on pattern matching.

Item Description
Syntax 
<host>host name or host pattern</host>
Attributes None
Data

host name or host pattern
Parent Elements

1. <allow-host>
2. <deny-host>
Child Elements

None
Example 
<!-- Match only a host with DNS name 
     "www1.mycompany.com" -->
<host>www1.mycompany.com</host>

<!-- Match all hosts with names that end with 
     "mycompany.com" -->
<host>*mycompany.com</host>
<!-- Match all hosts with names containing 
     "mycompany" -->
<host>*mycompany*</host>

<allow-address>

Defines one or more remote host IP address patterns. If a remote host attempts to access a resource protected by the security constraint associated with this rule and it's host IP address matches a pattern within this constraint, then that remote host is eligible to have access granted. Access will be granted by the enclosing rule only if the host does not match a deny pattern. If the remote host IP address is not available, then it cannot match this pattern so this constraint does not apply.

Item Description
Syntax 
<allow-address>
  <address> ... </address>
	...
</allow-address>
Attributes None
Data

None
Parent Elements

1. <host-acr>
Child Elements
<address> Opt The pattern for a remote host IP address with support for regular expression matching. Zero or more are required. See the Regular Expressions document for more information on pattern matching.
Example 
<!-- Grant access from specific IP addresses -->
<allow-address>
  <address>208.175.100.5</address>
  <address>192.168.0.*</address>
</allow-address>

<deny-address>

Defines one or more remote host IP address patterns. If a remote host attempts to access a resource protected by the security constraint associated with this rule and it's host IP address matches a pattern within this constraint, then that remote host is immediately denied access. If the remote host name is not available, then it cannot match this pattern so this constraint does not apply.

Item Description
Syntax 
<deny-address>
  <address> ... </address>
	...
</deny-address>
Attributes None
Data

None
Parent Elements

1. <host-acr>
Child Elements
<address> Opt The pattern for a remote host IP address with support for regular expression matching. Zero or more are required. See the Regular Expressions document for more information on pattern matching.
Example 
<!-- Deny accesss to specific IP addresses -->
<deny-address>
  <address>192.168.0.1</address>
</deny-address>

<address>

The pattern for a remote host IP address with support for regular expression matching. Zero or more are required. See the Regular Expressions document for more information on pattern matching.

Item Description
Syntax 
<address>host IP address or host IP address pattern</address>
Attributes None
Data

host IP address or host IP address pattern
Parent Elements

1. <allow-address>
2. <deny-address>
Child Elements

None
Example 
<!-- Match only a host that has IP address 
     "192.168.0.1" -->
<address>192.168.0.1</address>
<!-- Match all hosts with IP addresses that start 
     with "192.168.0." -->
<address>192.168.0.*</address>

<acr>

Creates a custom access control rule by combining other elements attributes. Once defined, access control rule expressions can be referenced directly from permissions or nested within other access control rule expression.

Item Description
Syntax 
<acr 
  id="access control rule identifier" 
  debug="true | false">
  ...
</acr>
Attributes
id Req Uniquely identifies this rule so it can be referenced from permissions and other access control rule expressions. It is required if used directly within an access control rule library, but optional if used within another access control rule expression.
debug Opt Activate debug for the authentication constraint (true or false).
Data None
Parent Elements

1. <acr-lib>
Child Elements
<granted> Opt Intrinsic Cams operator, unconditionally grant access to a resource.
<denied> Opt Intrinsic Cams operator, unconditionally deny access to a resource.
<confidential> Opt Intrinsic Cams operator, require a confidential (typically SSL/TLS) connection.
<and> | <or>| <not> Opt Boolean operators for use between access control rules.
<acr-ref> Opt A reference to an existing access control rule within the enclosing security domain's access control rule library. The referenced access control rule must already have been defined within the acr-lib or an "Undefined Access Control Rule" will be reported.
<auth-acr> Opt Requires user authentication and controls access based on the user's role(s).
<host-acr> Opt Grants or denies access to a user based on the host from which he's attempting to access a protected resource.
[custom-acr] Opt A custom access control rule of a type declared by acr-type and embedded in this rule. See acr-type and acr-persistence-manager.
Example 
<!--  
  Require:
    1. the host to be on the ACME Local Area Network
    2. the user to be authenticated with the "manager" role
    3. a confidential (SSL) connection for privacy 
-->
<acr id="ACME Manager Resources Rule">
  <acr-ref id="ACME LAN Rule"/>
  <and/>
  <acr-ref id="ACME Management Rule"/>
  <and/>
  <confidential/>
</acr>

<granted> <denied> <confidential>

Cams instrinsic access control rules that are available to all security domains. These access control rules can be referenced by their identifiers: granted, denied, and confidential. They can also be embedded as XML elements anywhere within an access control rule expression (<acr ...>).

Item Description
Syntax 
<granted/>
<denied/>
<confidential/>
Attributes None
Data

None
Parent Elements

1. <acr>
2. <permission>
Child Elements

None
Example 
<!-- Grant GET access by all to "public" -->
<permission desc="Grant access to public" actions="GET">
  <resource-pattern id="http://localhost:8080/public/*"/>
  <acr-ref id="granted"/>
</permission>

<!-- Deny GET access by all to "private" -->
<permission desc="Deny access to private" actions="GET">
  <resource-pattern id="http://localhost:8080/private/*"/>
  <acr-ref id="denied"/>
</permission>

<!-- Require a non-confidential connection -->
<acr id="non-confidential">
  <not/>	
  <confidential/>	
</acr>

<and> <or> <not>

Boolean operators for use between access control rule invocations and available to all security domains.

Item Description
Syntax 
condition <and/> condition
condition <or/> condition
</not> condition
Attributes None
Data

None
Parent Elements

1. <acr>
Child Elements

None
Example 
<!--  
  Match
    1. the host to be on the ACME Local Area Network
    2. the user to be authenticated with the "manager" role
       or "executive" role
    3. a confidential (SSL) connection for privacy  
-->
<acr id="ACME Manager Resources Rule">
   <acr-ref id="ACME LAN Rule"/>
   <and/>
   <acr-ref id="ACME Management Rule"/>
   <or/>
   <acr-ref id="ACME Executive Rule"/>
   <and/>
   <confidential/>
</acr>

Back | Next | Contents

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