[an error occurred while processing this directive]
Back | Next | Contents Cams Administrator's Guide

Troubleshooting Cams Access Control

The Cams access control system provides fine-grained information that can help you debug your security domains, access control policies, and access control rules. This document contains:

  • A summary of the Cams access control system structure, which will enable you to understand the context of configuration issues
  • Cams trace log file locations where you'll find DEBUG, INFO, WARNING, ERROR, and FATAL messages
  • How to enable Cams trace logs to include DEBUG-level messages
  • How to configure specific Cams access control components to issue DEBUG-level messages

The Cams Access Control System Structure

In order to effectively debug Cams access control issues, it's important to understand how the Cams access control system is organized. You'll be able to isolate the Cams components that you want to provide DEBUG-level messages so you can avoid generating too much data, which can make debugging more difficult.

Figure 1 shows the high-level, hierarchical structure of the Cams access control services.

Figure 1 - High-level structure of Cams access control services

Table 1 describes each of these components and their roles within the Cams architecture.

Component Description
Cams Access Control Message Service

Receives incoming access control requests from network agents and hands them to the system security domain, then returns the associated access control response. This service handles access-control requests for all configured Cams security domains and it's debug information is written to:

${cams.home}/logs/cams-server.log

Security Domain

Hosts a set of standard security services that are configured to manage a subset of an enterprise's overall security responsibilities. security domains essentially partition responsibility for managing users, authentication, and access control according to organizational, structural, or political boundaries. Each security domain has it's own trace log file, which is generally written to security domain-specific file name. security domains also have various transaction log files for authentication, access control, session management, session access, etc, but debug information is available in the trace log. By default, the "system" security domain's trace log is written to:

${cams.home}/logs/system-trace.log

DEBUG-level messages for all sub-components: access control service, access control pipeline, access control valve, access control policy, and access control rule are written to their security domain-specific trace logs.

Access Control Service
The service with a security domain responsible for implementing access control to resource protected by that security domain.
Access Control Pipeline

A component with a security domain's access control service that hosts a configureable set of "access control valves". This architecture implements a flexible "Chain of Responsibility" design pattern that enables logging, debugging, auditing, etc components to be plugged into a security domains's access control service.

When the access control pipeline receives a request, it is passed through it's sequence of access control valves. Each valve may handle the request, modify the request, and/or pass the request to the next valve. An internally-defined "Basic" access control valve is always the last one in the sequence and is usually the one that does the work of invoking the associated Cams access control policy.

Access Control Valve
A component within a security domain's access control pipeline that may handle the request, modify the request, and/or pass the request to the next valve.
Access Control Policy
Contains all of the access control permissions for resource protected within a security domain. Also contains all access control rule instances that may be invoked by permissions and access control rule type definitions if custom access control rules have been developed and plugged into Cams.
PermissionCollection

A permission collection is a homogeneous collection of permissions. For example, all http permissions are in the same permission collection and all cams permissions are in another permission pollection. Each permission associates a set of resources with an access control action. The action may either be:

  1. invoke an access control rule that will check access to the requested resource
  2. delegate the request to another Cams security domain
Access Control Rule Library
A Container for access control rule instances and access control rule type declarations.
Access Control Rule
In general an access control policy will contain many access control rules, which are used to decide whether or not access will be granted or denied to a protected resource. Cams comes with a number of standard access control rules for controlling access by: authenticated user role, network host, confidential (encrypted) network traffic, etc. Cams also includes a special access control rule that enables you to combine access control rules into logical expressions using "and", "or", and "not" operators.

Table 1 - Summary of Cams access control services/components

Enabling/Disabling Cams DEBUG-level Messages

To generate DEBUG-level messages for a particular Cams access control system component, you'll need to:

  1. enable DEBUG-level messages for the appropriate Cams Logger
  2. enable DEBUG messages for the desired Cams Service/Component

Configuring Loggers to Enable DEBUG-level Messages

Table 2 summarizes the configuration file locations for Cams trace loggers. In general, each security domain will configure it's own trace logger. See configuration file: ${cams.home}/domains/security-domain-registry.xml for the list of registered security domains and their configuration root directories.

Component Debug Configuration Properties
Cams Access Control Message Service

Configuration file: ${cams.home}/conf/cams.conf

Property: debug=true

Security Domain
Access Control Service
Access Control Pipeline
Access Control Valve
Access Control Policy
Permission Collection
Access Control Rule Library
Access Control Rule

Configuration file: security-domain.xml

