Back | Next | Contents Cams Administrator's Guide

Access Control Policy Tag Reference

A Cams access control policy declares web resources and the access control rules that secure them using a security domain specific XML file, access-control-policy.xml. Web resources are declared in permissions that are grouped within permission collections. Access control rules are declared within an access control rule library.

This document contains reference information for each of the XML tags that can be used within a Cams access-control-policy.xml file to implement an access control policy. Table 1 shows the hierarchical file structure of this file with convenience links to each of the standard Cams access control XML elements. This document is also organized into the following sections:

Tag Name Instances Description

access-control-policy

1

declares an access control policy

[permission-collection]

0 ... N

a collection of permissions

[permission]

0 ... N

associates web resources with an access control rule or another security domain owner

resource-pattern

1

a URL pattern for matching web resources

acr-ref | owner

1

a reference to an access control rule in the current security domain or a security domain owner to which access control is delegated

acr-lib

1

an access control rule library

[acr-type]

0 ... N

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

acr-persistence-manager

1

defines the Java 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 name/value pair

[acr]

0 ... N

an access control rule expression

[granted]

0 ... N

always grant access

[denied]

0 ... N

always deny access

[confidential]

0 ... N

requires web resource access using a secure connection (usually SSL/TLS)

[and | or | not]

0 ... N

boolean operators to expression relationships between access control rule elements

[acr-ref]

0 ... N

a reference to another access control rule embedded in this rule

[auth-acr]

0 ... N

an authentication access control rule embedded in this rule

[auth-method-acr]

0 ... N

an authentication method access control rule embedded in this rule

[host-acr]

0 ... N

a remote host access control rule embedded in this rule

[attr-acr]

0 ... N

an attribute access control rule embedded in this rule

[obligations-acr]

0 ... N

an obligations access control rule embedded in this rule

[sql-data-acr]

0 ... N

an SQL data access control rule embedded in this rule

[example:business-hours-acr]

0 ... N

an example date/time access control rule embedded in this rule

[example:user-attribute-acr]

0 ... N

an example user session attribute 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

a constraint based on a role name and optionally a class

role-name

1

a role name

role-class

0 ... 1

a role Java class

[auth-method-acr]

0 ... N

an authentication method access control rule that implements authentication type-based access control

[host-acr]

0 ... N

a remote host access control rule that implements DNS host or IP address access control

allow-host

0 ... 1

a list of remote host names to allow access

[host]

0 ... N

a remote host name pattern

deny-host

0 ... 1

a list of remote host names to deny access

[host]

0 ... N

a remote host name pattern

allow-address

0 ... 1

a list of remote IP addresses to allow access

[address]

0 ... N

a remote host IP address pattern

deny-address

0 ... 1

a list of remote IP addresses to deny access

[address]

0 ... N

a remote host IP address pattern

[attr-acr]

0 ... N

an attribute access control rule that implements HTTP request attribute-based access control (e.g., query parameters)

[attr-target]

0 ... N

a target within an attribute access control rule to which an access control request may apply if ALL of its conditions match

acr-ref

1

a reference to the access control rule to be evaluated if all conditions defined in the attribute target match

attr-conditions

0 ... N

all conditions of a specific category that attributes must meet to match an enclosing attribute target

attr-condition

1 ... N

a specific condition that must be met by one or more attributes

attr-match

1 ... N

an attempt to match a designated attribute within an access control request against a pattern of possible values

attr-designator

1

indicates which attribute is to be used in the matching operation

attr-value

1

the value or pattern of values used by the attribute match operation

[obligations-acr]

0 ... N

an obligations access control that implements custom request routing based on access control decisions

acr-ref

1

a reference to another access control rule embedded in this obligation

obligations

1

A container for a sequence of obligation instances

[obligation]

0 ... N

An obligation

eval-result-matches

1

A container for a sequence of evaluation result matches

[eval-result-match]

0 ... N

A match condition for evaluation of an obligation's nested acr-ref

effect-matches

1

A container for a sequence of effect matches

[effect-match]

0 ... N

A match condition for evaluation of an overall access control evaluation request

attr-assignments

0 ... 1

A container for a sequence of obligation attribute assignments

[attr-assignments]

0 ... N

An obligation attribute assignment

attr-value

1

An obligation attribute assignment value

[sql-data-acr]

0 ... N

an SQL data access control rule that implements SQL database value-based access control

sql-data-source

1

the JDBC database configuration parameters

sql-data-param-sets

0 or 1

a container for sql-data-param-sets

[sql-data-param-set]

0 ... N

an SQL query to be evaluated with the result assigned to a namespace for reference within sql-data-constraint queries

sql-data-constraints

1

a container for sql-data-constraints

[sql-data-constraint]

0 ... N

a SQL select or update statement that returns an integer value indicating success or failure

session-cache-config

1

configures caching of granted access control decisions within a Cams user session

[example:business-hours-acr]

0 ... N

an example date/time access control rule

[example:user-attribute-acr]

0 ... N

an example user session attribute access

[custom-acr]

0 ... N

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

Table 1 - Hierarchical links to the standard Cams access-control-policy.xml file XML elements

Access Control Policy

An access control policy contains all the rules and permissions that govern access to web resources secured by Cams. Access control policies are specific to a security domain and defined in an XML file, access-control-policy.xml. Each HTTP request creates an access check request, which is evaluated against the Cams access control policy to return a grant or deny decision. All access check requests are first evaluated by the system security domain's access control policy, which may delegate request to another security domain.

<access-control-policy>

The top-level element for an access control policy.

Item Description
Syntax
<access-control-policy
  lastModified="date/time value"
  defaultBias="granted|denied"
  debug="true|false">
  ...
</access-control-policy> 
Attributes
lastModified Required

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

NOTE: To reload access-control-policy.xml in a running Cams policy server you must increase this value, which will also force Cams web agents to clear any cached access control responses.

defaultBias Optional If no matching resource is found, the defaultBias determines how the access check request will be handled (granted or denied). If not specified, the default bias is denied.
debug Optional Activate debug for the access control policy (true or false).
Child Elements
<permission-collection> Optional 0 ... N
<acr-lib> Required 1
Example

Example access-control-policy.xml file. Contains all examples shown in this document for easy copy and paste reference. Please note that this file does

NOTE: Because this link is for an XML-formatted file, it has been saved with a txt extension to ensure that your browser displays it without trying to interpret the XML. We recommend opening it in a text or XML editor to cut and paste the examples.

WARNING: A Cams policy server will not load this access-control-policy.xml file without additional configuration. The file contains database connection values, references to other security domains and other references that must be configured before it will load. Please read the comments, which explain the values that must be set.

Permission Collections

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

<permission-collection>

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 (used for all HTTP protocol access check requests) or cams (used for Cams protocol access check requests) are defined by default. However, Cams agents can be embedded into other types of network software, which when associated with a permission collection/permission type would enable Cams to secure other protocols (e.g. SOAP to support securing web services).

Item Description
Syntax
<permission-collection
  type="type code"
  desc="textual description"
  debug="true|false">
  ...
</permission-collection> 
Attributes
type Required A code indicating the type of permission contained within the permission collection. (http or cams).
desc Optional A description used for readability and for context-sensitive messages.
debug Optional Activate debug for the permission collection (true or false).
Data None
Child Elements
<permission> Optional 0 ... N
Example
<permission-collection type="http" desc="HTTP Resource Permissions">

  <!--=================================-->
<!-- Intrinsic Permission Examples -->
<!--=================================-->
<!-- Grant access to the Cams login/logout URIs and the Cams login, denied and error pages. WARNING: You MUST grant access to these Cams resources or the user will not be able to login/logout or be redirected to the error or denied pages. --> <permission desc="Cams IIS/J2EE login, denied and error pages" actions="GET,POST"> <resource-pattern id="*://*:*/cams*"/> <acr-ref id="granted"/> </permission> <!-- Require confidential connections for Cams login resources --> <permission desc="Cams login resources require confidential connection">
<resource-pattern id="*://*:*/cams/login*"/>
<acr-ref id="confidential"/>
</permission> <!-- Grant HTTP "GET" access to public resources --> <permission desc="Public web resources" actions="GET"> <resource-pattern id="*://*:*/*"/>
<acr-ref id="granted"/>
</permission> <!-- Deny access to system configuration files --> <permission desc="Deny direct access to configuration files">
<resource-pattern id="*://*:*/*.conf"/>
<acr-ref id="denied"/>
</permission> <!-- Delegate resources to the "myCompany" security domain
         WARNING: This will not load correctly unless a "myCompany"
         security domain is defined. -->
  <permission desc="mycompany web resources">
    <resource-pattern id="*://www.mycompany.com:*/*"/>
    <owner id="mycompany"/>
  </permission>
  <!-- Unconditionally grant access to images under employee resources -->
  <permission desc="Grant access to employee images" actions="GET">
