PingAuthorize

Statements

A statement is a directive that instructs the policy enforcement point (PEP) to perform additional processing in conjunction with an authorization decision.

When a policy is applied to a request or response, the policy result might include one or more statements. Statements allow the PEP—PingAuthorize Server, in this case—to do more than allow or deny access to an API resource. For example, a statement can:

  • Cause the removal of a specific set of fields from a response

  • Provide details about the reason for denying access to a user

You can add a statement directly to a single policy or rule and modify that statement as part of a policy definition. You can also add a statement in Components for use with multiple policies or rules.

Screen capture of a statement checking the risk for a specific customer and returning multiple attribute key-value pairs

Each statement contains the following mandatory fields:

Name

Human-readable label for reference in the Policy Manager

Code

Identifier that distinguishes between different types of statements

Applies To

Type of decision to which the statement is attached

Applies If

Condition under which the statement is returned in the decision response

If the Applies To criteria for a statement is met by its associated rule or policy decision, and that decision contributes to the final result, PingAuthorize uses the statement in its final response if the statement’s associated Applies If condition is satisfied. Select an option to exercise precise control over when a qualifying statement gets returned in a decision response, which can make it easier to provide reasons for both permit and deny decisions and risk evaluation feedback.

Statements carry additional data in the form of payloads and attributes:

  • The optional field Payload can consist of static or interpolated data.

  • The Attributes field lets you return a key-value mapping of attributes that might be relevant to the statement.

To indicate that the final decision applies only if a statement can be fulfilled, mark the statement as Obligatory. Typically, the service that calls PingAuthorize Server handles this responsibility.

You can reorder collapsed statements by dragging the handles on the left. To reorder using the keyboard, press Tab to go to the statement, press Enter to select the statement, press the Up Arrow key or Down Arrow key to go to the desired location, and press Enter to drop the statement in the new location.

The following table identifies significant statement properties.

Property Description

Name

Friendly name for the statement.

Obligatory

When marked as Obligatory, the statement must be fulfilled as a condition of authorizing the request:

  • If PingAuthorize can’t fulfill an obligatory statement, it fails the operation and returns an error to the client application.

  • If PingAuthorize can’t fulfill a non-obligatory statement, the server logs an error, but the client’s requested operation continues.

Code

Identifies the statement type. This value corresponds to a statement ID that the PingAuthorize configuration defines.

Applies To

Specifies the decision types that should include the associated statement with the result. Available types include:

  • Applicable: This is the default option. Select Applicable if the statement should apply to any of the following decision types.

  • Permit

  • Deny

  • Permit or Deny

  • Indeterminate

Applies If

Specifies how the statement propagates through the decision tree and whether it is returned in the overall decision response. Available options include:

  • All decisions in path match: The statement is returned when the decision for the rule or policy with which the statement is associated matches all decisions in the path. For example, when the decision for a rule with which the statement is associated is permit, and all decisions in the path are permit, the statement is returned. This is the default option.

  • Final decision in path matches: The statement is returned when the decision for the rule or policy with which the statement is associated matches the overall decision. For example, when the decision for the rule with which the statement is associated is permit, and the overall decision is permit, the statement is returned even if there are deny decisions in between.

  • All decisions in path are applicable: The statement is always returned, unless an error occurs in the associated decision.

Payload

Set of parameters governing the actions that the statement performs when PingAuthorize applies the statement. The appropriate payload value depends on the statement type.

PingAuthorize Server supports all of the provided statement types except for custom statements. To develop custom statement types, use the PingAuthorize Server SDK.

Many statement types let you use the JSONPath expression language to specify JSON field paths. To experiment with JSONPath, use this JSONPath evaluator.