Version: 1.16

YAML-format domain file analysis

This section describes in more detail the contents of the YAML domain configuration file.

This file contains several sections. You can use any text editor to create and edit the YAML-format domain configuration file. (See yaml.orgOpens in a new tab, for more information about the format.)

The examples in this section only display specific parts of the domain configuration sections. For a complete view, see the Sample domain file included in the Additional resources section.

Identity section

The identity section uniquely identifies the domain.

It is configured using the identity property that has a single, case-sensitive string value adhering to the following constraints:

the string may only contain alphabetic characters (a-z, A-Z), digits (0-9), underscores (_), hyphens (-), and periods (.).
the string cannot contain spaces

This information can be useful for versioning and/or life-cycle management. If logging is enabled the identity is printed in the audit log as groupId.

It is recommended to update it every time you change the domain configuration.

note

ADS cannot initialize if the identity property is not set.

Example:

identity: domain_identification_1234

Identity section example

Metadata section

This is an optional section for storing metadata used for tooling and domain management workflow processes. This section can have any number of sub-properties like shown in the example below.

Example:

metadata:   ## Marks the start of the metadata section of the domain configuration file.
    status: published   
    approvedBy: Bob
## each metadata entry is in the format <Metadata key>: <Metadata value>

Metadata section example

Metadata properties

Below is a list of the components that the metadata sub-properties consist of:

Components	Examples	Notes
`<Metadata key>`	`status`, `approvedBy`	The key must be a string only containing alphabetic characters (a-z, A-Z), digits (0-9), underscores (_), hyphens (-), and periods (.).
`<Metadata value>`	`under-development`, `in-review`	The value can be any string.

The metadata could be used, for example, to indicate the status of the domain (under-development, in-review, published), or the sensitivity of the document (public, secret, top-secret).

note

ADS will disregard the actual content of the metadata section and focus only on ensuring its structure is correct.

Policy section

This section contains the authorization policies, expressed as a list of XACML policies and/or policy sets.

To create or edit entries in this section, you can use any software tool, including plain text editors, that can produce XACML 3.0 compliant policies.

Axiomatics provides the following three tools that you can use to create policies:

The Policy Editor of Axiomatics Services Manager (ASM)
The Policy Administration Point (PAP)
The Axiomatics Language for Authorization (ALFA) plugin and compiler.

note

ADS will not start if the domain configuration file lacks a policy.

The policies section is included under the policy property and includes the sub-properties listed below.

Policy properties

Below is a list of the sub-properties that define the policy section:

Property	Description
`policy`	Marks the start of the Policy section of the domain configuration file.
`mainPolicyId`	Contains a reference to the ID of the policy or policy set in the subsequent list of policies that will serve as the main policy. There must be a designated main policy, or root policy, as a starting point for the evaluation process. If you are using a dedicated application, such as one of the editing tools provided by Axiomatics, policy and policy set IDs may have been generated automatically by the editing tool. Regardless of method of creation, no two policies can have the same ID. To change main policy, update this field with the ID of the new main policy.
`xacmlSpecifications`	Contains the actual policy specifications in a list format. Create an entry in the list by typing `-

important

Be sure to follow the indentation rules for lists in YAML when you add policy specifications. Include one list entry per policy or policy set. Repeat for as many policies as required. The policies do not have to be entered in a particular order.

The following example displays a YAML policy section that includes a main policy ID and an embedded XACML policy specification. The XACML policy is described as a string within the YAML file. It details a policy with a specific rule for granting access if the role ismanager:

Policy section example (detail)

important

Policy content can only be specified as in-line text. References using URIs/URLs are not allowed. Only XACML 3.0 format is supported.

Attributes section

An attribute is identified by a string called an attribute identifier. This attribute identifier needs to be associated with a XACML quadruple made up of the following components:

a XACML identifier,
a category,
a data type,
and an issuer

This is the way XACML defines attributes. These are required for compatibility with internal components that cannot handle attribute identifiers.

Duplicate attribute identifiers are not allowed within the attributes section, nor can there be duplicate XACML quadruples. If a duplicate is found, an error message is displayed and ADS will not run.

Example:

attributes:         ## Marks the start of the attributes section of the domain configuration file.
  role:             ## Attribute identifier
    xacmlId: com.acme.user.role
    category: AccessSubject
    datatype: string
    issuer: Acme Inc.
  resourceId:       ## Attribute identifier
    xacmlId: com.acme.user.resourceId
    category: urn:oasis:names:tc:xacml:3.0:attribute-category:resource
    datatype: http://www.w3.org/2001/XMLSchema#string
    issuer: Acme Inc.

Attributes section example

Attribute identifiers

An attribute identifier is a short and simple name for the attribute, like for example: role, _documentStatus, attributes.resourceType.

It should be in the form of a single, case-sensitive string adhering to the following constraints:

the name may only contain alphabetic characters (a-z, A-Z), digits (0-9), and underscores (_)
no segment of the attribute name (separated by a period (.)) can start with a digit (0-9), neither can an element or the whole name be a single underscore
no segment of the attribute name (separated by a period (.)) can use any of the following reserved words

should not be a reserved word, as listed in the table below:

Reserved words
advice	bag	function	namespace	policyset
allowbags	category	id	obligation	rule
and	clause	import	on	ruleCombinator
anyAtomic	comm	infix	or	target
anyAtomicOrBag	condition	inv	permit	true
apply	deny	issuer	policy	type
attribute	false	mustbepresent	policyCombinator

Attribute properties

Below is a list of the sub-properties that define the attributes section:

Property	Description	Examples
`xacmlId`	A URI representing the XACML identifier (or attribute ID) of the attribute.	`com.acme.user.role`
`category`	Declares which category the attribute belongs to.	`urn:oasis:names:tc:xacml:1.0:subject-category:access-subject`
`datatype`	Declares the XACML data type of the attribute.	It is possible to use either the full XACML category URI or a short name. `datatype: "http://www.w3.org/2001/XMLSchema#integer"<br /> or<br />datatype: integer`
`issuer`	Defines the issuer of the attribute, such as a person or a department. This field is optional, but if used it must have a value.	`Axiomatics`

XACML categories

In the category property you can either use the full XACML category URI or a short name for a standard category.

Both category: Resource and category: "urn:oasis:names:tc:xacml:3.0:attribute-category:resource" refer to urn:oasis:names:tc:xacml:3.0:attribute-category:resource.

The shorthand notation is translated to the full XACML URI when read from the configuration file.

Below are some examples:

Identifier	Short name
urn:oasis:names:tc:xacml:3.0:attribute-category:resource	Resource
urn:oasis:names:tc:xacml:3.0:attribute-category:action	Action
urn:oasis:names:tc:xacml:3.0:attribute-category:environment	Environment
urn:oasis:names:tc:xacml:1.0:subject-category:access-subject	AccessSubject

XACML category examples

For a full list of the standard XACML categories, see the OASIS specificationOpens in a new tab.

note

All other strings are interpreted as references to custom user-defined categories, which must be constructed using the anyURI format

XACML datatypes

In the datatype property you can either use the full datatype URI or a short name.

Both datatype: integer and datatype: "http://www.w3.org/2001/XMLSchema#integer" refer to the http://www.w3.org/2001/XMLSchema#integer datatype.

The shorthand notation is translated to the full XACML URI when read from the configuration file.

Below are some examples:

Identifier	Short name
http://www.w3.org/2001/XMLSchema#boolean	boolean
http://www.w3.org/2001/XMLSchema#date	date
http://www.w3.org/2001/XMLSchema#dateTime	dateTime
http://www.w3.org/2001/XMLSchema#integer	integer
http://www.w3.org/2001/XMLSchema#string	string
http://www.w3.org/2001/XMLSchema#time	time

Datatype examples

For a complete list of the supported datatypes, see the OASIS specificationOpens in a new tab. Any other strings are understood to refer to custom datatypes, which are created using the anyURI format.

Attribute connectors section

Attributes used in a policy may need to get their values from an external source such as a database or an LDAP directory. A source of such data is called a Policy Information Point (PIP). ADS connects to a PIP via an attribute connector.

The attribute connector contains information about the type of attribute source (for example, LDAP, or SQL), the XACML attributes it provides, and how to obtain them (query strings specific to the PIP type and instance). The attribute connectors themselves are then used at runtime during policy evaluation.

The attribute connector can be exported from ASM (as attribute_connector.xml). The file contains the configuration string for the attribute connector, ready to be pasted into the YAML domain configuration file.

attributeConnectors:        ## Marks the start of the Attribute Connectors section
  employee_database#1:      ## attribute connector identifier 
    className: com.axiomatics.acs.plugin.pips.sql.SqlPipModule # The class name of the attribute connector.
    provides:
      - role
      - resourceId
    configurationString: |
      <cfg:configuration xmlns:cfg='http://www.axiomatics.com/jdbc.config' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation=''>
        <cfg:connnection>
          <!-- Environment variable substitution with default value. -->
          <cfg:url>${MY_DB_URL:-jdbc:h2:mem:ac1}</cfg:url>
          <cfg:driver>${MY_DB_DRIVER:-org.h2.Driver}</cfg:driver>
        </cfg:connnection>
        <cfg:mapping>
          <cfg:xacmlAttribute AttributeId='com.acme.user.role' Category='urn:oasis:names:tc:xacml:1.0:subject-category:access-subject' DataType='http://www.w3.org/2001/XMLSchema#string' Issuer='Acme Inc.'/>
          <cfg:nativeAttribute>
            <cfg:sqlType>2004</cfg:sqlType>
            <cfg:query>SELECT ROLE FROM EMPLOYEES WHERE EMPLOYEE_ID = ?</cfg:query>
            <cfg:key allowMultiple='false' sqlType='12'>
              <cfg:xacmlAttribute AttributeId='com.acme.user.employeeId' Category='urn:oasis:names:tc:xacml:1.0:subject-category:access-subject' DataType='http://www.w3.org/2001/XMLSchema#string' Issuer=''/>
            </cfg:key>
          </cfg:nativeAttribute>
          <cfg:uId>region_0</cfg:uId>
        </cfg:mapping>
      </cfg:configuration>

Attribute Connectors section example (detail)

Notes for attribute connector identifier

A single, case-sensitive string that identifies the attribute connector. It must adhere to the following constraints:

the string may only contain alphabetic characters (a-z, A-Z), digits (0-9), underscores (_), hyphens (-), and periods (.).
the string cannot contain spaces

Attribute connectors properties

Below is a list of the sub-properties that define the attribute connectors section:

Property	Description	Notes
`className`	The class name of the attribute connector, that is, the fully qualified name of the class that implements the attribute connector.
`provides`	A list of the attributes this attribute connector is expected to provide.	The configuration is optional, but must be present if attribute caching is enabled.
`configurationString`	This is the configuration of the attribute connector, for example, connection and mapping data.	Add the configuration content by typing `