<resource-pattern id="*://*:*/employee/images*"/>
<acr-ref id="granted"/>
</permission>
<!--=================================--> <!-- Auth Permission Examples --> <!--=================================-->
  <!-- Resources available only to authenticated employees -->
  <permission desc="Employee web resources">
    <resource-pattern id="*://*:*/employee*"/>
    <acr-ref id="complex employee rule"/>
  </permission>
  <!-- Grant access to images under employee resources -->
  <permission desc="Grant access to employee images" actions="GET">
    <resource-pattern id="*://*:*/employee/images*"/>
    <acr-ref id="granted"/>
  </permission>
  <!--=================================-->
  <!-- Host Permission Examples        -->
  <!--=================================-->
  <!-- Resources available only when using any LAN host -->
  <permission desc="All LAN hosts can access internal resources">
    <resource-pattern id="*://*:*/internal*"/>
    <acr-ref id="lan rule"/>
  </permission>
  <!-- Resources available only when using a specific WAN hosts -->
  <permission desc="Specific WAN hosts can access partner resources">
    <resource-pattern id="*://*:*/partner*"/>
    <acr-ref id="wan rule"/>
  </permission>
  <!--=================================-->
  <!-- Auth/Host Permission Examples   -->
  <!--=================================-->
  <!-- Resources available only when authenticated as an "administor"
       from any LAN host -->
  <permission desc="Administrator resources that can only be access from LAN">
    <resource-pattern id="*://*:*/admin*"/>
    <acr-ref id="administrator lan rule"/>
  </permission>
  <!--=================================-->
  <!-- Attribute Permission Example    -->
  <!--=================================-->
  <!-- ReportBuilder historical reports are only available to shareholders
       for specific report types and years. -->
  <permission desc="Administrator resources that can only be access from LAN">
    <resource-pattern id="*://*:*/ReportBuilder/gethistorical.do"/>
    <acr-ref id="shareholder reportbuilder rule"/>
  </permission>
  <!--=================================-->
  <!-- Obligations Permission Example  -->
  <!--=================================-->
  <!-- Users must be authenticated with the "PASSWORD" authentication method
       to update their profiles. -->
  <permission desc="Users must authenticate with user name and password for self-administration">
    <resource-pattern id="*://*:*/CamsIdentity/selfAdmin*"/>
    <acr-ref id="obligate authenticated user with password authentication method rule"/>
  </permission>
  <!--=================================-->
  <!-- SQL Data Permission Example     -->
  <!--=================================-->
  <!-- Users must be authenticated and have completed information in the user
       database table COMPANY field. -->
  <permission desc="Users must authenticate with user name and password for self-administration">
    <resource-pattern id="*://*:*/whitepapers*"/>
    <acr-ref id="authenticated user with completed company rule"/>
  </permission>
  <!--=================================-->
  <!-- Custom Rule Permission Examples -->
  <!--=================================-->
  <!-- Resources available during business hours -->
  <permission desc="Live support is only available during business hours">
    <resource-pattern id="*://*:*/livesupport*"/>
    <acr-ref id="business hours rule"/>
  </permission>
  <!-- Resources only available to authenticated users with gold accounts -->
  <permission desc="Gold account resources only available to users with gold accounts">
    <resource-pattern id="*://*:*/goldaccount*"/>
    <acr-ref id="account type rule"/>
  </permission>
</permission-collection>

<permission>

A type-specific resource and rules for controlling access. A permission identifies a set of resources via a resource pattern and either an access control rule to evaluate or the owner of another security domain to which access control will be delegated. 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. Permissions overlap if their fully-qualified resource patterns are identical and they have at least one action in common. An access control policy referencing an overlapping permission will fail to load.

Item Description
Syntax
<permission 
  desc="textual description"
  actions"GET,POST,PUT,DELETE,HEAD,OPTIONS,TRACE | ACCESS, START, STOP"
  debug="true|false">
  ...
</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:

  • 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).
Child Elements
<resource-pattern>
Required
1
<acr-ref> or <owner>
Required
1
Example See permission-collection example

<resource-pattern>

Identifies the resources associated with a permission. When a permission receives an access control request, it compares the requested resource and action against it's identifer and actions patterns. If the patterns match and are the most specific for the request, then the permission will be used to enforce access control.

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

A pattern for matching resources identifiers. The actual syntax of this pattern depends on the type of resource being protected:

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

Support for pattern wild card matching and range matching can vary by permission type. For more information, see How Cams Access Control Works.

ignoreCase Opt

To prevent security holes on web servers that provide case-insensitive access to resources, specify true for this value. If not specified, the default behavior is false, resulting in case-sensitive URI pattern matching.

NOTE: Sites using IIS on Microsoft Windows should consider use of this flag and testing for any case-sensitive security holes.

Child Elements None
Example See permission-collection example

<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 (composite) custom access control rules

The referenced access control rule must already have been defined within the access control library or an Undefined Access Control Rule will be reported.

Item Description
Syntax
<acr-ref id="access control rule identifier reference"/>
Attributes
id Required

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

  • granted
  • denied
  • confidential

Other Cams access control rules identifiers associated with defined instances within the enclosing access control rule library, including types:

  • acr-ref
  • auth-acr
  • auth-method-acr
  • host-acr
  • attr-acr
  • obligations-acr
  • sql-data-acr
  • custom
Child Elements None
Example See permission-collection example and acr example

<owner>

A reference to an existing security domain (other than system) to which access control for a permission is delegated.

Item Description
Syntax
<owner id="security domain name"/>
Attributes
id Required

the name of an existing security domain (other than system).

Child Elements None
Example See permission-collection example

Access Control Rule Library

An access control rule library is a container for defining all access control rules available within a security domain. There is only one access control rule library for each security domain. Access control rules defined in one security domain may not be referenced from another security domain.

<acr-lib>

A container for all security domain access control rule types and references.

Item Description
Syntax
<acr-lib debug="true|false">
  ...
</acr-lib> 
Attributes
debug Opt Activate debug for the library. The default is false.
Child Elements
<acr-type> Optional 0 ... N
<acr> Optional 0 ... N
<auth-acr> Optional 0 ... N
<auth-method-acr> Optional 0 ... N
<host-acr> Optional 0 ... N
<attr-acr> Optional 0 ... N
<obligations-acr> Optional 0 ... N
<sql-data-acr> Optional 0 ... N
<example:business-hours-acr> Optional 0 ... N
<example:user-attribute-acr> Optional 0 ... N
[custom-acr] Optional 0 ... N
Example
<acr-lib>

  <!--======================================-->
<!-- Host Access Control Rule Examples -->
<!--======================================--> <!-- Allow hosts where: 1) the remote host has an IP address that matches pattern "192.168.0.*" -->
<host-acr id="lan rule"> <allow-address> <address>192.168.0.*</address> </allow-address> </host-acr> <!-- Allow hosts where: 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 "203.142.0.101" --> <host-acr id="wan 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>203.142.0.101</address> </deny-address> </host-acr>
  <!--======================================-->
  <!-- Auth Access Control Rule Examples    -->
  <!--======================================-->

  <!-- Cams agents must have the "cams-agent" role -->
  <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>

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

  <!-- Allow only if:
       1) the user is authenticated
       2) and the user has the "administrator" role
       3) or 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) the user is authenticated and at least one role-
          constraint matches a user role and no role-constraints
          deny access
       2) the user is authenticated and auth-acr is completely
          empty of role-constraints -->
  <auth-acr id="complex employee 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.cams.auth.CSRolePrincipal</role-class>
    </role-constraint>
  </auth-acr>

  <!-- Require an authenticated user to have "administrator" role,
       which must be implemented by a specific role class -->
  <auth-acr id="administrator rule">
    <role-constraint>
      <role-name>administrator</role-name>
      <role-class>com.cafesoft.cams.auth.CSRolePrincipal</role-class>
    </role-constraint>
  </auth-acr>
  <!-- Require:
       1. the host to be on the LAN
       2. the user to be authenticated with "administrator" role
       3. a confidential (SSL) connection for privacy -->
  <acr id="administrator lan rule">
    <acr-ref id="lan rule"/>
    <and/>
    <acr-ref id="administrator rule"/>
    <and/>
    <confidential/>
  </acr>

</acr-lib>

<acr-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. This tag registers new access control rule types created using the Cams Access Control Rule API. See the Cams Programmer's Guide - Access Control Rules for more details.

Item Description
Syntax
<acr-type>
  ...
</acr-type> 
Attributes
name Required The name associated with the access control rule type.
className Required The fully-qualified name of the Java class that implements the access control rule.
desc Optional A textual description of the access control rule type.
Child Elements
<acr-persistence-manager> Required 1
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>

<acr-persistence-manager>

Configures the Java class that is responsible for storing, loading, and creating new access control rules.

Item Description
Syntax
<acr-persistence-manager debug="true|false">
  ...
