Statement templates

PingOne Authorize provides statement templates that you can use in policies out of the box.

Statements templates in the Library enable you to easily add statements to policies. Each template includes a statement code, description, and example payload.

To ensure that statement templates are always available, you can’t update or delete them. However, you can update a statement cloned from a template. For more information about using statements in policies, see Adding statements to policies and rules.

Built-in statements created from the templates listed below are processed by the API Access Management HTTP Access Policy Service and require an API gateway integration. You can only use these built-in statements in custom policies and rules for API services.

The Library can also include other templates created by your organization for statements processed by the dynamic authorization decision service that don’t require an API gateway integration.

This HTTP request/response pair is used in several of the examples that follow:

Request

POST /accounts HTTP/1.1
Host: bankingexample.com:1443
Content-Length: 56
Accept: application/json

{
"ID": "123456",
"amount": "999",
"type": "Savings"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 56
Date: Mon, 17 Oct 13:17:18 GMT

{
"ID": "123456",
"amount": "999",
"type": "Savings"
}

Exclude attributes

Use the exclude-attributes statement to define a list of attributes to exclude from the HTTP response body in an inbound request or outbound response. This statement applies to permit decisions produced by custom API Access Management policies.

If your protected API is changing over time, consider using the include-attributes statement instead of the exclude-attributes statement. The include-attributes statement is a safer choice that continues to work when you add new attributes to your API.

Code

exclude-attributes

Payload

The payload for this statement is a JSON array of attribute names. This statement limits the attributes in the response body returned to the requester by removing attributes that are listed in the payload.

If an attribute has descendants, they are also removed from the response body.
If a single JSONPath expression represents multiple attributes, all of the represented attributes are removed from the response.

Format: [ "attribute-to-exclude", "attribute-to-exclude" ]

Example

The following payload instructs the decision service to remove the amount attribute from the HTTP response body.

Example payload: [ "amount" ]

Original body:

{
"ID": "123456",
"amount": "999",
"type": "Savings"
}

Modified body:

{
"ID": "123456",
"type": "Savings"
}

Include attributes

Use the include-attributes statement to define an allowed list of attributes to include in the HTTP response body in an inbound request or outbound response. This statement applies to permit decisions produced by custom API Access Management policies.

Code

include-attributes

Payload

If a listed attribute has ancestors, the response also includes the ancestors.
If a single JSONPath expression represents multiple attributes, the response includes all of the represented attributes.
If a policy result returns multiple instances of include-attributes statements, the response includes the union of all selected attributes.

Format: [ "attribute-to-include", "attribute-to-include" ]

Example

The following payload instructs the decision point to remove the type attribute from the HTTP response body.

Example payload: [ "ID", "amount" ]

Original body:

{
"ID": "123456",
"amount": "999",
"type": "Savings"
}

Modified body:

{
"ID": "123456",
"amount": "999"
}

Modify query

Use the modify-query statement to add, update, or remove request URL query parameters. This statement applies to permit decisions produced by custom API Access Management policies. This statement doesn’t apply to outbound responses.

Code

modify-query

Payload

The payload for this statement is a JSON object that contains key-value pairs. For each pair, the key is the name of the query parameter to modify, and the value is the new value of the query parameter. The value can be:

null: Removes the query parameter from the request.
String: Sets the query parameter to that specific value.
Array of strings: Sets the query parameter to all of the values in the array.

If the query parameter already exists in the request, the decision service overwrites it. If the query parameter does not already exist, the decision service adds it, unless the value is null.

Format: { "queryParameter": "parameter-value" }

Example

The following payload instructs the decision service to modify a query parameter that returns 20 accounts at a time to return 10 instead.

Example payload: { "limit":"10" }

Original request:

GET /accounts?limit=20 HTTP/1.1
Host: bankingexample.com:1443
Accept: application/json

Modified request:

GET /accounts?limit=10 HTTP/1.1
Host: bankingexample.com:1443
Accept: application/json

Regex replace attributes

Use the regex-replace-attributes statement to use regular expressions to search for and replace attribute values in the HTTP response body in an inbound request or outbound response. This statement applies to permit decisions produced by custom API Access Management policies.

Code

regex-replace-attributes

Payload

The payload for this statement is a JSON object that contains key-value pairs, or an array of JSON objects. Each JSON object represents a single replacement operation and has up to four keys:

path: Optional. A JSONPath expression that represents the nodes to search under. The expression can point to objects, arrays, or strings in the body.
regex: Required. The regular expression used to find the attribute values to replace.
replace: Required. The regex replacement string used to replace the attribute value with a new value.
flags: Optional. A string that contains any of the following recognized regex flags:
- i: Performs case-insensitive matching.
- l: Interprets the regex key’s value as a literal string.
- c: Performs canonical equivalence matching.
You can combine flags. For example: “il”.

The decision service replaces any portion of the attribute value that matches the regular expression in the regex key’s value in accordance with the replace key’s replacement string. If multiple substrings in the attribute value match the regular expression, the decision service 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.

Format: { "path": "$.jsonPath", "regex": "regex", "replace": "replacement-value" }

Example 1

The following payload instructs the decision service to replace the account type Savings with the account type PremierSavings.

Example payload:

{
"path":"$.type",
"regex":"^S[a-z]+s$",
"replace":"PremierSavings"
}

Original body:

{
"ID": "123456",
"amount": "999",
"type": "Savings"
}

Modified body:

{
"ID": "123456",
"amount": "999",
"type":"PremierSavings"
}

Example 2

The following payload instructs the decision service to mask the social security number.

Example payload:

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

As an alternative, you can use a different regular expression to do the same thing:

{
"regex": "[0-9]{3}-[0-9]{2}-([0-9]{4})",
"replace": "XXX-XX-$1"
}

Original body:

{
"name": "Jacob Andrews",
"age": "39",
"SSN": "123-45-6789"
}

Modified body:

{
"name": "Jacob Andrews",
"age": "39",
"SSN": "XXX-XX-6789"
}

Set attributes

Use the set-attributes statement to add, update, or remove attribute values in the HTTP response body in an inbound request or outbound response. This statement applies to permit decisions produced by custom API Access Management policies.

Code

set-attributes

Payload

The payload for this statement is a JSON object that contains key-value pairs. 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 points to the attribute being modified, and the value is the new value for the 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 HTTP body. Key-value pairs that do not already exist are added to the HTTP body, unless the value is null.

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

Example

The following payload instructs the decision service to replace the account type Savings with the account type PremierSavings.

Example payload: { "$.type":"PremierSavings" }

Original body:

{
"ID": "123456",
"amount": "999",
"type": "Savings"
}

Modified body:

{
"ID":"123456",
"amount":"999",
"type":"PremierSavings"
}

Set headers

Use the set-headers statement to add, update, or remove HTTP request and response headers before they’re returned to the API gateway. This statement applies to permit decisions produced by custom API Access Management policies.

Code

set-headers

Payload

The payload for this statement is a JSON object that contains key-value pairs. For each pair, the key is the name of the header field to set, and the value is the new value of the header field. The value can be:

null: Removes the header field.
A string: Sets the header field to that value.
An array of strings: Sets the header field to all of the string values.

If the header field supports multiple values, such as the Accept field, the decision service repeats the header field for each string in the array. If a header field doesn’t support multiple values, such as the Content-Type field, the decision service sets the header field to the last string in the array.

If a header field already exists, the decision service overwrites it. If a header field doesn’t already exist, the decision service adds it, unless the value is null.

Format: { "Header-Name": "header-value" }

Example

The following payload instructs the decision service to add a custom request header.

Example payload: { "X-UserName": "user@bankexample.com" }

Original headers:

Host: bankingexample.com:1443
Content-Length: 13
Accept: application/json

Modified headers:

Host: bankingexample.com:1443
Content-Length: 13
Accept: application/json
X-UserName: user@bankexample.com