Environment variables

Environment variables can be utilized to configure properties, offering a secure method for handling sensitive data.

note

Axiomatics recommends using environment variables to substitute any sensitive information, such as passwords, so that sensitive information can be managed and protected using generic mechanisms, external to the deployment file.

Example of environment variables use

The following example shows an attribute connector that uses an environment variable to set the connection information in the configurationString.

The YAML codeblock in this example is designed to represent the configuration setup for an attribute connector in a system that connects to an employee database. Variables such as ${MY_DB_URL} and ${MY_DB_DRIVER} are meant to be replaced with actual environment variable values during runtime.

The syntax is: ${<environment variable name\>:-<default value\>}.

attributeConnectors:
  employee_database#1:
    className: com.axiomatics.acs.plugin.pips.sql.SqlPipModule
    provides:
      - role
      - resourceId
    configurationString: |
      <cfg:configuration xmlns:cfg='http://www.axiomatics.com/jdbc.config' xmlns:xacml='urn:oasis:names:tc:xacml:2.0:policy:schema:os'>
        <cfg:connection>
          <!-- Environment variable substitution with default value. -->
          <cfg:url>${MY_DB_URL:-jdbc:h2:mem:ac1}</cfg:url>
          <cfg:driver>${MY_DB_DRIVER:-org.h2.Driver}</cfg:driver>
        </cfg:connection>
        <cfg:mapping>
          <cfg:xacmlAttribute AttributeId='com.acme.user.role' Category='urn:oasis:names:tc:xacml:1.0:subject:subject-id'>
            <cfg:nativeAttribute>
              <cfg:sqlType>2004</cfg:sqlType>
              <cfg:query>SELECT ROLE FROM EMPLOYEES WHERE EMPLOYEE_ID = ?</cfg:query>
              <cfg:key allowMultiple='false' sqlType='12'>
                <cfg:xacmlAttribute AttributeId='com.acme.user.employeeId' Category='urn:oasis:names:tc:xacml:1.0:subject:subject-id'/>
              </cfg:key>
            </cfg:nativeAttribute>
          </cfg:xacmlAttribute>
          <cfg:nativeAttribute>
            <cfg:sqlType>2004</cfg:sqlType>
            <cfg:query>SELECT REGION FROM EMPLOYEES WHERE EMPLOYEE_ID = ?</cfg:query>
            <cfg:key allowMultiple='false' sqlType='12'>
              <cfg:xacmlAttribute AttributeId='com.acme.user.region' Category='urn:oasis:names:tc:xacml:1.0:subject:subject-id'/>
            </cfg:key>
          </cfg:nativeAttribute>
        </cfg:mapping>
      </cfg:configuration>

Environment variable substitution with a default value (detail)

In the example, the string ${MY_DB_DRIVER:-org.h2.Driver} will be replaced by the value of the environment variable MY_DB_DRIVER if it exists, otherwise the default value org.h2.Driver will be used.

note