</acr-persistence-manager> 
Attributes
className Required The fully-qualified name of the Java class that implements the access control rule persistence manager.
Child Elements
<param-list> Optional 0 ... 1
Example See example-acr-type

<param-list>

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

Item Description
Syntax
<param-list>
  ...
</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 See example-acr-type

<param>

A parameter used to set the default configuration.

Item Description
Syntax
<param name="textual name" value="value"/>
Attributes
name Required The textual parameter name.
value Required The parameter value.
Child Elements None
Example See example-acr-type

Access Control Rule Expressions

Access control rule expressions are rules declared by referencing other existing rules with boolean operators that specify any conditional logic. For example, you can use an access control rule expression to create access control rules such as Only allow access to users with role administrator while using hosts on LAN during business hours.

<acr>

Creates a custom access control rule by combining other element attributes. Once defined, access control rule expressions can be referenced directly from permissions or nested within other access control rule expressions using the acr-ref element.

Item Description
Syntax
<acr
  id="access control rule identifier"
  debug="true | false">
  ...
</acr>
Attributes
id Required/
Optional
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 the reference is embedded within another access control rule expression.
debug Optional Activate debug for the authentication constraint (true or false).
Child Elements
<granted> Optional 0 ... N
<denied> Optional 0 ... N
<confidential> Optional 0 ... N
<and> | <or>| <not> Optional 0 ... N
<acr-ref> Optional 0 ... N
<auth-acr> Optional 0 ... N
<auth-method-acr> Optional 0 ... N
<host-acr> Optional 0 ... N
<attr-acr> Optional 0 ... N
<obligations-acr> Optional 0 ... N
<sql-data-acr> Optional 0 ... N
<example:business-hours-acr> Optional 0 ... N
<example:user-attribute-acr> Optional 0 ... N
[custom-acr] Optional 0 ... N
Example See acr-lib example

<granted> <denied> <confidential>

Instrinsic access control rules available to all security domains and referenced by their identifiers:

  • granted - unconditionally grant access to a resource
  • denied - unconditionally deny access to a resource
  • confidential - require a confidential connection (usually SSL/TLS)
Item Description
Syntax
<granted/>
<denied/>
<confidential/>
Attributes None
Child Elements

None

Example See permission-collection granted, denied and confidential examples

<and> <or> <not>

Boolean operators embedded in access control rule expressions that define logical relationships between access control rule invocations.

Item Description
Syntax
acr-ref <and/> acr-ref
acr-ref <or/> acr-ref
<not/> acr-ref
Attributes None
Child Elements

None

Example See acr-lib example

Authentication Access Control Rule

Requires user authentication and controls access based on the user's role(s). This is commonly referred to as Role-based Access Control (RBAC).

<auth-acr>

An authentication access control rule forces user authentication and controls access by the user's roles. It is composed of zero 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. Access is granted if:

  1. the user is authenticated and no role-constraints are required

or 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 authentication access control rule 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 policy server authentication configured for the protected resource assigns one or more roles to the user (a user is always assigned at least one role with his own user name).

Let's clarify with an example where a user authenticates with a user name of johndoe and password. The following roles are assigned by the Cams policy server authentication system:

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

Don't let the user designation fool you, johndoe is also a role. Keep in mind that a Cams access control policy can distinguish internall between a user role and a role, when required, using a role-class constraint.

Item Description
Syntax
<auth-acr
  id="access control rule identifier"
  debug="true | false">
  ...
</auth-acr>
Attributes
id Optional 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 Optional Activate debug for the authentication constraint. The default is false.
Child Elements
<role-constraint> Optional 0 ... N
Example See acr-lib example

<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 authentication access control rule as a whole will immediately deny access. To optimize performance, place any role-constraints that deny access at the beginning of the rule.

Item Description
Syntax
<role-constraint accessGranted="true | false">
  ...
</role-constraint>
Attributes
accessGranted Optional Indicates whether a matching role-constraint grants or denies access. If not specified, the default is to grant access.
Child Elements
<role-name>
Required
1
<role-class>
Optional
0 ... 1
Example See acr-lib example

<role-name>

Identifies the name of a role that is possibly assigned to an authenticated user.

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.
Child Elements

None

Example See acr-lib example

<role-class>

Identifies the fully-qualified name of the Java class that implements a role that is possibly assigned to an authenticated user. If specified, the role-constraint applies only if an authenticated user has a role-name 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.cams.auth.CSUserPrincipal
  • com.cafesoft.cams.auth.CSRolePrincipal
Child Elements

None

Example See acr-lib example

Authentication Method Access Control Rule

An access control rule that requires a particular method of authentication to access a protected resource. The Cams login module implementations are responsible adding an authentication method
to the user session corresponding to one of the following standard authentication methods:

  • Password - The authentication was performed by means of a password.
  • Cams Autologin - The authentication was performed by means of a Cams autologin.
  • Kerberos - The authentication was performed by means of the Kerberos protocol [RFC 1510].
  • Secure Remote Password (SRP) - The authentication was performed by means of Secure Remote Password protocol as specified in [RFC 2945].
  • Hardware Token - The authentication was performed by means of an unspecified hardware token.
  • SSL/TLS Certificate Based Client Authentication - The authentication was performed using either the SSL or TLS protocol with certificate based client authentication.
  • X.509 Public Key - The authentication was performed by some (unspecified) mechanism on a key authenticated by means of an X.509 PKI.
  • PGP Public Key - The authentication was performed by some (unspecified) mechanism on a key authenticated by means of a PGP web of trust.
  • SPKI Public Key - The authentication was performed by some (unspecified) mechanism on a key authenticated by means of a SPKI PKI.
  • XKMS Public Key - The authentication was performed by some (unspecified) mechanism on a key authenticated by means of a XKMS trust service.
  • XML Digital Signature - The authentication was performed by means of an XML digital signature.

All standard Cams login modules support both the PASSWORD and AUTOLOGIN authentication methods. See the documentation for the login modules supplied with Cams or any custom login module in use at your site for information on the supported authentication methods.

NOTE: A complete description of the non-cams authentication methods can be found in the Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V1.1.

<auth-method-acr>

Implements an access control rule based on the user authentication method. This rule should usually be combined with an access control rule expression such that, minimally, the expression evaluates not only the authentication method but first ensures that the user is authenticated. It might also be combined with an obligation-acr to, on a denied exception, prompt the user for a higher level of authentication. For example, if a user is logged in with the Cams autologin authentication method, an access control rule expression can be implemented with an obligation to redirect the user to a login page, which would prompt for user name and password authentication. An example is provide below.

Item Description
Syntax
<auth-method-acr
  id="access control rule identifier" 
method="uniform resource name"/>
Attributes
id Required 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 the reference is embedded within another access control rule expression.
method Required

The URN of the authentication method to require. Standard Cams supported authentication methods are:

  • urn:oasis:names:tc:SAML:1.0:am:password
  • urn:cams:1.0:names:auth-method:auto-login
  • urn:oasis:names:tc:SAML:1.0:am:X509-PKI
Child Elements

None

Example
<!-- Require the PASSWORD authentication method -->
<auth-method-acr
  id="Require Password Authentication Method"
  method="urn:oasis:names:tc:SAML:1.0:am:password"/>

Host Access Control Rule

Grant or deny access to a user based on the host from which he's attempting to access a protected resource.

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.

<host-acr>

Grants or denies access based on the host name and/or IP address of the user's remote computer. This rule does not require user authentication, but does require that the remote host and/or remote address be known. A host access control rule will evaluate to true ONLY if:

  1. 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
Item Description
Syntax
<host-acr
  id="access control rule identifier"
  debug="true | false">
...
</host-acr>
Attributes
id Optional 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 Optional Activate debug for the host access control rule. The default is false.
Child Elements
<allow-host> Optional 0 ... 1
<deny-host> Optional 0 ... 1
<allow-address> Optional 0 ... 1
<deny-address> Optional 0 ... 1
Example See acr-lib example

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

Item Description
Syntax
<allow-host>
  ...
</allow-host>
Attributes None
Child Elements
<host> Optional 0 ... N
Example See acr-lib example

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

Item Description
Syntax
<deny-host>
...
</deny-host>
Attributes None
Child Elements
<host> Optional 0 ... N
Example See acr-lib example

<host>

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

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

Host name or host pattern

Child Elements

None

Example See acr-lib example

<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>
  ...
</allow-address>
Attributes None
Data

None

Child Elements
<address> Optional 0 ... N
Example See acr-lib example

<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>
  ...
</deny-address>
Attributes None
Child Elements
<address> Optional 0 ... N
Example See acr-lib example

<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

Child Elements

None

Example See acr-lib example

Attribute Access Control Rule

Enables evaluation of HTTP and other access control request attributes using if-then-else style access control logic. If a given access control request matches a set of conditions, then another referenced access control rule associated with those conditions is evaluated to determine if access is granted or denied.

<attr-acr>

