PingAuthorize

Provided statements

The PingAuthorize Policy Editor comes with preconfigured statement types that are also in PingAuthorize Server.

Policy writers can use the following provided statements out of the box, and PingAuthorize Server fulfills the statements as documented:

  • Add Filter

  • Combine SCIM Search Authorizations

  • Denied Reason

  • Exclude Attributes

  • Filter Response

  • Include Attributes

  • Modify Attributes

  • Modify Headers

  • Modify Query

  • Modify SCIM Patch

  • Regex Replace Attributes

To view the set of provided statement types within the Policy Editor, click Add Statement.

provided statement no hover list

You can hover over a statement type to view its description.

provided statement hover list

Selecting a statement type prepopulates the Description and Code fields and provides an example Payload value. Most users replace the example Payload value with one that is appropriate for their policy.

provided statement pre-populated fields

The following sections describe the statement types built into PingAuthorize Server.

Add Filter

Use add-filter to add administrator-required filters to System for Cross-domain Identity Management (SCIM) search queries.

Description Details

Applicable to

SCIM

Additional information

The Add Filter statement places restrictions on the resources returned to an application that can otherwise use SCIM search requests. The filters that the statement specifies are ANDed with any filter that the SCIM request includes.

The payload for this statement is a string that represents a valid SCIM filter, which can contain multiple clauses separated by AND or OR. If the policy result returns multiple instances of the Add Filter statement, they are ANDed together to form a single filter that passes with the SCIM request. If the original SCIM request body included a filter, it is ANDed with the policy-generated filter to form the final filter value.

Combine SCIM Search Authorizations

Use combine-scim-search-authorizations to optimize policy processing for SCIM search responses.

Description Details

Applicable to

SCIM

Additional information

By default, SCIM search responses are authorized by generating multiple policy decision requests with the retrieve action, one for each member of the result set. The default mode enables policy reuse but might result in greater overall policy processing time.

When you use this statement type, the current SCIM search result set is processed using an alternative authorization mode in which all search results are authorized by a single policy request that uses the search-results action. The policy request includes an object with a single Resources field, which is an array that consists of each matching SCIM resource. Statements that the policy result returns are applied iteratively against each matching SCIM resource, allowing for the modification or removal of individual search results.

This statement type does not use a payload.

For more information about SCIM search handling, see About SCIM searches.

Denied Reason

Use denied-reason to allow a policy writer to provide an error message that contains the reason for denying a request.

Description Details

Applicable to

DENY decisions

The Denied Reason statement only applies to SCIM searches using the optimized search response authorization mode.

Additional information

The payload for Denied Reason statements is a JSON object string with the following fields:

  • status – Contains the HTTP status code returned to the client. If this field is absent, the default status is 403 Forbidden.

  • message – Contains a short error message returned to the client.

  • detail (optional) – Contains additional, more detailed error information.

The following example shows a possible response for a request made with insufficient scope:

{"status":403, "message":"insufficient_scope", "detail":"Requested operation not allowed by the granted OAuth scopes."}

Exclude Attributes

Use exclude-attributes to specify the attributes to exclude from a JSON response.

Description Details

Applicable to

PERMIT decisions, although you cannot apply Exclude Attributes statements directly to a SCIM search.

Also, do not use this statement type with SCIM modifies. Instead, use the Modify SCIM Patch statement type.

Additional information

The payload for this statement is a JSON array of strings. Each string is interpreted as a JSONPath into the response body of the request being authorized. Each JSONPath can select multiple attributes in the object. The portions of the response that a JSONPath selects are removed before sending the response to the client.

The following example instructs PingAuthorize Server to remove the attributes secret and data.private.

["secret","data.private"]

For more information about the processing of SCIM searches, see Filter Response.

Filter Response

Use filter-response to direct PingAuthorize Server to invoke policy iteratively over each item of a JSON array contained within an API response.

Description Details

Applicable to

PERMIT decisions from the gateway, although you cannot apply Filter Response statements directly to a SCIM search. However, the SCIM service performs similar processing automatically when it handles a search result. For every candidate resource in a search result, the SCIM service makes a policy request for the resource with an Action value of retrieve.

