Access Control Services

This document details how Cams access control services work and how to configure them. Instructions are provided for configuring a security domain's access control policy, which is found in the access-control-policy.xml file of each security domain. See also the Access Control Policy Tag Reference for a complete reference on all XML tags used in the access-control-policy.xml file.

Access Control Conceptual Model

The Cams access control model defines two major responsibilities:

• Policy Enforcement Point - A location in the system where a security policy is enforced. For Cams, this is usually a Cams web agent installed in a resource provider like Apache or Tomcat, but may also be a custom agent embedded in an application, etc.
• Policy Decision Point - A location in the system where the access control decisions are made. For Cams, this is always the Cams policy server.

To implement access control on a client's request, the policy enforcement point asks the policy decision point whether to grant or deny access to a resource. If the policy decision point grants access, then the policy enforcement point allows access to the resource. If the policy decision point denies access, then the policy enforcement point will not allow access to the resource. Figure 1 shows these abstract access control roles.

Figure 1 - The Cams centralized access control model

Figure 2 shows a deployment where the resource provider is a web server, the resources are web pages, CGI scripts, and other URL resources accessible via the server. The policy enforcement point is a Cams web agent and the policy decision point is the Cams policy server. The web browser requests access to an HTTP URL from a web server, where a web server agent intercepts the request and asks the Cams policy server if access is granted or denied. The Cams policy server decides whether or not access is granted and the agent enforces the decision.

Figure 2 - Example: Web resources access control model

Cams Security Domains

Cams partitions access control, authentication and session management responsibilities into security domains. Security domains enable a separation of administrative responsibilities based on organizational boundaries. Each security domain has an access control service that uses an access control policy that contains permissions for accessing protected resources. Each permission:

• is associated with a type of resource that it protects (e.g. http or cams)
• contains a pattern for matching resource identifier(s) (e.g. http://www.cafesoft.com:80/secure*)
• may specify one or more actions (e.g. GET, POST, PUT, etc.)
• references an access control rule that protects access to matching resources or a security domain to which access control will be delegated (e.g. "acr-ref id=granted")

Permissions are organized into separate permission collections (based on type) and access control rules are stored in an access control rule library, which enables them to be re-used, managed and referenced from permissions and other access control rules. Figure 3 shows the relationships between these major access control components.

Figure 3 - Relationships between major Cams access control components

How Cams Access Control Works

When a Cams web agent needs to check access to a resource, it submits a resource request to a Cams policy server. The Cams policy server gives the request to the access control service within a special system security domain, which either handles it or delegates the request to another security domain as configured in it's access control policy. So, in order for a resource to be protected by Cams, a permission that matches its identifier and action must be configured in the Cams system security domain.

Access control decisions are based on a resource request, which is sent from a Cams web agent as part of an access control check request. Each resource request includes a resource type, a unique resource identifier and one or more requested actions. For example, an attempt to access a web page via a web browser might correspond to the following Cams resource request parameters:

1. Resource type: http
2. Resource id: http://www.cafesoft.com:80/index.html
3. Action: GET

The enclosing access control check request contains other parameters that may be important for deciding whether to grant or deny access including:

• the identity of a user (if the user is authenticated)
• the remote host on which the user is operating
• the confidentiality of the network connection by which a resource might be accessed
• the type(s) of authentication successfully passed by the user
• the date/time of the request
• any HTTP query parameters optionally sent with a request
• Cams web agent attributes optionally sent with a request
• the fulfillment of an SQL query
  

When the Cams high-level access control service receives this request, the following actions are taken:

1. A Cams web agent, usually installed at a resource provider, will connect with the Cams policy server and send an access control request (hereafter refered to as the request).
2. The request and its enclosed resource request are given to the Cams access control service.
   
3. The access control service gives the request to the system security domain's access control service
   
4. The system security domain's access control service passes the request to it's access control pipeline, which contains a series of access control valves
5. Each access control valve can: ignore the request, partially handle the request or completely handle the request.
6. By default, an access control valve will log the request
7. By default, a Cams basic access control valve will invoke the security domain's access control policy
8. The access control policy will find the permission collection that matches the resource type
9. The permission collection will find the permission that best matches the resource request. The rules for best match can depend on the resource type and is explained in detail below.
10. If the permission references an access control rule, that rule will be invoked on the request. If the permission references another security domain, the request will be forwarded to that security domain.
11. The invoked access control rule will evaluate the request, possibly invoking other nested access control rules. An access control response will be populated and returned to the Cams web agent.

This entire processing pipeline is completely pre-loaded and memory-resident, so it's very fast. The design enables pluggable support for new resource types, new access control rule types and pluggable access control valves. The Cams policy server engine is thread-safe and can be used stand-alone or embedded within applications.

In order for a permission to match a specific resource request, the following criteria must be met:

• the id of the requested resource must match the permission's resource pattern
• the action on the requested resource must match one or more of the permission's actions

To understand permission matching rules, consider the example access control policy represented within Example 1.

Example 1 - Example permissions within an access control policy

Each row represents a permission to access some HTTP (web) resources.

• for request: GET http://www.foo.com/secure/index.html, only permission 1 matches.
• for request: POST http://www.foo.com/secure/employee/suggestion permissions 1 and 2 match the request, but 2 is more specific so it takes precedence. In this case more specific means that permission 1's resource pattern is longer than permission 2's resource pattern. The request does not match permission 3 because the requested POST action is not associated with permission 3.
• for request: DELETE http://www.foo.com/secure/employee/picnic_2002.html only permission 3 matches because it's the only one that matches the resource pattern and the DELETE action.

Permission 4 is incompatible with permission 2 because both have identical resource patterns and a matching action. Cams requires unambiguous rules for assigning access control responsibility within a security domain, so it will not allow insertion of a permission that overlaps another permission. Permissions are considered overlapping if they have the same type, have identical resource patterns and have at least one action in common. Without this precaution, Cams would not be able to decide which of the two permissions has responsibility for protecting a matching resource request. If an access control policy contains an overlapping permission during initial access control policy loading, the access control policy will fail to load and the enclosing security domain will not be started.

Finally, if the access controller does not find a matching permission, then access will be either granted or denied based on the default bias you set for the access control policy.

Managing a Cams Access Control Policy

Cams stores each security domain's access control policy in an XML file named access-control-policy.xml. An access control policy is configured by editing this file, which is loaded when the Cams policy server is started and automatically reloaded if the access-control-policy.xml file is modified at runtime. More information on the service that triggers reloading of the access-control-policy.xml file for each Cams security domain is available in The Access Control Policy Monitor Service.

NOTE: If you must make configuration changes to an access control policy that will be deployed in a production environment, it is recommended that you test the access control policy in a development or test/QA environment first.

The following procedure is recommended for managing an access-control-policy.xml file.

Step 1 - Make a backup copy of the current access-control-policy.xml file

Copy the existing access-control-policy.xml file to a file named: access-control-policy.xml.<lastModifiedTime>, where lastModifiedTime is the value of the attribute shown in the first XML element of Example 1.

For example: access-control-policy.xml.200503231200

This will provide you a way to roll back to a known access control policy if the changes you make will not load or don't behave as desired.

Step 2 - Edit and save the access-control-policy.xml file

Edit the access-control-policy.xml file as described in Configuring a Cams Access Control Policy.

NOTE: You must update the value of the lastModifiedTime attribute in the <access-control-policy> using the date/time format: YYYYMMDDHHmm. If the Cams policy server is already running, this value must be greater than the lastModifiedTime date/time stamp in the previously loaded access control policy or automatic reloading will fail. The lastModifiedTime value is important for ensuring that all Cams policy servers in a cluster use the same access control policy. It is also important for Cams web agents, which are required to clear cached access control responses when an access control policy is modified.

Step 3 - Start the Cams policy server or wait for access-control-policy.xml to reload

If the Cams policy server is not running, start it. The security domain's access control service attempts to load the access-control-policy.xml file on startup. If the access control policy has an error, it is reported to the security domain's trace log and the security domain will fail to load. If the security domain is the required system security domain, the Cams policy server will not start.

If the Cams policy server is already running and automatic access control policy reloading is enabled, the access control service will attempt to reload access-control-policy.xml when the file date/time changes. If the access-control-policy.xml's lastModifiedTime date/time has not been increased relative to the currently loaded access control policy or a valadation error occurs, then the reload will fail and the existing access control policy will stay in effect. The access control service will not attempt to reload access-control-policy.xml again until the file date/time is modified because the access control policy monitor service knows that the file failed to load and would fail again.

You can confirm that the access control policy is loaded or reloaded by viewing the security domain trace log file. The access control policy lastModifiedTime date/time associated with a newly loaded access-control-policy.xml file is displayed.

Rolling Back to a Previous Access Control Policy

To help Cams agents efficiently cache access control responses and to avoid access control policy reloading failures due to an invalid lastModfied date/time, use the following file management procedure to roll back to a previous access control policy.

NOTE: For purposes of these instructions, let's assume that the access control policy that we'd like to roll back to is in file: access-control-policy.xml.200503231200.

1. Copy the access-control-policy.xml file saved in Step 1 above to a new file with the current lastModifiedTime date/time stamp. For example, if the current date/time is Mar 23, 2005 12:30 PM, copy: access-control-policy.xml.200503231200 to access-control-policy.xml.200503231230.
2. Edit and save access-control-policy.xml.200503231230 with the lastModifiedTime value set to 200503231230.
3. Copy access-control-policy.xml.200503231230 to access-control-policy.xml

Configuring a Cams Access Control Policy

This section shows an example Cams access-control-policy.xml file in to describe how you use this file to configure permissions and access control rules. Example 1 shows how an access control policy might be configured to protect some HTTP (web) resources available from a fictitious application server at http://www.acme.com that hosts:

• web pages to be made available only to authenticated employees
• servlets and/or web applications available only to authenticated managers
• web pages available to everybody

Each of these access control requirements can be expressed as a distinct permission within the access control policy's <permission collection> start and end tags. Custom access control rules are defined in the access control rules library within the <acr-lib> start and end tags. Please refer to the comments in Example 2 to understand more about each permission and its associated rule reference.

<!-- Declare an access control policy -->
<access-control-policy defaultBias="denied" lastModifiedTime="200503231200">
 
    <!-- HTTP (Web) resource permissions -->
    <permission-collection type="http" desc="HTTP (Web) Resources">

       <!-- Declare web pages available to all ACME employees -->
       <permission desc="ACME Employee Web Resources"> 
         <resource-pattern id="*://*:*/employee*" ignoreCase="false"/>
         <acr-ref id="ACME Employee Rule"/>
       </permission>
			
       <!-- Declare web pages available only to ACME manager users -->
       <permission desc="ACME Manager Web Resources"> 
         <resource-pattern id="*://*:*/manager*" ignoreCase="false"/>
         <acr-ref id="ACME Manager LAN-Auth-Conf Rule"/>
       </permission>
		
       <!-- Declare web pages available to the public -->
       <permission desc="ACME Public Web Resources" actions="GET"> 
         <resource-pattern id="*://*:*/*" ignoreCase="false"/>
         <acr-ref id="granted"/>
       </permission>

    </permission-collection>

    <!-- Access Control Rule Library -->
    <acr-lib> 

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

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

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

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

  </acr-lib>

</access-control-policy>

Example 2 - An example access control policy file

Configuring Permissions

Each Cams permission protects a specific type of resource (http or cams) and is enclosed within a permission collection specific for that type. For example, the system security domain's access control policy defines two permission collections: one for HTTP permissions and one for Cams system-level permissions. Although http and cams resources are both identified using a URL syntax, they are considered different resource types and therefore protected by permissions in different permission collections.

A Cams permission specifies the following elements:

1. A textual description helpful for administrators and debugging
2. An optional list of actions used to match one or more resources to be protected
3. A resource pattern formulated to match the fully-qualified identifier of one or more resources to be protected
4. A reference to an access control rule used to protect matching resources or a reference to another security domain to which the access control checks for matching resources will be delegated

The following sections provide more details on each of these elements.

Setting a Permission's Description

The textual description for a permission is useful for adminstration and debugging. Enter a unique value that describes the resources protected by the permission, as shown in Example 3.

<!-- Declare web pages available to all ACME employees -->
<permission desc="ACME Employee Web Resources"> 
 <resource-pattern id="*://*:*/employee*" ignoreCase="false"/>
 <acr-ref id="ACME Employee Rule"/>
</permission>

Example 3 - Setting a permission's description in access-control-policy.xml

Setting a Permission's Actions

A permission's actions are used when selecting which permission will apply to an access control request. An access control request will specify zero or more actions and a resource identifier. If all of the actions specified by the access control request match actions specified by a permission, then that permission is a candidate for handling the request. Example 4 shows how a permission's actions may be set in access-control-policy.xml.

<!-- Declare web pages available to all ACME employees -->
<permission desc="ACME Employee Web Resources" actions="GET,POST"> 
 <resource-pattern id="*://*:*/employee*" ignoreCase="false"/>
 <acr-ref id="ACME Employee Rule"/>
</permission>

Example 4 - Setting a permission's actions in access-control-policy.xml

NOTE: The permission's resource pattern will also need to match the access control request's resource identifier to remain a candidate.

Example 5 shows how the actions specified within an access control request match actions defined for hypothetical http permissions.

Example 5 - Matching access control request actions against permission actions

Cases 2 and 5 shows that only a subset of a permission's actions must match the access control request's actions. Case 4 shows that when no actions are specified for a permission, then all actions are implied. Case 5 shows that the order of actions is not significant. Case 6 shows that actions are case-sensitive. In fact, the access control policy containing this invalid action would fail to load and an exception would be reported in the enclosing security domain's trace log.

Configuring Resource Patterns

A permission's resource pattern is used to match the resource identifier specified within an access control request. The recommended practice is to make a resource pattern just general enough to match all the resources that must be protected by the same access control rule (or delegated to the same security domain). This enables you to minimize the number of permissions needed by your access control policy. Remember, simplicity is golden when security is involved. Example 6 shows how a permission's resource pattern may be set in access-control-policy.xml.

<!-- Declare web pages available to all ACME employees -->
<permission desc="ACME Employee Web Resources" actions="GET,POST"> 
 <resource-pattern id="*://*:*/employee*" ignoreCase="false"/>
 <acr-ref id="ACME Employee Rule"/>
</permission>

Example 6 - Setting a permission's resource pattern in access-control-policy.xml

WARNING: Some web servers and their underlying operating systems (most notably IIS on Windows) provide case-insensitive access to resources. Because Cams access control policy evaluations are case sensitive by default, it is easy to create an access control policy security hole on case-insensitive servers. To prevent this, a resource-pattern XML element ignoreCase="true|false" is available. If not specified, the default behaviour is false, resulting in case-sensitive URI pattern matching.

Example Resource Patterns

Example 7 shows some sample resource patterns for http and cams resource types. For purposes of matching, these URL-based resource patterns are divided by Cams into four distinct fields:

• scheme - resource type, currently either http or cams
• host - IP address or DNS hostname for the server where the resource is located
• port - the porter number of the server for the resource
• URI - the path on the server to the resource

Each field within the overall resource pattern may be customized independently to make it as specific or as general as needed.

NOTE: You should keep the scheme, host and port as general as possible (usually *://*:*). This facilitates moving access-control-policy.xml between development, test/QA and production systems. Use of scheme, host and port is most useful in situations where HTTP and HTTPS resources need different permissions, or you have multiple web or application servers with distinct security requirements (especially if you delegate to another security domain).

Example 7 - Sample Resource Patterns for http and cams resource types

For HTTP URL-based resource patterns, the best matching pattern is based on URI first, port second, host third and scheme last. Cams implements resource pattern scoring based on field weighting and field pattern specificity to ensure that more specific patterns are matched.

Legal and Illegal URL-based Resource Patterns

URL-based resource patterns, like those for http and cams resource types include alot of flexibility and some limitations. In particular, use of the wildcard character '*' is supported only certain contexts, which helps maximize performance and simplify the rules for best permission matching. In addition, the meaning of '*' depends on the part of the URL pattern in which it is used.

Cams URL-based resource patterns have the following general form:

shemePattern :// hostPattern : portPattern / uriPattern

As you can see, the overall resource pattern is composed of four sub-patterns, each of which has its own validation rules. Example 8 summarizes the legal and illegal URL-based resource patterns for the http resource type. Rules for URL-based cams resource patterns are similar.

Example 8 - URL resource pattern examples for HTTP resources

NOTE: Most web servers resolve multiple juxtaposed slashes in a URI to a single slash. For example:

http://www.mycompany.com/mysecure//resource.html

would resolve to:

http://www.mycompany.com/mysecure/resource.html

Because Cams does resource pattern matching on a character by character basis, this situation creates a potential access control policy security hole. To prevent this from happening, Cams automatically reduces two or more juxtaposed slashes in the URI to one (this does not apply to the expected double slash between the scheme and the host name).

Linking a Permission to an Access Control Rule

Example 9 shows how the access control rule associated with a permission may be set in access-control-policy.xml. The identified access control rule instance must be defined within the access control policy's access control rule library.

<!-- Declare web pages available to all ACME employees -->
<permission desc="ACME Employee Web Resources" actions="GET,POST"> 
 <resource-pattern id="http://www.acme.com:80/employee*" ignoreCase="false"/>
 <acr-ref id="ACME Employee Rule"/>
</permission>

Example 9 - Setting the access control rule for a permission within access-control-policy.xml

Delegating a Permission to another Security Domain

Example 10 shows how a permission can be delegated to another security domain. The destination security domain becomes the owner of the resources matching the associated resource pattern(s). It is up to the access control policy in the destination security domain to define permissions as required to protect the associated resources.

NOTE: The system security domain's access control policy receives EVERY access control request. In order for any other security domain's access control policy to handle an access control requests, the system security domain's access control policy must delegate permissions.

<!-- Delegate http permissions for "www.foo.com" -->
<permission desc="Delegate web permissions for www.foo.com"> 
 <resource-pattern id="*://www.foo.com:*/*" ignoreCase="false"/>
 <owner id="mydomain"/>
</permission>

Example 10 - Delegating a permission (assigning ownership of resources) within access-control-policy.xml

Debugging Permissions

Permissions may be debugged by setting a debug flag and viewing the contents of the security domain-specific trace log. For example, if a permission is contained within the access control policy of the mydomain security domain, its trace log (by default), is in file CAMS_HOME/logs/mydomain-trace.log.

Example 11 shows how the debug flag can be enabled for a permission. In general, you will also want to enable the debug flag on element <access-control-policy debug="true">, <permission-collection debug="true"> and possibly at the access control rule level.

<!-- Declare web pages available to all ACME employees -->
<permission desc="ACME Employee Web Resources" actions="GET,POST" debug="true"> 
 <resource-pattern id="http://www.acme.com:80/employee*" ignoreCase="false"/>
 <owner id="mydomain"/>
</permission>

Example 11 - Enabling debug within access-control-policy.xml

Configuring Access Control Rules

After any and all security domain delegations are performed, a single access control rule instance is evaluated to determine if an access control check request will be granted or denied. Some Cams access control rules, called intrinsic rules, are always present in all security domains and require no further definition. For example, the following intrinsic rules can be reference directly from any permission:

• granted -always grant access unconditionally
• denied - always deny access unconditionally
• confidential - grant access only if the connection is confidential (e.g. HTTPS)

Most access control rules must be defined for your site-specific requirements. You do this within the access control rule library using the syntax defined for each access control rule. For example, if you want to create a role-based access control rule that requires a user to have the employee role, you would define a rule similar to the one in Example 12.

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

Example 12 - Defining a role-based access control rule

The access control rule library is the second major block of XML in a security domain's access-control-policy.xml file (immediately following the permission collection XML block). Each access control rule must have a unique identifier, which permissions and other access control rules use to reference it. You can also nest many access control rules within other access control rules and can always combine access control rules using AND, OR and NOT operators to create new composite access control rules. Example 13 shows how.

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

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

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

Example 12 - Defining a composite access control rule

The composite ACME Manager LAN-Auth-Conf Rule is created by using the AND condition between two previously defined rule and the Cams confidential intrinsic rule. Notice that the two reference access control rules are defined first in the file, which is required.

The syntax for the Cams access control rules you can instance in a security domain's access control rule library is quite varied. You should reference the Access Control Policy Tag Reference document to learn more about the syntax required for each access control rule. Also, if the standard Cams access control rules are not sufficient for your site, programmers can implement custom access control rules that can be plugged into the Cams policy server.

Back | Next | Contents

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