Each attribute access control rule may contain zero or more targets. A target has a nested access control rule reference that is evaluated if it is the first target where ALL associated attribute conditions match an access control request. If the attribute access control rule does not contain any targets or an access control request does not match any targets, then a default access control rule is evaluated.

The following pseudo code expresses an example of business logic that can be implemented by attribute access control rule:

   if ((requested an historical report) AND
       (requested report-type is FINANCIAL or AUDIT) AND
       (requested year is 2002 or 2003)) then

      if (user is authenticated) then
         if (user has the Shareholder role) then
            Grant Access;
         else
            Deny Access;
      else
         Deny Access, Require User Authentication;
   else
      Deny Access, No match - Target missing required attribute;

Nearly every value within an access control request can be referenced as an attribute. Each attribute within an access control request has an identifier, belongs to a category, and has one or more attribute values of a specific data type.

Every standard Cams attribute identifier, category and data type is designated by a Uniform Resource Name (URN). For example:

  • Attribute identifier: urn:cams:1.0:names:resource:resource-id
  • Category: urn:cams:1.0:names:attribute-category:resource
  • Data type: urn:cams:1.0:names:data-type:string

NOTE: A URN is a sub-category of Uniform Resource Identifer (URI), which names a resource but does not specify how to locate it. A more detailed explanation of URNs, URIs, and URLs is available in the Java 2 Javadoc for class java.net.URI, which is used internally by Cams to store URNs.

Use of URNs for Cams attribute identifiers, categories and data types provides a highly structured and extensible naming strategy. See the following sections for more details:

Item Description
Syntax
<attr-acr
  id="access control rule identifier"
  default-acr-ref="access control rule indentifier reference"
  debug="true|false">
  ...
</attr-acr> 
Attributes
id Required Uniquely identifies this rule so it can be referenced from permissions and other access control rule expressions.
default-acr-ref Required Identifies an access control rule that is evaluated and whose value is returned from this access control rule if no attribute targets are matched by a given request.
debug Optional Activate debug for this access control rule (true or false).
Child Elements
<attr-target> Optional 0 ... N
Example
<!--
   If the ReportBuilder application is accessed, make sure the required HTTP
   parameters are present and valid. If the target matches, then invoke the
   "shareholder rule", access control rule, which will enforce authentication
   and the shareholder role. -->

<auth-acr id="shareholder rule">
<role-constraint>
<role-name>shareholder</role-name>
</role-constraint>
</auth-acr> <attr-acr id="shareholder reportbuilder rule" default-acr-ref="denied"> <!-- Target 1: Protect FINANCIAL and AUDIT reports for years 2002-2003 --> <attr-target desc="FINANCIAL and AUDIT reports for years 2002-2003"> <acr-ref id="shareholder rule"/> <!-- Conditions for resource attributes --> <attr-conditions category="urn:cams:1.0:names:attribute-category:resource"> <!-- Match the URI where historical reports are requested --> <attr-condition desc="Historical report resource ID (URI) Condition"> <attr-match function-id="urn:cams:1.0:names:function:regexp-string-match" desc="Match the URI for accessing historical reports"> <attr-designator data-type="urn:cams:1.0:names:data-type:string"
id="urn:cams:1.0:names:resource:resource-id"
must-be-present="true"/>
<attr-value data-type="urn:cams:1.0:names:data-type:string"> ^.*/gethistorical.do </attr-value> </attr-match> </attr-condition> </attr-conditions> <!-- Conditions for "http-param" attributes --> <attr-conditions category="urn:cams:1.0:names:attribute-category:action"> <!-- Require valid report-type --> <attr-condition desc="Required the report-type parameter to be FINANCIAL or AUDIT"> <attr-match function-id="urn:cams:1.0:names:function:equals-ignorecase-string-match" desc="Match the FINANCIAL report type"> <attr-designator data-type="urn:cams:1.0:names:data-type:string"
id="urn:cams:1.0:names:action:http-param:report-type"
must-be-present="true"/>
<attr-value data-type="urn:cams:1.0:names:data-type:string"> FINANCIAL </attr-value> </attr-match> <attr-match function-id="urn:cams:1.0:names:function:equals-ignorecase-string-match" desc="Match the AUDIT report type"> <attr-designator data-type="urn:cams:1.0:names:data-type:string"
id="urn:cams:1.0:names:action:http-param:report-type"
must-be-present="true"/>
<attr-value data-type="urn:cams:1.0:names:data-type:string"> AUDIT </attr-value> </attr-match> </attr-condition> <!-- Require valid year --> <attr-condition desc="Require the year parameter to be 2003 or 2005"> <attr-match function-id="urn:cams:1.0:names:function:regexp-string-match" desc="Match the FINANCIAL report type"> <attr-designator data-type="urn:cams:1.0:names:data-type:string"
id="urn:cams:1.0:names:action:http-param:year"
must-be-present="true"/>
<attr-value data-type="urn:cams:1.0:names:data-type:string"> 200[3-4] </attr-value> </attr-match> </attr-condition> </attr-conditions> </attr-target> </attr-acr>

<attr-target>

Creates a possible target for an access control request within an attribute access control rule. An attribute target contains one access control rule reference and any number of attribute conditions, which are evaluated in order to determine if the target applies. If ALL attribute conditions associated with a target are met, then the access control rule referenced by the target is evaluated and its response is returned as the enclosing attribute rule response.

Item Description
Syntax
<attr-target desc="textual description">
 ...
</attr-target> 
Attributes
desc Optional A textual description displayed in the enclosing security domain's trace log file when debugging is enabled. Useful for debugging target matching.
Child Elements
<acr-ref> Required 1
<attr-conditions> Optional 0 ... N
Example See attr-acr example

<attr-conditions>

Creates an attribute category-specific set of conditions for matching an enclosing attribute target. Attribute conditions contains one or more individual attribute condition elements, which are evaluated in order. If ALL individual attribute condition elements match, then the overall attribute conditions for the given category match. A sequence of conditions, all of which must be met in order to match the enclosing attribute target. One attr-conditions element is required for each category of attributes.

Item Description
Syntax
<attr-conditions
  category="attribute category URI"
  desc="textual description">
  ...
</attr-conditions> 
Attributes
category Required

The category of attributes associated with the conditions. This value is a fully-qualified URI that starts with prefix:

urn:cams:1.0:names:attribute-category:

See the complete list of standard Cams attribute categories.

desc Optional A textual description displayed in the enclosing security domain's trace log file when debugging is enabled. Useful for debugging attribute conditions matching.
Child Elements
<attr-condition> Required 1 ... N
Example See attr-acr example

<attr-condition>

Creates an individual attribute condition evaluated against an access control request. Each attribute condition contains one or more attribute match operations. If ANY enclosed attribute match succeeds, then the condition succeeds. If ALL enclosed attribute matches fail, then the condition fails. An individual condition within a set of category-specific attribute conditions. If all attr-condition elements match a given access control request, then the enclosing attr-conditions matches.

Item Description
Syntax
<attr-condition desc="textual description">
  ...
</attr-condition> 
Attributes
desc Optional A textual description displayed in the enclosing security domain's trace log file when debugging is enabled. Useful for debugging evaluation of an attribute condition.
Child Elements
<attr-match> Required 1 ... N
Example See attr-acr example

<attr-match>

Creates an attribute match, which is reponsible for matching an attribute value from an access control request against a value or pattern of values. An attribute match specifies a function to be used, an attribute designator (which identifies which attribute to compare), and an attribute value which indicates the value or pattern of values to match. An individual attribute match operation. An attri-condition may contain any number of attr-match elements. If ANY attr-match succeeds, then the attr-condition succeeds, else the attr-condition fails, the enclosing attr-conditions fail, and the enclosing attr-target does not match the access control request.

Item Description
Syntax
<attr-match
  function-id="matching function URI"
  desc="textual description">
  ...
</attr-match> 
Attributes
function-id Required The identifier of the function to be used when matching an access control request attribute value against the attribute value (or pattern of values) specified in the attr-match. This value is a fully-qualified URI that starts with prefix:

urn:cams:1.0:names:function:

See the complete list of standard Cams attribute matching functions.

desc Optional A textual description displayed in the enclosing security domain's trace log file when debugging is enabled. Useful for debugging attribute matching.
Data None
Parent Elements

1. <attr-condition>

Child Elements
<attr-designator> Required 1
<attr-value> Required 1
Example See attr-acr example

<attr-designator>

An attribute designator selects values from an access control request by attribute identifier, data type, and category (indicated by the enclosing attr-conditions). The values (if they exist) can then be used by the enclosing attribute matching function to compare against an attribute value or pattern of attribute values.

Attribute designators are also responsible for indicating whether or not a given attribute must be present in an access control request in order to evaluate the enclosing condition. If a designator indicates that a given attribute must be present, but it is not available from the access control request, then the enclosing attribute access control rule denies access due to missing/required attribute. If a designator indicates that a given attribute need not be present and it is not available from the access control request, then the enclosing attribute match is ignored. If a subsequent attribute match within the same condition matches, then the condition matches and evaluation of conditions continues.