Additional information

When presented with a request to permit or deny a multivalued response body, Filter Response statements allow policies to require that a separate policy request be made to determine whether the client can access each individual resource that a JSON array returns.

The following list identifies the fields of the JSON object that represents the payload for this statement.

Path

JSONPath to an array within the API’s response body. The statement implementation iterates over the nodes in this array and makes a policy request for each node. This field is required.

Action

Value to pass as the action parameter on subsequent policy requests. If no value is specified, the action from the parent policy request is used. This field is optional.

Service

Value to pass as the service parameter on subsequent policy requests. If no value is specified, the service value from the parent policy request is used. This field is optional.

ResourceType

Type of object contained by each JSON node in the array, selected by the Path field. On each subsequent policy request, the contents of a single array element pass to the policy decision point as an attribute with the name that this field specifies. If no value is specified, the resource type of the parent policy request is used. This field is optional.

On each policy request, if policy returns a deny decision, the relevant array node is removed from the response. If the policy request returns a permit decision with additional statements, the statements are fulfilled within the context of the request. For example, this statement allows the policy to decide whether to exclude or obfuscate particular attributes for each array item.

For a response object that contains complex data, including arrays of arrays, this statement type can descend through the JSON content of the response.

Performance might degrade as the total number of policy requests increases.

Include Attributes

Use include-attributes to limit the attributes that a JSON response can return.

Description Details

Applicable to

PERMIT decisions, although you cannot apply Include Attributes statements directly to a SCIM search.

Also, do not use this statement type with SCIM modifies. Instead, use the Modify SCIM Patch statement type.

Additional information

The payload for this statement is a JSON array of strings. Each string is interpreted as a JSONPath into the response body of the request being authorized. The response includes only the portions that one of the JSONPaths selects. When a single JSONPath represents multiple attributes, the response includes all of them. If the policy result returns multiple instances of Include Attributes statements, the response includes the union of all selected attributes.

For more information about the processing of SCIM searches, see Filter Response.

Modify Attributes

Use modify-attributes to modify the values of attributes in the JSON request or response.

Description Details

Applicable to

All, although you can’t apply the Modify Attributes statement directly to a SCIM search.

Also, do not use this statement type for SCIM modify operations. Instead, use the Modify SCIM Patch statement type.

Additional information

The payload for this statement is a JSON object. Each key-value pair is interpreted as an attribute modification on the request or response body of the request being authorized. For each pair, the key is a JSONPath expression that selects the attribute to modify, and the value is the new value to use for the selected attribute.

The value can be any valid JSON value, including a complex value such as an object or array. A null value removes the attribute from the body. Key-value pairs that do not already exist are added to the body, unless the value is null.

Format: { "$.jsonPath": "attributeValue" }

Modify Headers

Use modify-headers to modify the values of request headers before PingAuthorize sends them to the upstream server or to modify the values of response headers before PingAuthorize returns them to the client.

Description Details

Applicable to

All, although you cannot apply the Modify Headers statement directly to a SCIM search.

Additional information

The payload for this statement is a JSON object. The keys are the names of the headers to set, and the values are the new values of the headers.

A value can be:

  • Null, which removes the header

  • A string, which sets the header to that value

  • An array of strings, which sets the header to all of the string values

If the header already exists, PingAuthorize overwrites it.

If the header does not exist, PingAuthorize adds it (unless the value is null).

If a payload value is an array of strings:

  • Given a header that supports multiple values, such as Accept, PingAuthorize repeats the header for each string in the array.

  • Given a header that does not support multiple values, such as Content-Type, PingAuthorize sends the last string in the array.

Modify Query

Use modify-query to modify the query string of the request sent to the API server.

Description Details

Applicable to

All

Additional information

The payload for this statement is a JSON object. The keys are the names of the query parameters that must be modified, and the values are the new values of the parameters. A value can be one of the following options:

null

The query parameter is removed from the request.

String

The parameter is set to that specific value.

Array of strings

The parameter is set to all of the values in the array.

