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.
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).
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.
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 `- |
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)
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.
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.
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.
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) |
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.