An individual attribute match operation. An attri-condition may contain any number of attr-match elements. If ANY attr-match succeeds, then the attr-condition succeeds, else the attr-condition fails, the enclosing attr-conditions fail, and the enclosing attr-target does not match the access control request.

Item Description
Syntax
<attr-designator
  data-type="attribute value(s) data type URI"
  id="attribute value(s) URI"
  must-be-present="true|false"/>
Attributes
data-type Required The identifier of an attribute value data type. This value is a fully-qualified URI that starts with prefix:

urn:cams:1.0:names:data-type:

See the complete list of standard Cams data types.

id Required The identifier of the attribute value(s) to be selected from an access control request. This value is a fully-qualified URI that starts with prefix:

urn:cams:1.0:names:data-type:

See the complete list of standard Cams attribute identifiers.

must-be-present Optional A boolean flag (valid values are true or false) indicating whether an attribute value corresponding to the category, id, and data-type must be present in an access control request. If true, but the attribute is not present, then the enclosing access control rule immediately denies access due to a missing, required attribute. If false, or not specified, and the attribute is not present, then the enclosing attr-condition continues to the next attr-match.
Child Elements None
Example See attr-acr example

<attr-value>

An attribute value specifies the value or pattern of values for matching values selected by an attribute designator. Attribute values have an associated data type.

A value or pattern of values used by the matching function to compare the value(s) from the access control request indicated by the attribute designator.

Item Description
Syntax
<attr-value data-type="data type URI">
  value
</attr-value>
Attributes
data-type Required The identifier of an attribute value data type. This value is a fully-qualified URI that starts with prefix:

urn:cams:1.0:names:data-type:

See the complete list of standard Cams data types.

Data The string representation of the attribute data value.
Child Elements None.
Example See attr-acr example

Standard Cams Attribute Categories

Every attribute available from a Cams access control request is uniquely specified by:

  1. An attribute category
  2. An attribute value data type
  3. An attribute identifier

Each of these values is represented by a URI, which provides a standardized identification scheme. Cams provides a standard and extensible set of attribute categories. Current categories include:

  • urn:cams:1.0:names:attribute-category:resource - attributes associated with a requested resource. For example, the resource identifier, type, etc.
  • urn:cams:1.0:names:attribute-category:action - attributes associated with an action, usually on a resource. For example GET or POST (for web resources) or READ, WRITE, DELETE for file-based resources.
  • urn:cams:1.0:names:attribute-category:environment - attributes associated with the environment in which an access control request is evaluated.
  • urn:cams:1.0:names:attribute-category:subject - attributes associated with a user or some other subject associated with an access control request such as a Cams web agent.

See section Standard Cams Attribute Identifiers for a comprehensive list of attributes in each of these categories.

Standard Cams Attribute Data Types

Every attribute available from a Cams access control request is uniquely specified by:

  1. An attribute category
  2. An attribute value data type
  3. An attribute identifier

Each of these values is represented by a URI, which provides a standardized identification scheme. Cams includes support for attribute data types:

  • urn:cams:1.0:names:data-type:string - a string attribute value.

Support may be added for the following data types:

  • urn:cams:1.0:names:data-type:boolean - a boolean attribute value.
  • urn:cams:1.0:names:data-type:double - an numeric double precision floating point attribute value.
  • urn:cams:1.0:names:data-type:time - a time attribute value.
  • urn:cams:1.0:names:data-type:date - a date attribute value.
  • urn:cams:1.0:names:data-type:date-time - a date/time attribute value.
  • urn:cams:1.0:names:data-type:integer - a numeric integer attribute value.
  • urn:cams:1.0:names:data-type:uri - a uniform resource identifier (which includes URLs).
  • urn:cams:1.0:names:data-type:hex-binary - a hexidecimal encoded binary value.
  • urn:cams:1.0:names:data-type:base64-binary - a base-64 encoded binary value.
  • urn:cams:1.0:names:data-type:x500-name - an LDAP distinguished name.
  • urn:cams:1.0:names:data-type:rfc822-name - an email address.

NOTE: Please contact Cafésoft support if one of these data types and an associated matching functions are desired.

Standard Cams Attribute Identifiers

Cams attribute identifiers are represented by URIs that start with one of the following prefixes:

  • urn:cams:1.0:names:resource - attributes associated with a resource.
  • urn:cams:1.0:names:action - attributes associated with an action, usually on a resource.
  • urn:cams:1.0:names:environment - attributes associated with the environment.
  • urn:cams:1.0:names:subject - attributes associated with the user requesting access to a resource.
  • urn:cams:1.0:names:access-subject - attributes associated with the component attempting to access a resource on the user's behalf, such as a Cams web agent.

Attributes are also associated with a category and a data type.

Resource Attribute Identifiers

Resource attributes pertain to resource associated with an access control request. Standard resource attribute identifiers include:

urn:cams:1.0:names:resource:resource-id
Description: The string representation of the fully-qualfied identifier for a requested resource.
Category: urn:cams:1.0:names:attribute-category:resource
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • http://www.cafesoft.com:80/index.html
  • cams://127.0.0.1:9191/

urn:cams:1.0:names:resource:resource-type
Description: The string representation of a resource type.
Category: urn:cams:1.0:names:attribute-category:resource
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • http
  • cams

Action Attribute Identifiers

Action attributes pertain to actions requested on resources. Standard action attribute identifiers include:

urn:cams:1.0:names:action:action-id
Description: The string representation of a requested action on a resource.
Category: urn:cams:1.0:names:attribute-category:action
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • GET
  • POST
  • PUT
  • DELETE
  • TRACE
  • HEAD

Environment Attribute Identifiers

Environment attributes pertain to the systems, time, etc. context in which access control decisions are requested. Standard environment attribute identifiers include:

urn:cams:1.0:names:environment:login-config-entry
Description: The Cams login configuration entry to use should a user require authentication. This value generally corresponds to the type of Cams agent executing the access control check.
Category: urn:cams:1.0:names:attribute-category:environment
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • http
  • cams

Subject Attribute Identifiers

Subject attributes pertain to users. Standard subject attribute identifiers include:

urn:cams:1.0:names:subject:remote-addr
Description: The string representation of the IP address from which the requesting subject is attempting to access a resource
Category: urn:cams:1.0:names:attribute-category:subject
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • 192.168.10.201
  • 127.0.0.1

urn:cams:1.0:names:subject:remote-host
Description: The string representation of the network host from which the requesting subject is attempting to access a resource. NOTE: If DNS resolution of IP addresses is not enables, this value will be the same as remote-addr.
Category: urn:cams:1.0:names:attribute-category:subject
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • host1.mydomain.com
  • host2.mydomain.com
  • 192.168.10.201

Access Subject Attribute Identifiers

Access Subject attributes pertain to system entities that initiate access control requests (Cams web agents). These attributes identify various properties of Cams web agents and/or the environment in which a Cams web agent is installed. Standard access subject attribute identifiers include:

urn:cams:1.0:names:access-subject:agent-type
Description: The class of a principal associated with the authenticated subject.
Category: urn:cams:1.0:names:attribute-category:access-subject
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • http

urn:cams:1.0:names:access-subject:agent-impl
Description: The implementation name of the requesting Cams web agent.
Category: urn:cams:1.0:names:attribute-category:access-subject
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • tomcat4
  • tomcat5
  • servletfilter23
  • iis
  • apache13
  • apache20
  • sunone61

urn:cams:1.0:names:access-subject:agent-version
Description: The release version of the requesting Cams web agent.
Category: urn:cams:1.0:names:attribute-category:access-subject
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • 2.1.27 beta
  • 2.0.20

urn:cams:1.0:names:access-subject:agent-id
Description: An unique identifier for the requesting Cams web agent within the deployment envirionment. This value is generally configurable for each Cams web agent, enabling administrators to base access control policy on specific agent instances.
Category: urn:cams:1.0:names:attribute-category:access-subject
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • MyCamsAgent
  • urn:cams:agent:www.cafesoft.com:80
  • 443

urn:cams:1.0:names:access-subject:agent-os
Description: A token corresponding to the type operating system in which the Cams web agent is running.
Category: urn:cams:1.0:names:attribute-category:access-subject
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • Windows XP
  • Windows 2000
  • Windows 2003
  • Linux
  • SunOS

Cams Web Agent HTTP Request Attributes

Cams web agents supporting version 2.0 and higher of the Cams access control protocol may also support access control based on HTTP query parameters and other HTTP request element (like headers, cookies, etc.). Some of the HTTP request elements are already mapped to more general attributes, like the resource-id, action-id, etc. Check the Cams web agent specific release notes for more detailed information.

HTTP Query Parameters as Attributes

In some cases, it is desirable to control access to web agents based on query parameters. For example, the HTTP request:

GET http://www.mydomain.com:80/mywebapp?name1=value1&name2=value2

might need to have access granted based on availability of the name1 and name2 query parameters and their values. If enabled on supporting Cams web agents, these parameters would be available as attributes:

urn:cams:1.0:names:action:http-param:name1=value1
Description: An example HTTP query parameter made available by Cams as an action attribute.
Category: urn:cams:1.0:names:attribute-category:action
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • name1=value1
HTTP Request Headers as Attributes

You may also control access based on the HTTP request headers provided by web clients. For example, if the "user-agent" HTTP request header is a WebDAV client, then you may want to place additional constraints (like an IP address rule) on access to the web site. The HTTP request headers received can vary widely based on web browser, the web server, the requested URL, intervening proxy servers, etc., but the following are common for HTTP 1.1 requests:

  • Accept
  • Accept-Charset
  • Accept-Encoding
  • Accept-Language
  • Authorization
  • Expect
  • From
  • Host
  • Max-Forwards
  • Proxy-Authorization
  • Range
  • Referer
  • User-Agent

A more complete list of standard HTTP request headers and their meanings is available in the HTTP 1.1 specification. To send HTTP request headers with access control requests, you must enable the property documented in the agent's cams-webagent.conf file. Cams web agents cannot send Cams HTTP request headers, because they are generally injected into the HTTP request after access control is completed. If Cams HTTP request headers sent via an upstream Cams Web Agent, they are excluded from the headers sent with access control checks.

Cams HTTP request header attribute names are normalized to lower case and belong to the "urn:cams:1.0:names:environment:http-req-header" category.

urn:cams:1.0:names:action:http-req-header:name
Description: An example HTTP request header made available by Cams as an environment attribute.
Category: urn:cams:1.0:names:attribute-category:environment
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • urn:cams:1.0:names:environment:http-req-header:user-agent
  • urn:cams:1.0:names:environment:http-req-header:referer
HTTP Cookies as Attributes

You may also control access based on the HTTP cookies provided by web clients. For example, you may want to grant or deny access to a web application based on an application-specific cookie value. When HTTP cookies as attributes is enabled in Cams web agents, all HTTP cookies present in an HTTP request are sent as attributes, including Cams session identifier cookies, Cams AUTOLOGIN cookies, JSESSION cookies, ASPSESSION cookies, etc.

NOTE: HTTP cookies may also be accessed via the "Set-Cookie" HTTP request header value using HTTP request headers as attributes. Using HTTP cookies as attribute provides the convenience of separately parsed cookie name/value pairs as Cams attributes.

Cams HTTP cookie attribute names are normalized to lower case and belong to the "urn:cams:1.0:names:environment:http-cookie" category.

urn:cams:1.0:names:action:http-cookie:name
Description: An example HTTP cookie made available by Cams as an environment attribute.
Category: urn:cams:1.0:names:attribute-category:environment
Data type: urn:cams:1.0:names:data-type:string
Examples:
  • urn:cams:1.0:names:environment:http-cookie:cams_sid_mycluster_system
  • urn:cams:1.0:names:environment:http-cookie:jsession
  • urn:cams:1.0:names:environment:http-cookie:my_app

Standard Cams Attribute Matching Functions

Cams provides an extensible set of functions that can be used in attr-match elements to control how attribute values are compared. The following matching functions are available:

  • urn:cams:1.0:names:function:regexp-string-match - match attribute values using a regular expression.
  • urn:cams:1.0:names:function:equals-string-match - case sensitively match an entire string attribute value.
  • urn:cams:1.0:names:function:equals-ignorecase-string-match - case insensitively match an entire string attribute value.
  • urn:cams:1.0:names:function:starts-with-string-match - case sensitively match a string attribute value that starts with a given string.
  • urn:cams:1.0:names:function:starts-with-ignorecase-string-match - case insensitively match a string attribute value that starts with a given string.
  • urn:cams:1.0:names:function:ends-with-string-match - case sensitively match a string attribute value that ends with a given string.
  • urn:cams:1.0:names:function:ends-with-ignorecase-string-match - case insensitively match a string attribute value that ends with a given string.
  • urn:cams:1.0:names:function:contains-string-match - case sensitively match a string attribute value that contains a given string.
  • urn:cams:1.0:names:function:contains-ignorecase-string-match - case insensitively match a string attribute value that contains a given string.

Please contact Cafésoft if support of any of the following attribute functions are needed:

  • urn:cams:1.0:names:function:integer-equal
  • urn:cams:1.0:names:function:integer-not-equal
  • urn:cams:1.0:names:function:integer-greater-than
  • urn:cams:1.0:names:function:integer-greater-than-or-equal
  • urn:cams:1.0:names:function:integer-less-than
  • urn:cams:1.0:names:function:integer-less-than-or-equal
  • urn:cams:1.0:names:function:integer-match
  • urn:cams:1.0:names:function:double-equal
  • urn:cams:1.0:names:function:double-not-equal
  • urn:cams:1.0:names:function:double-greater-than
  • urn:cams:1.0:names:function:double-greater-than-or-equal
  • urn:cams:1.0:names:function:double-less-than
  • urn:cams:1.0:names:function:double-less-than-or-equal
  • urn:cams:1.0:names:function:boolean-equal
  • urn:cams:1.0:names:function:date-equal
  • urn:cams:1.0:names:function:time-equal
  • urn:cams:1.0:names:function:date-time-equal
  • urn:cams:1.0:names:function:any-uri-equal
  • urn:cams:1.0:names:function:x500-name-equal
  • urn:cams:1.0:names:function:rfc822-name-equal
  • urn:cams:1.0:names:function:hex-binary-equal
  • urn:cams:1.0:names:function:base64-binary-equal

Obligations Access Control Rule

An access control rule that associates possible Cams web agent obligations with an access control policy evaluation. For example, you might create an access control rule that would obligate the Cams web agent to send an HTTP redirect to the client's browser (you can also include dynamic query parameters in the redirect). Obligations provide a convenient way to route an access check request based on an access control policy.

<obligations-acr>

Creates an obligations access control rule. If an obligations access control rule is evaluated and the result matches, the specified obligations are added to the access control policy evaluation state. When the final access control decision is made, those obligations that have been added to the response state are matched to determine if they apply to the access control rule result. Those that match are returned to the Cams web agent, which attempts to fulfill the specified obligations.

NOTE: Because Cams web agents do not have a way to determine which of two competing obligations will be fulfilled, they will return an error if this condition is detected. For example, if two obligations for an HTTP redirect at sent, the Cams web agent cannot determine which one to try to fulifill and an error will result. When using obligations, be careful to construct an access control policy that cannot return more than one of the same obligation type (e.g. obligation id).

Item Description
Syntax
<obligations-acr
  id="access control rule identifier"
  debug="true|false">
  <acr-ref id="access control rule id"/>
  ...
</obligations-acr>
Attributes
id Required

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 Optional Activate debug for this access control rule (true or false).
Child Elements
<acr-ref> Required

1

<obligations> Required 1
Example
<!-- By default, Cams would redirect to the configured accessed denied
     page if an authenticated user is not granted access to a resource.
     This example shows how multiple rules are used with an obligation
     to prompt a Cams AUTOLOGIN authenticated user for PASSWORD
     authentication instead. -->

<!-- Require a user to be authenticated (regardless of roles) with the 
"PASSWORD" authentication method -->

<acr id="authenticated user with password authentication method rule">
<auth-acr> </auth-acr>
<and/>
<auth-method-acr method="urn:oasis:names:tc:SAML:1.0:am:password"/>
</acr> <!-- Require a user to be authenticated with the password method --> <obligations-acr id="obligate authenticated user with password authentication method rule" debug="false"> <!-- Invoke the rule that checks for the authentication method --> <acr-ref id="authenticated user with password authentication method"/> <!-- Candidate obligations --> <obligations> <!-- If access is denied because the authentication method is insufficient, then redirect to the login page --> <obligation id="urn:cams:1.0:names:obligation:http:redirect">
      <!-- Add this obligation to response only if the nested rule evaluates to
           false -->
      <eval-result-matches>
        <eval-result-match
          return-value="false"
          reason="any"/>
      </eval-result-matches>
      <!-- Send this obligation to the Cams web agent only if overall policy
           evaluates to denied and the reason is an insufficient authentication
           method -->
      <effect-matches>
        <effect-match
          status="denied"
          reason="access_denied_insufficient_auth_method"/>
      </effect-matches>
      <!-- Parameters for the http-redirect -->
      <attr-assignments>

        <!-- The URL for the redirect -->
        <attr-assignment
          id="urn:cams:1.0:names:obligation:http:url">
          <attr-value
            data-type="urn:cams:1.0:names:data-type:string">
            /cams/login.jsp?cams_security_domain=system&amp;cams_login_config=http
          </attr-value>
        </attr-assignment>

        <!-- Encode the URL -->
        <attr-assignment
          id="urn:cams:1.0:names:obligation:http:encode-orig-url-param">
          <attr-value
            data-type="urn:cams:1.0:names:data-type:boolean">
            true
          </attr-value>
        </attr-assignment>

        <!-- Append the URL the user was originally attempting to access
             as a query parameter with the specified name -->
        <attr-assignment
          id="urn:cams:1.0:names:obligation:http:orig-url-param-name">
          <attr-value
            data-type="urn:cams:1.0:names:data-type:string">
            cams_original_url
          </attr-value>
        </attr-assignment>

      </attr-assignments>

    </obligation>

  </obligations>

