JSON Parser configuration

The JSON Parser Attribute Connector is a tool that extracts values from JSON strings using JSONPathOpens in a new tab expressions.

A configuration must contain an identifier and two sections:

• The identifier is defined using the identifier attribute and must be globally unique, like a UUID. It serves two purposes. First, it helps identify the source of attribute values in host logs. Second, it generates unique identifiers for each attribute mapping within the configuration, used for runtime cache strategy configuration within the host engine.
• The source section specifies the source of the JSON data to be processed. It can be:
  • An attribute value provided by the host.
  • The contents of a file within the host environment.
  • A literal token value embedded in the configuration.
• The mapping(s) section contains multiple elements, each associating an attribute with a value within the JSON source. These mappings define the attributes the connector can provide to the host.

Source section

The source section is mandatory in every configuration and specifies the source of the JSON data to be processed. The sources can be:

• The value of an attribute

  The value is dynamically provided by the connector host for each policy evaluation. For example:

  XML

  <source>
    <xacmlAttribute AttributeId="user.data"
      Category="urn:oasis:names:tc:xacml:1.0:subject-category:access-subject"
      DataType="http://www.w3.org/2001/XMLSchema#string"/>
  </source>

  JSON

  JSON configuration files offer the option to use either ALFA or XACML for policy definitions.

  XACML

  {
    "source": {
      "xacmlAttribute": {
        "attributeId": "user.data",
        "category": "urn:oasis:names:tc:xacml:1.0:subject-category:access-subject",
        "datatype": "http://www.w3.org/2001/XMLSchema#string"
      }
    }
  }

  ALFA

  {
    "source": {
      "attributeName": "user.data"
    }
  }

  note

  When using ALFA, you must also include the dictionary (attributes section) in the authorization domain configuration.

  YAML

  YAML configuration files offer the option to use either ALFA or XACML for policy definitions.

  XACML

  source:
    xacmlAttribute:
      attributeId: "user.data"
      category: "urn:oasis:names:tc:xacml:1.0:subject-category:access-subject"
      datatype: "http://www.w3.org/2001/XMLSchema#string"

  ALFA

  source:
    attributeName: "user.data"

  note

  When using ALFA, you must also include the dictionary (attributes section) in the authorization domain configuration.

• The contents of a file within the environment of the connector host

  The value is read from a file during configuration and remains constant for all policy evaluations during the connector's lifetime. For example:

  XML

  <source>
    <json src="/secret/global-static-data.json"/>
  </source>

  JSON

  {
    "source": {
      "json": {
        "src": "/secret/global-static-data.json"
      }
    }
  }

  YAML

  source:
    json:
      src: "/secret/global-static-data.json"

• A literal JSON value embedded in the configuration

  The value is embedded within the configuration and remains constant for all policy evaluations during the connector's lifetime. For example:

  XML

  <source>
    <json>
      { "alice": { "role": "manager" } }
    </json>
  </source>

  JSON

  {
    "source": {
      "json": {
        "value": "{ \"alice\": { \"role\": \"manager\" } }"
      }
    }
  }

  YAML

  source:
    json:
      value: "{ \"alice\": { \"role\": \"manager\" } }"

Optionally, the source section can include an encoded attribute. This indicates if the source content is base64-encoded instead of plain text. The default is false.

The following example showcases literal base64-encoded JSON content embedded within the configuration:

XML

<source encoded="true">
  <json>eyJyb2xlIjoibWFuYWdlciJ9</json>
</source>

JSON

{
  "source": {
    "encoded": true,
    "json": {
      "value": "eyJyb2xlIjoibWFuYWdlciJ9"
    }
  }
}

YAML

source:
  encoded: true
  json: 
    value: "eyJyb2xlIjoibWFuYWdlciJ9"

In the example above, the eyJyb2xlIjoibWFuYWdlciJ9 string decodes into {"role":"manager"}.

Mapping section

The mapping section contains multiple mapping elements, each outlining an attribute the connector can offer to the host. These mappings pair an attribute with a value found within the JSON source. Each mapping element includes the following:

xacmlAttribute

The xacmlAttribute element contains the following attributes:

Attribute	Description	Mandatory
AttributeId	Indicates the XACML identifier of the attribute. For example, pip.payload.	Yes
Category	Indicates the category to which the XACML attribute belongs. For example, urn:oasis:names:tc:xacml:1.0:subject-category:access-subject.	Yes
DataType	Indicates the data type of the XACML attribute. For example, http://www.w3.org/2001/XMLSchema#string.	Yes
Issuer	Indicates the attribute's issuer but is rarely used.	No

attributeName

The attributeName element is only available in JSON and YAML configurations and contains the identifier of the ALFA attribute to be fetched from the attribute source. The supported format for this element is a valid ALFA attribute name that begins with a letter or underscore and includes only letters, numbers, and underscores.

Important

You cannot use both attributeName and xacmlAttribute in the same configuration simultaneously.

jsonPath

The jsonPath element contains a JSONPath expression specifying values to be collected from the JSON source.

note

The full reference for JSONPath can be found in the JSONPath - XPath for JSONOpens in a new tab webpage.

To make it adaptable, you can introduce parameters into the expression using placeholder variables in the format ##index##, where "index" denotes a number beginning at 1. For instance, $.authorizations[?(@.id=='##1##')].status demonstrates a parameterized expression.

key

This section defines a sequence of zero or more key elements. Each key represents an attribute required to complete an expression using placeholder variables.

Each key element contains exactly one xacmlAttribute or attributeName element (depending on whether you are using XACML or ALFA) and its structure is the same as previously described.

Mapping attributes

Additionally, the mapping element has two attributes:

Attribute	Description	Mandatory
collate	When enabled, this option combines multiple values found from the JSONPath search into a single value, instead of presenting them as individual entries in a bag. The default value is false.	No
delimiter	Used only when collate is enabled, this option specifies the separator between collated values. The default is a comma (,).	No

JSONPath search expressions

The search expressions use JSONPath whose full reference can be found in the JSONPath - XPath for JSONOpens in a new tab webpage. The following are a few useful examples:

• The abstract name $ points to the outer level object.

• In JSONPath, a period (.) serves as a separator between element names. For example, $.firstName points to the value associated with "firstName" in the outer level object. In the following example, it evaluates to "Joe".

  {
      "id": "1e36aef0-4e71-11e6-898d-f1931def5a85",
      "firstName": "Joe",
      "lastName": "Blog",
      "role": "manager"
  }

• If the response contains an array of objects, you can use the square bracket notation [i] to point to a specific object within the array. For instance, to select Joe’s last name in the example below, use $[0].lastName.

  [
    {
      "id": "1e36aef0-4e71-11e6-898d-f1931def5a85",
      "firstName": "Joe",
      "lastName": "Blog",
      "role": "manager"
    },
    {
      "id": "33cd91c1-4e71-11e6-898d-f1931def5a85",
      "firstName": "Alice",
      "lastName": "Swanson",
      "role": "student"
    }
  ]

  To select items in an array based on an expression, use the filter operator ?. For example, $[?(@.id=='1e36aef0-4e71-11e6-898d-f1931def5a85')].lastName, applied to the example above will select the value "Blog".

• To append a static prefix to the result of a search expression, use the concat function:

  concat("Bearer ",$.accessToken)

  which will yield a result such as Bearer abc123 .