Troubleshooting ACI evaluation for PingDirectory

The PingDirectory server provides the ability to collect debug information related to ACI evaluation for any operation by enabling the Debug ACI Logger. The Debug ACI Logger is highly configurable and can be scoped to trace very specific request operations to focus on any ACI issue that might arise in the field.

Parameters for non-request operations, such as the following, are are set to false by default and should remain so:

log-connects
log-disconnects
log-security-negotiation
log-results
log-assuance-completed
log-search-entries
log-search-references
log-intermediate-responses

Do not enable this logger on a production server unless instructed to do so by Ping Identity Support. The server can write huge amounts of data to this file on a busy production server.

To enable the Debug ACI Logger, run the following command:

$ bin/dsconfig set-log-publisher-prop \
  --publisher-name "Debug ACI Logger" \
  --set enabled:true

Using this debug tracer is often more efficient by limiting the output using request and result criteria to match specific types of operations. An example result criteria for operations that fail because of insufficient access rights can be added to the logger as follows:

$ bin/dsconfig set-log-publisher-prop \
  --publisher-name "Debug ACI Logger" \
  --set "result-criteria:Insufficient Access Rights"

After the logger has been enabled, all matching operations begin writing ACI evaluation traces to the log file. The amount of information is quite large for each evaluation that is done. However, this information is useful if there is an ACI issue that is difficult to resolve. Most operations result in multiple "ACI DEBUG" traces in the log, since it usually requires multiple ACI rights to perform an operation, each of which requires a separate evaluation. In particular, you can expect a lot of debug tracing when dealing with ACIs for controls, extended operations, and proxied authorization.

The ACI DEBUG traces contain the following pieces of information:

Operation

Specifies a dump of the operation object that you can use to correlate to the original request operation.

ACI Container

Specifies the context of the ACI evaluation being performed.

Client Entry: Specifies an LDIF dump of the client request access.
Resource Entry: Specifies an LDIF dump of the target resource.
isProxiedAuth: Specifies if the client is attempting to proxy as another user.
Original Auth: Specifies the original client DN if authorization is currently via the proxy.
Rights: Specifies a list of the ACI rights being requested on the resource entry.
Control: Specifies the OIDs when evaluating ACIs for a control.
ExtOp: Specifies the OIDs when evaluating ACIs for an extended operation.

ACI Candidates

Specifies a list of all the ACIs known to this operation, sorted by origin.

Applicable ACIs

Specifies a list of ACIs relevant to the current evaluation. These ACIs are separated by type into "Denies" and "Allows".

Deny ACI Evaluations

Specifies the results of evaluating each "deny" ACI. If any of these evaluate to TRUE, then the operation will be denied.

Allow ACI Evaluations

Specifies the results of evaluating each "allow" ACI. At least one of these must evaluate to TRUE or the operation will be denied.

For users with the bypass-acl privilege, the Debug ACI Logger will not provide any ACI debug tracing since evaluations are not done for those operations. However, you will see the following trace if you have ACI debugging enabled (debug-aci-enabled is set to TRUE) for those operations:

Bypassing ACL Evaluation for Operation

To avoid unnecessary tracing of these operations, the "Debug ACI Logger" uses a "Client Connection Criteria" called "Clients subject to Access Control" that excludes requests from users with the bypass-acl privilege. It is recommended that you create and use your own criteria which specifically targets the clients that you are trying to debug in order to make analyzing the tracing output easier.

$ bin/dsconfig create-connection-criteria \
  --criteria-name "Restricted Clients" \
  --type simple \
  --set none-included-user-privilege:bypass-acl

Do not use Result Criteria with the Debug ACI Logger. Result criteria is evaluated after ACIs, so it will not be taken into consideration for this type of debugging.