</obligations-acr>

<obligations>

A container for a sequence of obligation instances.

Item Description
Syntax
<obligations>
  ...
</obligations>
Attributes None
Child Elements
<obligation> Optional 0 ... N
Example See obligations-acr example

<obligation>

A single obligation.

Item Description
Syntax
<obligation id="Cams obligation URI"> ...
</obligation>
Attributes
id Required

URI for this obligation. The available options are:

HTTP Redirect:

  • urn:cams:1.0:names:obligation:http:redirect

NOTE: Contact Cafésoft if addition obligations are required for setting cookies, HTTP request headers, etc.

Child Elements
<eval-result-matches> Required 1
<effect-matches> Required 1
<attr-assignments> Optional 0 or 1
Example See obligations-acr example

<eval-result-matches>

An element that contains a list of eval-result-match elements, which are matched using the logical OR Boolean operator against the return value of an obligation's nested access control rule.

Item Description
Syntax
<eval-result-matches>
  ...
</eval-result-matches>
Attributes None
Child Elements
<eval-result-match> Optional 0 ... N
Example See obligations-acr example

<eval-result-match>

An element used to match the return value of the access control rule evaluation associated with the obligation. If the corresponding return value and reason match the evaluation, then the enclosing obligation will be returned to the Cams web agent.

Item Description
Syntax
<eval-result-match
  return-value="return value"
  reason="reason name"/>
Attributes
return-value Required

Specifies the return value to match. An access control rule evaluation always returns one of the following values, which you must specify:

  • true
  • false
  • true_or_false
  • evaluation_exception
reason Optional

The access control rule evaluation reason message. The default value any is used if no value is specified. Possible values are:

  • any
  • not_applicable
  • general_server_error
  • invalid_remote_ip_address
  • invalid_remote_host_name
  • unauthorized_agent
  • unknown_security_domain
  • unknown_resource_type
  • invalid_resource_identifier
  • unknown_resource_action
  • access_denied_unconditionally
  • access_denied_authentication_required
  • access_denied_session_expired
  • access_denied_evaluation_error
  • access_denied_confidentiality_required
  • session_id_invalid
  • default_bias_applied
  • unknown_login_config
  • general_transport_error
  • access_granted_conditionally
  • access_granted_unconditionally
  • access_denied_conditionally
  • access_denied_missing_required_attributes
  • access_denied_insufficient_auth_method

For more information, please see the Cams Administrator's Guide - Access Control Responses.

Child Elements None
Example See obligations-acr example

<effect-matches>

An element that contains a list of effect-match elements, which are matched using the logical OR Boolean operator against the overall access control rule evaluation.

Item Description
Syntax
<effect-matches>
  ...
</effect-matches>
Attributes None
Child Elements
<effect-match> Optional 0 ... N
Example See obligations-acr example

<effect-match>

An element used to match the effect (or overall result) of a Cams access check request. It is possible to reference multiple obligation access control rules in the same access control evaluation or to reference an obligation from within another access control rule. Because of this, the effect match provides controls to determine if the enclosing obligation will be returned to the Cams web agent based based on the overall access control evaluation result (e.g. NOT just the specified acr-ref nested within the obligation itself). If the corresponding status and reason match the effect, then the obligation will be returned to the Cams web agent.

Item Description
Syntax
<effect-match
  status="status"
  reason="reason name"/>
Attributes
status Required

An access control evaluation will always result in a granted or denied result, except if a timeout value is exceed in which case the result can be pending. The valid status values are:

  • any
  • granted
  • denied
  • pending
reason Required

The access control rule evaluation reason message. The default value any is used if no value is specified. Possible values are:

  • any
  • not_applicable
  • general_server_error
  • invalid_remote_ip_address
  • invalid_remote_host_name
  • unauthorized_agent
  • unknown_security_domain
  • unknown_resource_type
  • invalid_resource_identifier
  • unknown_resource_action
  • access_denied_unconditionally
  • access_denied_authentication_required
  • access_denied_session_expired
  • access_denied_evaluation_error
  • access_denied_confidentiality_required
  • session_id_invalid
  • default_bias_applied
  • unknown_login_config
  • general_transport_error
  • access_granted_conditionally
  • access_granted_unconditionally
  • access_denied_conditionally
  • access_denied_missing_required_attributes
  • access_denied_insufficient_auth_method

For more information, please see the Cams Administrator's Guide - Access Control Responses.

Child Elements None
Example See obligations-acr example

<attr-assignments>

A container for a sequence of attribute assignments, which are used to convey obligation-specific parameters to a Cams web agent.

Item Description
Syntax
<attr-assignments>
  ...
</attr-assignments>
Attributes None
Child Elements
<attr-assignment> Optional 0 ... N
Example See obligations-acr example

<attr-assignment>

Specifies an individual obligation action.

Item Description
Syntax
<attr-assignment id="Cams obligation assignment identifier URI">
  ...
</attr-assignment>
Attributes
id Required The Standard Cams Obligation Assignment Identifier for the attribute assignment.
Child Elements
<attr-value> Required 1
Example See obligations-acr example

<attr-value>

Specifies the value associated with an attribute assignment.

Item Description
Syntax
<attr-value data-type="Cams attribute data type URI">
  attribute value
</attr-value>
Attributes
data-type Required The Standard Cams Attribute Data Type for the attribute value.
Data

The relevant attribute value

NOTE: Certain characters commonly included in some values such as a URL can cause problems for the XML parser Cams uses. Make sure you encode characters to avoid issues. For example, an ampersand should be expressed as "&amp;".

Child Elements None
Example See obligations-acr example

Standard Cams Obligation Assignment Identifiers

Cams Obligation Assignment Identifiers are referenced to compose the obligations returned to Cams web agents. Standard Cams Obligation Assignment Identifiers include:

urn:cams:1.0:names:obligation:http:url
  • Category: urn:cams:1.0:names:obligation:http
  • Data Type: urn:cams:1.0:names:data-type:string
  • Description: The string representation of a relative or fully qualified URL including query parameters to use for an HTTP redirect
  • Examples: /cams/login.jsp?cams_security_domain=system&amp;cams_login_config=http
urn:cams:1.0:names:obligation:http:encode-orig-url-param
  • Category: urn:cams:1.0:names:obligation:http
  • Data Type: urn:cams:1.0:names:data-type:boolean
  • Description: Encode the originally requested URL and append it as a query parameter to the redirect URL
  • Examples: true
urn:cams:1.0:names:obligation:http:orig-url-param-name
  • Category: urn:cams:1.0:names:obligation:http
  • Data Type: urn:cams:1.0:names:data-type:string
  • Description: The name of the original URL query parameter to use
  • Examples: cams_original_url

NOTE: Please contact Cafésoft if you require additional Cams Obligation Assignment Identifiers.

SQL Data Access Control Rule

You can use SQL data access control rules to ensure the existance or completeness of required SQL database values (constraints). For example, you might have a requirement to ensure that a user subcription is still valid to grant access to downloads. In this case, a user specific subcription date field might be defined in a database table that the SQL data access control rule can query to determine if it is in range.

<sql-data-acr>

Creates an SQL data access control rule, which may be used to enforce access to protected resources using an SQL data constraints. The SQL data constraints are evaluated and access is granted if all are fulfilled. Optional data parameters may be supplied for evaluation, which can be referenced from other SQL statements. This provides flexible support for context-sensitive SQL statements based on user identity and other request-specific values.

Item Description
Syntax
<sql-data-acr
  id="access control rule identifier"
  debug="true|false">
  ...
</sql-data-acr> 
Attributes
id Required Uniquely identifies this rule so it can be referenced from permissions and other access control rule expressions.
debug Optional Activate debug for this access control rule (true or false).
Child Elements
<sql-data-source> Required 1
<sql-data-param-sets> Optional 0 or 1
<sql-data-constraints> Required 1
<session-cache-config> Required 1
Example
<!-- Require a value for COMPANY column from a user database table
to grant access an authenticated user. WARNING: A JDBC connection pool must be configured in the corresponding security-domain.xml and a database with the correct tables and fields must exist for this example to work correctly. See the Cams Administrator's Guide - Security Domain Configuration - JDBC Connection Pool Service. -->
<sql-data-acr
id="completed company rule"
debug="false">