If the query parameter already exists on the request, it is overwritten. If the query parameter does not already exist, it is added. For example, consider the following request made to a proxied API:

curl --location --request GET '{{apiPath}}/directory/v1/{{dn}}/subtree?searchScope=wholeSubtree&limit=1000' \
--header 'Authorization: Bearer {{jwtToken}}'

You can set a policy to limit certain groups of users to request only 20 users at a time. A payload of \{"limit": 20} causes the request to be rewritten as follows:

curl --location --request GET '{{apiPath}}/directory/v1/{{dn}}/subtree?searchScope=wholeSubtree&limit=20' \
--header 'Authorization: Bearer {{jwtToken}}'

Modify SCIM Patch

Use modify-scim-patch to add operations to a SCIM patch in a modify request before it is submitted to the store adapter.

Description Details

Applicable to

SCIM requests with an action of modify

Additional information

The payload for this statement is either a JSON array or a JSON object.

If the payload is an array, PingAuthorize treats it as a list of operations in the SCIM patch format to add to the end of the operations in the patch. For example, assume the modify has the following patch.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "path": "name.formatted", "value": "John Doe"}
  ]
}

Also, assume the statement payload is as follows.

[
  {"op": "add", "path": "name.first", "value": "John"},
  {"op": "remove": "path": "name.last"}
]

Then the resulting request to the store adapter looks like this.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "path": "name.formatted", "value": "John Doe"},
    {"op": "add", "path": "name.first", "value": "John"},
    {"op": "remove", "path": "name.last"}
  ]
}

If the payload is an object, PingAuthorize interprets it as a set of new replace operations to add to the end of the operations in the patch. In these replace operations, the keys from the object become the paths to modify, and the values from the object become the values for those paths. For example, assume the modify has the following patch.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "path": "name.formatted", "value": "John Doe"}
  ]
}

Also, assume the statement payload is as follows.

{"name.first": "John", "name.last": "Doe"}

Then the resulting request to the store adapter looks like this.

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "path": "name.formatted", "value": "John Doe"},
    {"op": "replace", "path": "name.first", "value": "John"},
    {"op": "replace", "path": "name.last", "value": "Doe"}
  ]
}

Regex Replace Attributes

Use regex-replace-attributes to specify a regex to search for attributes in a request or response body and replace their values with a regex replacement string.

Description Details

Applicable to

All, although you cannot apply the Regex Replace Attributes statement directly to a SCIM search.

Additional information

The payload for this statement is either a JSON object or an array of JSON objects. Each object represents a single replacement operation and has up to four keys. The following list describes these keys:

"regex"

Represents the regular expression to use to find the attribute values to replace. This key is required.

"replace"

Represents the regex replacement string to use to replace the attribute values with a new value. This key is required.

"path"

A JSONPath expression that represents the nodes to start searching under. The expression can point to objects, arrays, or strings in the body. This key is optional.

"flags"

A string that contains the regex flags to use. Recognized flags include:

  • "i"

    Performs case-insensitive matching.

  • "l"

    Treats the "regex" value as a literal string.

  • "c"

    Performs "canonical equivalence" matching.

PingAuthorize replaces any portion of the attribute value that matches the regular expression in the "regex" value in accordance with the "replace" replacement string. If multiple substrings within the attribute value match the regular expression, PingAuthorize replaces all occurrences.

The regular expression and replacement string must be valid as described in the API documentation for the java.util.regex.Pattern class, including support for capture groups.

Example

For example, consider the following body.

{
   "id":5,
   "username":"jsmith",
   "description":"Has a registered ID number of '123-45-6789'.",
   "secrets":{
      "description":"Has an SSN of '987-65-4321'."
   }
}

Also, consider the following payload.

{
   "path":"$.secrets",
   "regex":"\\\\d{3}-\\\\d{2}-(\\\\d{4})",
   "replace":"XXX-XX-$1"
}

Applying the statement produces the following body with a changed "secrets.description" value.

{
   "id":5,
   "username":"jsmith",
   "description":"Has a registered ID number of '123-45-6789'.",
   "secrets":{
      "description":"Has an SSN of 'XXX-XX-4321'."
   }
}