Element:

<logger className="com.cafesoft.cams.log.CamsTraceLogger"
params="debug=true,logger.file.path=${cams.home}/logs/system-trace.log,logger.file.append=false"/>

 

Table 2 - Configuration parameters enabling/disabling Cams Logger DEBUG-level messages

Configuring Components to Enable DEBUG-level Messages

Table 3 summarizes the configuration properties for enabling/disabling component-level DEBUG messages.

Component Debug Configuration Properties
Cams Access Control Message Service

Configuration file: ${cams.home}/conf/cams.conf

Property: cams.service.access-control.debug=true

Security Domain

Configuration file: security-domain.xml

Element: <security-domain debug="true">

if the optional "debug" attributes is not present, the default is "false".

Access Control Service

Configuration file: security-domain.xml

Element:

<access-control-service
   className="com.cafesoft.security.engine.access.StandardAccessController"
   debug="true">

if the optional "debug" attributes is not present, the default is "false".

Access Control Pipeline

Configuration file: security-domain.xml

Element:

<access-control-pipeline
   className="com.cafesoft.security.engine.access.StandardAccessPipeline"
   debug="true">

if the optional "debug" attributes is not present, the default is "false".

NOTE: enabling debug for the access control pipeline also enables debug for it's internal "basic" access control valve.

Access Control Valve

Configuration file: security-domain.xml

Element:

<access-control-valve
   className="com.cafesoft.security.engine.access.valves.LogAccessRequestValve"
   debug="true">
   <param-list>
      <param name="logPath" value="${cams.home}/logs/system-access-control.log"/>
   <param-list>
</access-control-valve>

if the optional "debug" attributes is not present, the default is "false".

Access Control Policy

Configuration file: access-control-policy.xml

Element: <access-control-policy defaultBias="denied" debug="true">

if the optional "debug" attributes is not present, the default is "false".

Permission Collection

Configuration file: access-control-policy.xml

Element:

<permission-collection
   type="http"
   desc="HTTP Server Permissions"
   debug="true">

if the optional "debug" attributes is not present, the default is "false".

Access Control Rule Library

Configuration file: access-control-policy.xml

Element: <acr-lib debug="true">

if the optional "debug" attributes is not present, the default is "false".

Access Control Rule

Configuration file: access-control-policy.xml

Various access control rule element types exist. Each of the following elements supports a "debug" attribute:

Elements:

  • <auth-acr id="auth rule id" debug="true">
  • <host-acr id="host rule id" debug="true">
  • <acr id="access control rule expression id" debug="true">

if the optional debug attributes is not present, the default is false. If custom access control rule are developed, we recommend that they support a debug attribute.

Table 3 - Configuration parameters enabling/disabling component DEBUG-level messages

Troubleshooting Cams Access Control

This sections describes how to troubleshoot various Cams access control configuration problems and how to verify your configuration settings.

Troubleshooting a Cams Access Control Policy

Suppose you want to verify that the correct security domain is receiving an access control request for a given resource and that the appropriate permission and access control rule are being invoked. You'll need to:

  1. Enable DEBUG-level messages for the security domain protecting the resource
  2. Enable DEBUG-level messages for the security domain's access control policy component

(See sections: Configuring Loggers to enable DEBUG-level Messages and Configuring Components to enable DEBUG-level Messages). Once you've enabled these and either restarted the Cams Policy Server or reloaded the modified security domain, you should see DEBUG message like those in Example 1 within the security domain-specific trace log. If you don't see messages of this format, then you may not have the right debug flags turned on or some other security domain may be receiving the access control requests. These messages are generated by the standard Cams access control policy.