<!-- Configure the JDBC data source using a Cams connection pool -->
<sql-data-source
driver="org.apache.commons.dbcp.PoolingDriver"
url="jdbc:apache:commons:dbcp:example-jdbc-pool"
username=""
password=""/> <!-- Use the intrinsic #subject:username# value in a query to lookup the USER_ID, and make that available for use as #customer:userid#. -->
<sql-data-param-sets>
<sql-data-param-set namespace="customer" desc="Customer Parameters">
select USER_ID as userid
from USER_ACCOUNTS
where USER_NAME = '#subject:username#'
</sql-data-param-set>
</sql-data-param-sets> <!-- Use the #customer:userid# variable to build a query that determines if the value in the COMPANY field is populated -->
<sql-data-constraints>
<sql-data-constraint desc="Require Basic CUSTOMER fields">
select COUNT(*)
from USER_PROFILES c1
where c1.USER_ID = '#customer:userid#'
and LENGTH(c1.ORG) &gt; 0
</sql-data-constraint>
</sql-data-constraints> <!-- Define session caching parameters -->
<session-cache-config
enabled="true"
attr-namespace="user"
attr-name="company"
attr-value="true"/> </sql-data-acr>

<sql-data-source>

The Java JDBC configuration parameters to use for the data source, which is usually an SQL database such as Oracle, DB2, Microsoft SQL, MySQL, Sybase, etc., but can be virtually any other data source with a JDBC driver. You can also configure and use a Cams JDBC connection pooling service, which is recommended to minimize data source connection overhead and improve access control evaluation performance.

NOTE: If you need to use a JDBC driver other than the JDBC to ODBC bridge that ships with the J2SDK, you must supply and install the driver. To use the JDBC driver with Cams, copy the driver's jar file into the CAMS_HOME/cams/lib directory. You can alternatively copy the driver to the ext directory of your J2SDK installation. For example, if you want to use MySQL with the standard J2SDK installation, you would copy mysql-connector-java-3.0.15-ga-bin.jar to JAVA_HOME/jre/lib/ext.

Item Description
Syntax
<sql-data-source
  driver="fully.qualified.JavaClassName"
url="jdbc driver URL"
username="data source user name"
password="data source password"/>
Attributes
driver Required The fully qualified Java class name of the JDBC driver for your data source.
url Required The JDBC URL required to access the data source (see the JDBC driver documentation).
username Required The username to access the data source.
password Required The password to access the data source.
Child Elements None
Example See sql-data-acr example

<sql-data-param-sets>

A container for zero or more sql-data-param-set elements.

Item Description
Syntax
<sql-data-param-sets>
...
</sql-data-param-sets>
Attributes None
Child Elements
<sql-data-param-set> Optional 0 ... N
Example See sql-data-acr example

<sql-data-param-set>

A set of parameters populated when the enclosing access control rule is evaluated that can be referenced from SQL statements. All result set values returned from the enclosed SQL statement are are assigned to a namespace and can be referenced from sql-data-constraint queries.

Item Description
Syntax
<sql-data-param-set
  namespace="textual name"
  desc="textual description">
...
</sql-data-param-set>
Attributes
namespace Required The namespace to use to save the name/value pairs returned from an SQL query.
desc Required A description for this sql-data-param-set.
Data

An SQL query that will return a result set of name/value pairs that will be saved in the specified namespace for use in sql-data-constraints. You can embed tokens of the form #namespace:name# to make your SQL queries dynamic. The following values are available for use:

  • #subject:username# - The user name of the authenticated user
  • #http-param:[name]# - Any value submitted with an HTTP request as a query parameter (where [name] is the name of the query parameter)
Child Elements None
Example See sql-data-acr example

<sql-data-constraints>

A container for zero or more sql-data-constraint elements.

Item Description
Syntax
<sql-data-constraints>
...
</sql-data-constraints>
Attributes None
Child Elements
<sql-data-constraint> Optional 0 ... N
Example See sql-data-acr example

<sql-data-constraint>

An element containing an SQL select or update query that must return an integer value. A value greater than zero indicates a success condition. A null, empty or zero value indicates a failure condition. Any number of sql-data-constraints can be used. An implicit AND operator applies between statements. All sql-data-constraints in the set must evaluate successfully for this rule to return a grant response. Any failure condition will force a deny response.

Item Description
Syntax
<sql-data-constraint desc="textual description">
...
</sql-data-constraint>
Attributes
desc Required A description for this sql-data-constraint
Data

An SQL select or update query that returns an integer. You should construct SQL SELECT statements such that use of the SQL COUNT(*) function will return either a 0 (fail) or 1 (success). SQL update statements automatically return 0 (fail) or the number of rows that updated (success). You can embed tokens of the form #namespace:name# to make your SQL queries dynamic. The following values are available for use:

  • #subject:username# - The user name of the authenticated user
  • #http-param:[name]# - Any value submitted with an HTTP request as a query parameter (where [name] is the name of the query parameter value)
  • #[namespace]:[name] - Any sql-data-param-set value you have specified that evaluated successfully
Child Elements None
Example See sql-data-acr example

<session-cache-config>

An element that configures caching of granted access control decisions in the user's Cams session.

Item Description
Syntax
<SQL-data-constraint desc="textual description">
...
</SQL-data-constraint>
Attributes
enabled Required Activate the SQL data constraint session cache (true or false).
attr-namespace Required The namespace to use to save the name/value pairs in the user session.
attr-name Required The name to use for this value.
attr-value Required The value to save and compare (usually true).
Child Elements None
Example See sql-data-acr example

Custom Access Control Rule

The Cams Access Control Rules API enables you to implement custom access control rules based on date, time, business rules, user profile information, database values and more. Creating custom access control rules facilitates their centralization, security and reuse across enterprise resources. This section documents two example rules that are included with the standard Cams policy server distribution. For more information on how to create custom access control rules, see the Cams Programmer's Guide - Cams Access Control Rules.

NOTE: The format for this section is slightly different to avoid redundancy. The attributes that are user configurable are in red and are the only attributes presented. All other attributes should be used as shown unless you desire to relocate DTDs, customize Java code, etc. Please reference the acr-type section of this document for more information on additional configuration options.

<example:business-hours-acr>

This example implements an access control rule that evaluates based on the business days (Monday through Friday) and the time of the day. You need only declare the acr-type element and enclosed values once within the access control rules library. You can, however, declare multiple instances of the business-hours-acr with different attribute values for each instance.

Item Description
Syntax
<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>

<example:business-hours-acr
  xmlns:example="http://cafesoft.com/example-business-hours-acr_1_0.dtd"
  id="textual value"
  desc="textual value">
  <example:business-hours start-hour="start hour" end-hour="end hour"/>
</example:business-hours-acr>
Attributes/
Elements
id Required

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.

desc Optional A textual description of the access control rule type.
start hour Required The start of the business day where the clock hours are 0 to 23.
end hour Required The end of the business day where the clock hours are 0 to 23.
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>

<example:user-attribute-acr>

Demonstrates a custom Cams access control rule that only grants access to a resource to users with
specified user attributes. The user attribute is fetched from a Cams user session. You need only declare the acr-type element and enclosed values once within the access control rules library. You can, however, declare multiple instances of the user-attribute-acr with different attribute values for each instance.

Item Description
Syntax
<acr-type
  name="example:user-attribute-acr"
  className="examples.acrs.UserAttributeAcr"
  desc="Control access by user session attributes">

  <acr-persistence-manager className="examples.acrs.XmlUserAttributeAcrPm"/>
</acr-type>

<example:user-attribute-acr
  xmlns:example="http://cafesoft.com/example-user-attribute-acr_1_0.dtd"
  id="textual value"
  desc="textual value">

  <example:user-attribute
name="value to grant"
session-attr-namespace="session namespace for value"
session-attr-name="session namespace name for value"/> </example:user-attribute-acr>

Attributes/
Elements

id Required

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.

desc Optional A textual description of the access control rule type.
name Required The user attribute value for which
access will be granted.
session-attr-namespace Required The user session namespace in which the attribute is stored.
session-attr-name Required The name in the user session namespace in which the attribute is stored.
Example
<!-- Declare a custom Access Control Rule type for limiting
     access by user account type -->
<acr-type
  name="example:user-attribute-acr"
  className="examples.acrs.UserAttributeAcr"
  desc="Control access by user session attributes">

  <acr-persistence-manager className="examples.acrs.XmlUserAttributeAcrPm"/>
</acr-type>

<!-- Create an Access Control Rule for limiting access
     by user account type -->
<example:user-attribute-acr
  xmlns:example="http://cafesoft.com/example-user-attribute-acr_1_0.dtd"
  id="account type rule"
  desc="Limit access to user's with a gold account">

  <example:user-attribute
name="gold"
session-attr-namespace="userinfo"
session-attr-name="account_type"/> </example:user-attribute-acr>

Back | Next | Contents