Using a YAML-format domain configuration file
The YAML-format authorization domain configuration file contains several sections. You can use any text editor to create and edit the YAML-format domain configuration file. (See yaml.org, for more information about the format.)
Some images in this section only show detail views of the domain configuration sections. For a complete view, see the sample domain configuration file included in the appendix Sample domain.
The identity section
The identity property holds a string identifying the domain. The 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 a good practice to update it every time you change the domain configuration.
ADS will not start if the identity property is not set.
identity: domain_identification_1234
Identity section example
identity:
A single, case-sensitive string 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
The metadata section
This is an optional section where metadata for tooling and domain management workflow processes can be stored. Any number of fields can be added to the section.
metadata:
status: published
approvedBy: Bob
Metadata section example
metadata:
This object marks the start of the Metadata section of the domain configuration file.
<Metadata key>:
The key must be a string without spaces or non-printable characters.
<Metadata value>
The value can be an arbitrary 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 ignore the contents of the metadata field except for the purpose of validating its structure.
The policy section
This section contains the authorization policies, expressed as a list of XACML policies and/or policy sets.
Any software tool, including plain text editors, with which you can produce XACML 3.0 compliant policies can be used.
There are three tools provided in the Axiomatics Policy Server Product that you can use to create policies: the Policy Editor within ASM, the Policy Administration Point (PAP), and the Axiomatics Language for Authorization (ALFA) plugin and compiler.
ADS will not start if the domain configuration file lacks a policy.
This section is structured as follows:
policy:
This object marks the start of the Policy section of the domain configuration file.
mainPolicyId:
There must be a designated main policy, or root policy, as a starting point for the evaluation process. This field must contain a reference to the ID of the policy or policy set in the subsequent list of policies that will serve as the main policy.
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:
This field contains the actual policy specifications in a list format. Create an entry in the list by typing a dash (-) and then a pipe (|), and then paste in the XML-format policy or policy set.
Be careful to follow the indentation rules for lists in YAML when you add policy specifications, that is, an indentation of at least one more character than the list dash. (See the figure below.)
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.
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.
The attributes section
An attribute is identified by a string called an attribute identifier. An attribute identifier needs to be associated with a XACML quadruple made up of a XACML identifier, a category, a data type, and an issuer, which is the way XACML defines attributes. This is 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.
attributes:
role:
xacmlId: com.acme.user.role
category: AccessSubject
datatype: string
issuer: Acme Inc.
resourceId:
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
attributes:
This object marks the start of the Attributes section of the domain configuration file.
<Attribute identifier>:
A short and simple name for the attribute, 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
Reserved words
xacmlId:
A URI representing the XACML identifier (or attribute ID) of the attribute, for example, com.acme.user.role.
category:
A string declaring which category the attribute belongs to. For example, urn:oasis:names:tc:xacml:1.0:subject-category:access-subject.
To simplify refer to standard categories, it is possible to use either the full XACML category URI or a short name.
Both category: Resource and category: "urn:oasis:names:tc:xacml:3.0:attribute-category:resource" refer to the urn:oasis:names:tc:xacml:3.0:attribute-category:resource category. The shorthand notation is translated to the full XACML URI when read from the configuration file.
| 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 specification.
Any other strings are understood to refer to custom categories, which are created using the anyURI format.
datatype:
The XACML data type of the attribute. To simplify refer to common data types, it is possible to use either the full XACML category 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.
| 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 specification. Any other strings are understood to refer to custom datatypes, which are created using the anyURI format.
issuer:
The issuer of the attribute, such as a person or a department. This field is optional, but if used it must have a value.
The 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:
employee_database#1:
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)
attributeConnectors:
This object marks the start of the Attribute Connectors section of the domain configuration file.
<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
className:
The class name of the attribute connector, that is, the fully qualified name of the class that implements the attribute connector.
provides:
This is 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 a pipe (|), and then enter or paste in the data. The configuration data following the pipe (|) is sent as is to the attribute connector at initialization. The validation performed by ADS does not check whether the configuration string works or not.
Using environment variables for sensitive data
Properties can be configured using environment variables, for example, for 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.
The example shows an attribute connector that uses an environment variable to set the connection information in the configurationString.
The syntax is: ${<environment variable name>:-<default value>}.
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
If an attribute connector declares that it provides an attribute with data there must be a corresponding attribute definition in the Attributes section of the domain configuration. Also, duplicate attribute connector identifiers are not allowed for attribute connectors.
The attribute cache section
To improve performance, attribute values fetched from attribute connectors can be cached. This is an optional configuration, but if enabled both fields, timeToLive and maxItems, must have a value for the configuration to be valid. If attribute caching is not enabled, the attribute connector will be queried for every attribute access.
attributeCache:
<Attribute identifier>:
timeToLive: 5000 seconds
maxItems: 100
Attribute Cache section example
attributeCache:
This object marks the start of the Attribute Cache section of the domain configuration file.
<Attribute identifier>:
The attribute identifier (or name) of the attribute 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. If that is not done, ADS will not start.
timeToLive:
This field indicates the maximum length of time a cached item exists in the attribute cache. The value for the timeToLive duration must be expressed as an integer number and a time unit. Time units can be expressed in the following ways:
second: s, second, seconds minute: m, min, mins, minute, minutes hour: h, hour, hours day: d, day, days
The time to live value should be set based on how often the data is changed. You also need to consider what is a satisfactory balance between speed (cached data loads faster) and content freshness (data cached for too long can become stale).
A cached item expires when it has passed its time to live value. The attribute connector has to be queried again to update the cache.
maxItems:
This field indicates the maximum number of attribute values that will be stored per attribute. The minimum value is 1.
When the maxItems value is reached, items are evicted according to the least recently used (LRU) policy.
- Try to estimate what the size of the cache would be if the maximum number is reached and make sure that your system has the memory capacity required to hold the cache.
The higher the number of values stored, the greater the RAM requirements. The type of attribute data also has an influence on the memory requirements of the cached data. For example, consider the possible size difference between attribute data that consists of 1000 integers compared with 1000 variable length strings.
The 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:
partialEvaluationThreshold: 2
Decision Parameters section example
decisionParameters:
This object marks the start of the Decision Parameters section of the domain configuration file.
partialEvaluationThreshold:
The threshold indicates how many individual requests a multiple-decision request should contain before ADS attempts to optimize that specific multiple request.
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.
Deploying 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.