DEBUG - ------------------ Start Access Control Check -------------------------
DEBUG - AccessRequest
DEBUG - {
DEBUG - Security Domain=examples
DEBUG - Session Id=6578616d706c6573-31303236353136323034363934-6775657374-\ 4d2f4338a97cdaead51f2ccb35e94b2e8dcdce66
DEBUG - Remote Addr=127.0.0.1
DEBUG - Remote Host=localhost
DEBUG - Confidential=false
DEBUG - App Name=xml
DEBUG -
DEBUG - ResourceRequest
DEBUG - {
DEBUG - Id=http://localhost:8080/examples/index.jsp
DEBUG - Type=http
DEBUG - Actions=GET
DEBUG - Actions Mask=1 (dec) , 1 (bin)
DEBUG - }
DEBUG -
DEBUG - Session
DEBUG - {
DEBUG - Id=6578616d706c6573-31303236353136323034363934-6775657374-\ 4d2f4338a97cdaead51f2ccb35e94b2e8dcdce66
DEBUG - Creation Time=Fri Jul 12 16:23:24 PDT 2002
DEBUG - Last Touched Time=Fri Jul 12 16:23:25 PDT 2002
DEBUG - Status=ACTIVE
DEBUG - Subject
DEBUG - {
DEBUG - username=guest
DEBUG - principal: name=everyone, class=com.cafesoft.cams.auth.CSRolePrincipal
DEBUG - principal: name=guest, class=com.cafesoft.cams.auth.CSUserPrincipal
DEBUG - }
DEBUG - Attributes
DEBUG - {
DEBUG - default:namespace
DEBUG - {
DEBUG - }
DEBUG - }
DEBUG - }
DEBUG -
DEBUG - RequestDispatchStack
DEBUG - {
DEBUG - [1]=examples
DEBUG - [0]=system
DEBUG - }
DEBUG - }
DEBUG -
DEBUG - Permission
DEBUG - {
DEBUG - Description: Examples Content
DEBUG - ResourcePattern
DEBUG - {
DEBUG - Pattern=http://localhost:8080/examples/
DEBUG - Owner=NONE
DEBUG - }
DEBUG - Type=http
DEBUG - Actions=GET,POST
DEBUG - Actions Mask=3 (dec), 11 (bin)
DEBUG - ACR=allow role everyone
DEBUG - }
DEBUG -
DEBUG - ACR evaluated to "true": ACCESS GRANTED
DEBUG - AccessResponse
DEBUG - {
DEBUG - status=GRANTED
DEBUG - reason=0
DEBUG - message=null
DEBUG - LoginParameters
DEBUG - {
DEBUG - }
DEBUG - }
DEBUG - ------------------ End Access Control Check -------------------------
Example 1 - Access control request DEBUG-level messages

Table 4 defines the high-level sections within these debug messages and some of the values you might see under different conditions. Curly brackets and indentation are used to show logical collections of parameters and child/parent relationships. A dot notation is used in Table 4 to show parent/child relationships, but for brevity, only enough context is shown for the Debug Tag to uniquely identify it.

Debug Tag Debug Configuration Properties
AccessRequest

The incoming access control request, which encapsulates the information used to evaluate whether access to a resource will be granted or denied. All of the parameters contained within the access request are included between the curly brack that follows this line and the matching curly bracket farther down the listing.

AccessRequest.Security Domain

The name of the security domain receiving the access control request. This will correspond with the security domain-specific log file containing this message.

AccessRequest.Session Id The identifier of a session asserted for the access control request. Existence of this value asserts that the user has already authenticated. If the session object corresponding to this value exists and is valid, then the session object is also referenced by the access request.
AccessRequest.Remote Addr

The TCP/IP address of the host from which a user is attempting to access a protected resource.

AccessRequest.Remote Host

The DNS name of the host from which a user is attempting to access a protected resource. Cams currently depends on the access control agent (or the application containing the access control agent) to implement reverse DNS name lookups (IP address to name lookups). These name lookups can be very slow and unreliable, so it is not advisable or practical to have the Cams Policy Server resolve them unless you have complete control over the DNS configuration for the clients from which users will access resources.

If the reverse DNS is not enabled in the agent or the agent's application, then this value will contain the TCP/IP address (same as Remote Addr).

AccessRequest.Confidential

If "true", then the resource is being accessed via "confidential" means. For example, if the resource is a Web page, then SSL is in use.

AccessRequest.App Name

The name of the application containing the agent from which the access control request was received. This value is used to select a Login Configuration Entry from the security domain's Login Configuration if authentication is required.

ResourceRequest

Encapsulates information about the protected resource that a user wants to access.

ResourceRequest.Id

The identifier of the resource. The actual format for a resource identifier depends on it's type. In this case, an "http" resource is uniquely identified by it's fully-qualifier URL.

ResourceRequest.Type

The type of resource. This value is sent from the access control agent and must match one of the type supported by the Cams Policy Server. See the Cams Policy Server configuration file at: ${cams.home}/conf/cams.conf for the list of all registered resource types.

