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. Learn more about using statements in policies in 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"
}

Respond with authentication step-up challenge

Use the auth-challenge statement to implement step-up authentication challenges in policies that protect API services and operations. In step-up authentication, HTTP servers use the WWW-Authenticate response header to challenge OAuth 2.0 clients to provide sufficient credentials. Learn more about authentication challenges and bearer token usage in RFC 9470 and RFC 6750.

The auth-challenge statement:

Applies to deny decisions produced by inbound decision requests only
Adds the WWW-Authenticate header to deny responses

Learn more in Step-up authentication.

Code

auth-challenge

Payload

The payload for this statement is a JSON configuration object with the following properties:

Property Type Required Description

httpStatus

Number

Required

The HTTP response status code to send to the client.

Example: 401

scheme

String

Optional

The challenge type. When this is not set, the default is "Bearer".

realm

String

Optional

Provides the scope of protection as a hint to the end user about which credentials are needed.

error

String

Required

An error code. Standard error codes are defined by RFC 6749, RFC 6750, and RFC 9470.

Example: "insufficient_user_authentication"

errorDescription

String

Optional

A human-readable error description for informational purposes that is meant for developers, not end-users.

Example: "A different authentication level is required"

errorUri

String

Optional

An absolute URI that identifies a Web page explaining the error.

Example: "https://example.com/insufficient_user_authentication"

acrValues

Array (String)

Optional

The authentication context class reference values, in order of preference, that the protected resource requires for the authentication event associated with the access token. Values are separated by spaces and can include the PingOne SSO policy name or DaVinci flow ID.

If you are using PingOne as your identity provider (IdP), PingOne SSO only considers the first listed value in authorization requests. Other IdPs might support multiple values.

acrValues provide authentication context that conveys information about how authentication takes place, such as the authentication methods or assurance level to meet.

Example: ["Single_Factor"]

maxAge

Number

Optional

The allowable elapsed time in seconds since the last active authentication event associated with the access token.

Example: 3600

scopes

Array (String)

Optional

An array of OAuth 2.0 scopes required to access the protected resource.

Example: ["scope1","scope2"]

Format:

{
  "httpStatus": 401,
  "error": "insufficient_user_authentication",
  "errorDescription": "Description",
  "acrValues": [
    "Authentication_Method"
  ],
  "maxAge": number of seconds
}

Example

The following payload instructs the decision service to construct an authentication challenge informing the requesting client that a different authentication level (multi-factor) and more recent authentication (within the last hour) are required.

Example payload:

{
  "httpStatus": 401,
  "error": "insufficient_user_authentication",
  "errorDescription": "A different authentication level is required. More recent authentication is required.",
  "acrValues": [
    "Multi_Factor"
  ],
  "maxAge": 3600
}

Example HTTP response status and WWW-Authenticate header value:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication",
     error_description="A different authentication level is required. More recent authentication is required.",
     acr_values="Multi_Factor",
     max_age="3600"

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