Reason codes for rule failures

This feature allows the target application to fail or permit the access request based on the rule failure reason code it is given by the resource manager.

The authorization engine processes all policies for the access decision as normal. If the rule evaluation fails, the engine returns access denied with a reason code in the azn_perminfo_reason_rule_failed permission information attribute list.

When access is denied, the application must check the permission_info attribute list returned from the access decision call. The application determines Whether a rule failure reason code was returned from the access decision. The resource manager does not need to check for the attribute on a successful access decision call. The Security Verify Access application is an example of an aznAPI resource manager that can use the rule failure reason code. When configured, Security Verify Access forwards the reason code to the protected web application. The protected web application must be mounted through a secure junction to have access to the reason code defined for the authorization rule. The use of rule failure reason codes in ISAM is limited to the protected object space of junctioned web applications.

The attribute value (the reason code) of the azn_perminfo_reason_rule_failed attribute is a single string. The value is determined and defined by the policy administrator and is set in the rule policy object when it is first created. The only constraint on the value of the reason code is that the value must be a string. The following conditions must be met before a rule failure reason code is returned to the caller:

• The reason code is returned only when the access request is denied and the rule policy evaluation denies access. However, the reason code is not returned for every case in which access is denied. The reason code is not returned when the rule evaluation succeeds. The rule failure reason code is not returned if the rule failed due to a rule syntax error. The code is not returned if there was insufficient ADI to do the rule evaluation. In the latter cases, the authorization decision is failed with an error status.
• There must be a reason code set in the attached rule policy object. This value is set in the rule policy with the admin API or the pdadmin utility.
• The aznAPI application must be enabled to return the rule failure reason as permission information. To do this action, either the azn_init_set_perminfo_attrs initialization parameter or the equivalent configuration file entry in the [aznapi-configuration] stanza (stanza entry permission-info-returned) must include the attribute name azn_perminfo_reason_rule_failed. This feature enables the attribute to be returned by the authorization engine in the permission information output parameter (perminfo) of azn_decision_access_allowed_ext(). See the Authorization C API Developer Reference.

Parent topic: Authorization rules evaluator