Even though the environment variable mechanism can be used elsewhere, you should be aware that this may affect the normal functioning in ways that are difficult to audit or troubleshoot.

Constraints

When an attribute connector specifies that it supplies an attribute with data, a matching attribute definition must exist in the domain configuration's Attributes section. Additionally, each attribute connector must have a unique identifier to avoid duplicates.

Attribute cache section

To enhance performance, attribute values retrieved from attribute connectors can be stored in a cache. This is an optional setting; however, if activated, it requires both timeToLive and maxItems sub-properties to be assigned valid values. Without enabling attribute caching, the attribute connector will be queried each time an attribute is accessed.

In the sample below, replace <Attribute identifier> with your actual attribute identifier value, as it serves as a placeholder.

attributeCache:     ## Marks the start of the Attribute Cache section of the domain configuration file.
  <Attribute identifier>:   ## This is a placeholder, enter your specific attribute identifier.
    timeToLive: 5000 seconds
    maxItems: 100

Attribute Cache section example

Attribute cache properties

Below is a list of the sub-properties that define the attribute caching section:

Properties	Description	Value
`<Attribute identifier>`	Defines the attribute identifier (or name) for which the caching value is configured. Attribute caching will not work unless this attribute is defined in the Attributes section of the domain configuration file, and the attribute is provided by an attribute connector. Without this configuration, ADS will not start.	String
`timeToLive`	Defines the maximum total time that a cached item remains in the attribute cache. The "time to live" (TTL) value for cached data should be determined by the frequency of data updates. It's essential to find an optimal balance between speed, as cached data loads quicker, and the freshness of content, since data held in cache too long may become outdated. Once a cached item exceeds its TTL, it is considered expired and must be removed. To refresh the cache with the most current data, the system will need to re-query the attribute connector.	Integer followed by a time unit expressed in one of the following ways: second: s, second, seconds minute: m, min, mins, minute, minutes hour: h, hour, hours day: d, day, days
`maxItems`	Specifies the maximum number of attribute values that can be stored for each attribute, with the minimum allowable value being 1. Upon reaching the maximum specified by the `maxItems` setting, the system will remove items based on the Least Recently Used (LRU) policy to make space for new entries.	Integer (minimum of 1)

note

For the maxItems value consider that the required amount of RAM increases with the number of stored values. Moreover, the nature of the attribute data affects how much memory is needed. For instance, storing 1000 integers will have different memory requirements compared to storing 1000 variable-length strings.

Decision parameters section

Enabling this property means that ADS will attempt to perform multiple-request optimization. In some cases this can improve the performance of ADS. In some special cases it may have a negative impact on performance. The actual improvement depends on several factors, for example, the structure of the request and the structure of the policy.

decisionParameters:     ## Marks the start of the Decision Parameters section of the domain configuration file.
  partialEvaluationThreshold: 2

Decision Parameters section example

partialEvaluationThreshold:

This property indicates how many individual requests a multiple-decision request should contain before ADS attempts to optimize that specific multiple request. It must adhere to the following constraints:

the value must be an integer
the value must be 2 or higher

If the threshold value is set too low, it may reduce performance. If the threshold value is set too high, it is less likely that it will be reached. The correct number cannot be determined without testing.

Deploy the authorization domain configuration file

After creating an authorization domain configuration file, it must be made available for deployment in Access Decision Service. This is done by setting a file retrieval reference to the YAML-format file using the domain property in the deployment configuration file.

See Authorization domain configuration for more information.

On this page

YAML-format domain file analysis

Identity section

Metadata section

Metadata properties

Policy section

Policy properties

Attributes section

Attribute identifiers

Attribute properties

XACML categories

XACML datatypes

Attribute connectors section

Attribute connectors properties

Environment variables

Example of environment variables use

Constraints

Attribute cache section

Attribute cache properties

Decision parameters section

Deploy the authorization domain configuration file

On this page

On this page

YAML-format domain file analysis

Identity section​

Metadata section​

Metadata properties​

Policy section​

Policy properties​

Attributes section​

Attribute identifiers​

Attribute properties​

XACML categories​

XACML datatypes​

Attribute connectors section​

Attribute connectors properties​

Environment variables​

Example of environment variables use​

Constraints​

Attribute cache section​

Attribute cache properties​

Decision parameters section​

Deploy the authorization domain configuration file​

On this page

Identity section

Metadata section

Metadata properties

Policy section

Policy properties

Attributes section

Attribute identifiers

Attribute properties

XACML categories

XACML datatypes

Attribute connectors section

Attribute connectors properties

Environment variables

Example of environment variables use

Constraints

Attribute cache section

Attribute cache properties

Decision parameters section

Deploy the authorization domain configuration file