Skip to main content
Version: 1.1

XML Parser configuration

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

A configuration starts with a root element named configuration and 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 (source) specifies the source of the XML data to be processed. It can be:

    • An XACML 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 section contains multiple mapping elements, each associating an attribute with a value within the XML 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 XML data to be processed. The sources can be:

  • The value of an XACML attribute

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

    <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>

  • 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:

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

  • A literal XML 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:

    <source>
      <xml>
        <![CDATA[<users><alice><role>manager</role></alice></users>]]>
      </xml>
    </source>

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 XML content embedded within the configuration:

<source encoded="true">
  <xml>PHJvbGU+bWFuYWdlcjwvcm9sZT4=</xml>
</source>

In the example above, the PHJvbGU+bWFuYWdlcjwvcm9sZT4= string decodes into <role>manager</role>.

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:

AttributeDescriptionMandatory
AttributeIdIndicates the XACML identifier of the attribute. For example, user.role.Yes
CategoryIndicates the category to which the XACML attribute belongs. For example, urn:oasis:names:tc:xacml:1.0:subject-category:access-subject.Yes
DataTypeIndicates the data type of the XACML attribute. For example, http://www.w3.org/2001/XMLSchema#string.Yes
IssuerIndicates 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.

xPath​

The xPath element contains a XPath expression specifying values to be collected from the XML source.

note

Read the XPath documentation and samplesOpens in a new tab for details.

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 example, /users/##1##/role/text().

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:

AttributeDescriptionMandatory
collateWhen enabled, this option combines multiple values found from the XPath search into a single value, instead of presenting them as individual entries in a bag.
The default value is false.		No
delimiterUsed only when collate is enabled, this option specifies the separator between collated values. The default is a comma (,).No

XPath search expressions​

The search expressions use XPath expressions that will return values. For example, the expression /class/student/name/text() is used to return the student’s name.

There are several online resources available to test XPath expressions such as the XPath TesterOpens in a new tab. Additionally, the XPath SyntaxOpens in a new tab webpage covers some of the most commonly used XPath expressions.