ResourceRequest.Actions The action or actions being requested on the resource. For example, the user may be attempting to "GET", "POST", "DELETE", etc a web URL. (If multiple actions are requested on the resource, then all actions must be granted in order for access to the resource to be granted.)
ResourceRequest.Actions Mask A bit mask used to efficiently compare resource request actions with corresponding permission actions. This value will be of interest to developers that add support for new resource types and permission types.
Session If an authenticated user is associated with the access request, then this tag encapsulates everything about that user's session. If no authenticated user is associated with the access request, then the content of this tag will be "NONE". If the value of AccessRequest.Session Id is populated and the contents of this tag is NONE, thent the session has either expired, been closes by an explicit "logout", or the reference Session Id is invalid and possibly counterfeit.
Session.Creation Time The date/time at which the session was created.
Session.Last Touched Time The date/time at which access control was last checked for the session. (This value is NOT updated by the "session-access" service or by session event handlers).
Session.Status The status of the session: "ACTIVE", "EXPIRED", or "CLOSED". In practice, the Session tag will be empty unless the session object is "ACTIVE". "EXPIRED" or "CLOSED" session states are used primarily by the session manager to purge session objects and to report that status of sessions queried via the session-access service.
Session.Subject Information about the authenticated Subject (user) associated with a Session. A A Subject will alway exist for an "ACTIVE" Session.
Subject.username The name and class of the user principal within the Subject. A Subject contains a list of Principal instances. The name of the first Principal in the list implemented by class: com.cafesoft.cams.auth.CSUserPrincipal is deemed the "user Principal".
Subject.principal The name and class of each Principal (including the user Principal) within the authenticated Subject. This tag may repeat any number of times, once for each Principal added by LoginModules at user authentication time.
Session.Attributes Name/value pairs associated with the authenticated user's session. These values are generally added when a session is first created by registered SessionEventHandlers. These values are segregated by "namespace" to help avoid collisions between applications different applications. (See the Cams Programmer's Guide, Chapter 5 - Programming Cams Sessions for more details).
RequestDispatchStack The stack of security domains to through which this access control request has traveled. The first name on the stack will be the current security domain, the last name on the stack will be the system secuirty domain.
Permission The permission within the access control policy that controls access to the requested resource. (This is established by pattern matching on the resource identifier and action(s)). If the indicated permission is not the one you'd like to control access to the resource, then you'll need to refine the resource pattern associated with the desired permission to "best match" the resource.
Permission.Description The textual description of the permission as specified in access-control-policy.xml.
ResourcePattern A container for the pattern for resource identifiers that match this permission and possibly the name of a security domain to which access control is to be delegated. Note: even if a resource identifier matches a permission's ResourcePattern, that will not guarantee that the permission will be selected to control access to the resource. In general, the "most specific" matching ResourcePattern will select the permission that applies.
ResourcePattern.Pattern The actual resource pattern used to match resource identifiers and choose the best matching permission.
ResourcePattern.Owner If "THIS", then the permission is enforced by the current security domain. Otherwise, the value indicates the next security domain to which the access control request will be delegated.
Permission.Type The type of permission. This will match the resource request.Type and corresponds to the permission collection type.
Permission.Actions The action(s) associated with the permission. Actions are specific to the type of resource. For example, "http" resource actions correspond to the different "HTTP" request types: "GET", "POST", "PUT", "DELETE", etc. A "file" resource type might support "CREATE", "READ", "WRITE", "EXECUTE", "DELETE", etc. The order of actions is not important when comparing with the actions within an access request's resource request. (The developer of a permission assigns a unque bit within the ActionMask to each unque action).
Permission.Actions Mask Decimal and Binary versions of an integer mask used for efficient comparison of actions within resource requests and other permissions. This value will be most useful to programmers creating custom permission types.
Permission.ACR The identifer of the access control rule that is evaluated to grant or deny access to the resource. If this value is "NONE", then the value of resource pattern.Owner must be populated with the security domain to which access control checks will be delegated.
"ACR evaluated to "true"": ACCESS GRANTED

A message that shows the results after evaluating the access control rule assocated with the permission.

AccessResponse A tag that encapsulates information returned to the access control agent for a given access response.
AccessResponse.status A code that indicates whether access to the protected resource was: GRANTED or DENIED
AccessResponse.reason If access to the protected resource was denied, then this value indicates why. (See AccessResponse.getReason()).
AccessResponse.message If access to the protected resource was denied, then this value contains a textual message describing why access was denied.
LoginParameters If access to the protected resource was denied because authetication is required, then is block indicates the application-specific login parameters returned to the agent. These values may indicate the address of the login server, login page, etc and are agent-specific.

Table 4 - Debug message sections and corresponding values

Back | Next | Contents