YAML format specification

This document describes the YAML configuration format for Airlock IAM. Using examples, it explains the syntax and the meaning of all supported configuration concepts for IAM configuration and snippet files.

General information

YAML version
The IAM YAML config format is based on YAML version 1.2.
YAML comments
Config files with YAML comments are valid and can be read by IAM components. However, YAML comments are not preserved when configuration files are written by IAM components. Use the comment attributes within the IAM YAML format instead (see below).
Lenient parsing vs. strict writing
Parsing YAML files is to some degree lenient: unquoted strings, arbitrary ordering of properties or plugins, or missing plugin IDs are accepted in some situations.
However, when IAM components - like the Config Editor or command-line tools - write YAML documents, they apply strict rules regarding the ordering of properties, plugins, and other elements. Moreover, missing plugin IDs are generated and strings are quoted where necessary.

Basic YAML document structure

The basic structure of Airlock IAM YAML config files is as follows:

Example

schemaVersion: iam.airlock.com/v1          # version of IAM YAML the format 
type: IamConfig                            # type of the configuration "IamConfig" or "IamSnippet"
metadata:                                  # metadata block with information about the configuration
  iamVersion: '8.4'                        # IAM product version the configuration is valid for
  history:                                 # Configuration history
    - datetime: 2025-02-05T12:34:56.123Z
      author: alice
      comment: Added passwordless flow
spec:                                      # The spec part contains the actual configuration
  - type: SomePluginType                   # See separate examples for more information about this part.
    id: somePluginId
    properties:
      prop1: value1
      prop2: value2

The spec part contains the actual configuration that defines Airlock IAM's behavior.

The spec is a list of plugin trees in the following defined order:

Top-level IAM modules (like Loginapp, Adminapp, etc.).
Plugin trees that are not directly connected to the top-level IAM modules (so-called unconnected plugins/plugin trees) and plugins that are only reachable via parent links (inheritance).

Example

This example shows an excerpt of an IAM configuration containing main settings (GlobalConfiguration), the settings for the Loginapp and the Adminapp, and two unconnected plugins.

schemaVersion: iam.airlock.com/v1
type: IamConfig
metadata:
  iamVersion: '8.4'
spec:
  # top-level IAM modules come first
  - type: GlobalConfiguration
    ...
  - type: Loginapp
    ...
  - type: Adminapp
    ...

  # "unconnected" plugins come after the IAM modules
  - type: ApplicationId
    ...
  - type: TaskSchedule
    ...

Each block starts with the type attribute and is configured as an IAM plugin. The inner structure of a plugin configuration is omitted in the above example and described in the next section.

YAML structure for an IAM plugin

The basic configuration unit in Airlock IAM is a plugin. A plugin configuration consists of some fixed YAML attributes (type, id, displayName, properties) and the property configuration itself, which depends on the plugin's type.

Consider the following plugin configuration example (configuring a password letter Word template):

Example

type: LanguageSpecificTemplate
id: passwordLetterTemplateEn
displayName: English Password Letter Template
comment: Letter template texts must be approved by marketing.  
properties:
  language: en
  template: instances/common/report-templates/password-letter-en.docx

Attribute	Description
`type` (mandatory)	Defines the type of the plugin. As of IAM 8.5, short names are used for plugin types, instead of fully-qualified Java class names. Notice For more information on short type names vs fully-qualified Java class identifiers, see Actions required when upgrading from IAM 8.4 to IAM 8.5.
`id` (optional)	A technical identifier that is used to refer to the plugin configuration. The `id` must be unique within a configuration. `id`s may consist of the following characters: `a`-`z`, `A`-`Z`, `0`-`9`, `-`, `_`, and `.` Valid examples: `myIden13`, `my_ident-13` Invalid example: `my Ident 13` References to the plugin may be within the configuration or also from configuration automation scripts or alike. Therefore, well-chosen IDs improve the readability of such scripts. As long as a plugin is not referred to, the `id` is optional. Note that an ID is automatically generated for each plugin once a configuration is written by an IAM component.
`displayName` (optional)	The `displayName` attribute holds a (typically) human-readable name of the plugin configuration. It is displayed in the Config Editor and improves the readability of the configuration. Display names must be unique within a configuration and they are optional. Note: IAM top-level plugins have a fixed display name that must not be changed. Currently, the following top-level module display names existed: `globalConfig`, `loginapp`, `adminapp`, `transaction-approval`, `api-policy-service`, `servicecontainerapp`.
`comment` (optional)	Optional comment. Favor this type of comment over YAML comments (starting with #): YAML comments are not displayed in the Config Editor and they are not preserved when IAM components write the configuration. The comment does not affect the behavior of the plugin.
`parentRef` (optional)	Used to refer to the parent plugin, if inheritance is used (see below). The parent plugin is referenced using its `id`.
`properties` (optional)	The `properties` attribute contains a YAML map of name-value pairs configuring the properties of the plugin. The names and types of the properties are defined by the plugin type and vary from plugin to plugin. Note that property values may themselves be plugins (also plugin lists or maps). See below for more information on this. If a plugin configuration has no properties, the `properties` attribute may be omitted. To get a list of properties for a plugin, refer to the plugin documentation in the Config Editor or the plugin reference (linked in this documentation).

Property values

Airlock IAM plugins have properties of different types. For example, there are booleans, integer numbers, and strings, but also properties referring to other plugins.

The following examples illustrate how the various types of IAM plugin properties are specified in the YAML config format.

Example

Simple properties

In general, simple properties are written as a string in YAML.

properties:

  # unquoted string value
  language: de
  resourceKey: mtan.payment.message

  # alternative representation of the same unquoted string value
  resourceKey:
  - value: mtan.payment.message   

   # quoted string values
  secretKey: '0x0000000000000000000000000000000000000000'
  pattern: '{digits:6}'

   # multiline string value
  languages: |-
    de
    fr
    en

   # numbers
  cacheTimeout: '5'
  maxRelative: '-6574'

   # boolean
  required: 'true'
  optional: 'false'

   # a list of simple values (e.g. strings or regex patterns)    languages:  
    - valueList:
        - de
        - en
        - fr
        - it 
  
   # alternative representation of the same list as above
  languages:
  - valueList: ['de', 'en', 'fr', 'it']

Note that strings can be provided without quotes but only as long as they can be interpreted as a string in a uniquely defined way. For example, the strings abc, true, and 2.4 can be specified without quotes. However, the strings '2e4' or 'TRUE' must be quoted, because they are ambiguous if unquoted. If in doubt, use quotes around strings.

Leading and trailing whitespace is removed (trimmed) from property values. Empty strings are treated as NULL values (no value). See below for NULL value representations.

Example

Properties with plugin values

Property types with plugins as values are represented as follows. How to make multiple references to a plugin is described further below and not part of this example.

properties:
 
  # plugin property with name "authenticationSettings"  
  authenticationSettings:
    type: SomePluginType
    # rest of the plugin configuration


  # alternative representation of the above plugin property
  authenticationSettings:
  - plugin:
      type: SomePluginType
      # rest of the plugin configuration

    
  # plugin list property with name "steps"
  steps:
    - pluginList:
        - type: SomePluginType
          # rest of the plugin configuration
        - type: SomePluginType
          # rest of the plugin configuration
 
  # plugin map property with name "valueProviders"
  valueProviders:
    - pluginMap:
        mapKey1:
          type: SomePluginType
          # rest of the plugin configuration
        mapKey2:
          type: SomePluginType
          # rest of the plugin configuration

Example

NULL values

To explicitly define NULL values (specifying the absence of a property value), the following syntax is used.

 properties:

   # simple property with explicit NULL value
   propertyName1: null

   # empty list (of simple properties)
   propertyName2:
   - valueList: []

   # plugin property with explicit NULL value
   propertyName3:
   - plugin: null

   # plugin list property with empty list
   propertyName4:
   - pluginList: []

   # plugin map property with empty map
   propertyName5:
   - pluginMap: {}

Info

Absent properties

If a property is not specified or explicitly specified as null, a default value may be used.

To find out whether and what default value is used, if a property is absent or null, refer to the plugin documentation in the Config Editor or the plugin reference (linked in this documentation).

Plugin trees and multiple references to plugins

The YAML document represents a tree (a hierarchical structure). Where the IAM configuration can be represented as a tree of plugins, it is represented in YAML accordingly. Consider the following example.

Example

# a simple plugin tree example
type: SomePluginType
id: topLevelNode
properties:
  child1:
    type: SomePluginType
    id: childNode1
  child2:
    type: SomePluginType
    id: childNode2
    properties:
      child21:
        type: SomePluginType
        id: childNode21
      child22:
        type: SomePluginType
        id: childNode22

However, in general, the Airlock IAM configuration is not a tree but a DAG (directed acyclic graph) because a plugin configuration may be referenced multiple times.

For example, the database connection settings are typically only defined once but referred to in several places in the configuration. To reflect this, the ref attribute is used:

The ref attribute allows referring to plugin configurations by their id.

Example

# use "ref" attribute to refer to plugin configurations
 type: SomePluginType
id: topLevelNode
properties:
  child1:
    type: SomePluginType
    id: childNode1
  child2:
    type: SomePluginType
    id: childNode2
    properties:
      child21:
        ref: childNode1
      child22:
        ref: childNode1

A plugin with a given id is defined once in the configuration and may be referred to multiple times using the ref attribute. This also works when referring to plugins in plugin lists or maps.

The id does not necessarily have to be defined before the ref. Forward references, i.e., referring to an ID defined later in the file is allowed. However, whenever an IAM component writes the configuration, it writes a plugin (with its id) first and refers to it in all subsequent occurrences of the plugin. A plugin may therefore “jump” up in the file when the configuration is written by IAM.

Inheritance (parents)

The concept of inheritance allows for reducing redundancy in the configuration by inheriting property values from a parent plugin and then overwriting specific values.

This concept is represented in YAML using the parentRef attribute as shown in the following example.

Example

type: SomePluginType
id: idOfTheParentPlugin
properties:
  propA: parentValueA
  propB: parentValueB
  
# use a parent plugin, inherit all its properties and overwrite one of them
type: SomePluginType
id: idOfTheChildPlugin
parentRef: idOfTheParentPlugin
properties:
  propB: childValueB

Note that it is possible, using NULL values, to undefine a property value in a child even if the parent specifies a value.

Configuration contexts, environments, and variables

In IAM each property value may be associated with a configuration context, a configuration environment, a configuration variable, or a combination of them. The examples below show how these concepts are represented in YAML.

For an explanation of the concepts themselves, refer to separate sections of this documentation.

Example

Configuration contexts, environments, and variables for simple properties.

# a simple property with a combination of values depending on context, environment, and variables
properties:
  sessionIdleTimeout:
    # property value with a variable marked as sensitive (no context, no environment)
    - value: 13m
      var:
        name: SESS_TIMEOUT
        sensitive: true
    # property value for context ctxA
    - value: 17m
      context: ctxA
    # property value for environment prod
    - value: 19m
      env: prod
    # property value for environment prod and context ctxA and a variable
    - value: 23m
      env: prod
      context: ctxA
      var:
        name: SESSIONTIMEOUT

Example

Configuration contexts, environments, and variables for a property with a simple value list.

# list of simple values with a combination of values depending on context, environment, and variables
properties:
  validLanguages:
    # property value with a sensitive variable (no context, no environment)
    - valueList:
        - de
        - en
      var:
        name: LANGDEF
        sensitive: true
    # property value for context ctxA
    - valueList:
        - de
        - fr
      context: ctxA
    # property value for environment prod
    - valueList:
        - de
        - en
        - fr
      env: prod
    # property value for environment prod and context ctxA and a variable
    - valueList:
        - de
        - it
      env: prod
      context: ctxA
      var:
        name: LANGSPEC

Example

Configuration contexts, environments, and variables for a property with a plugin as value:

# a plugin property with a combination of values depending on context, environment, and variables
properties:
  sqlDataSource:
    # property value with a sensitive variable (no context, no environment)
    - plugin:
        ref: defaultDbConnection
      var:
        name: DBCONDEF
        sensitive: true
    # property value for context ctxA
    - plugin:
        ref: dbConnectionForContextA
      context: ctxA
    # property value for environment prod
    - plugin:
        ref: dbConnectionForEnvProd
      env: prod
    # property value for environment prod and context ctxA and a variable
    - plugin:
        ref: dbConnectionForEncProdAndContextA
      env: prod
      context: ctxA
      var:
        name: DBCONSPEC

Example

Configuration contexts, environments, and variables for a property with a plugin list as value:

# a plugin list property with a combination of values depending on context, environment, and variables
properties:
  steps:
    # property value with a sensitive variable (no context, no environment)
    - pluginList:
        - ref: firstStepPluginId
        - ref: secondStepPluginId
      var:
        name: FLOWSTEPSDEV
        sensitive: true
    # property value for context ctxA
    - pluginList:
        - ref: firstStepPluginId
        - ref: secondStepForContextA
      context: ctxA
    # property value for environment prod
    - pluginList:
        - ref: firstStepPluginId
        - ref: secondStepForEnvProd
      env: prod
    # property value for environment prod and context ctxA and a variable
    - pluginList:
        - ref: firstStepPluginId
        - ref: secondStepForEnvProdAndContextA
      env: prod
      context: ctxA
      var:
        name: FLOWSTEPSSPEC

Example

Configuration contexts, environments, and variables for a property with a plugin map as value:

# a plugin map property with a combination of values depending on context, environment, and variables
properties:
  valueProviders:
    # property value with a sensitive variable (no context, no environment)
    - pluginMap:
        new_email:
          ref: emailValueProviderDefault
      var:
        name: VALUEPROVIDERSDEF
        sensitive: true
    # property value for context ctxA
    - pluginMap:
        new_email:
          ref: emailValueProviderForContextA
      context: ctxA
    # property value for environment prod
    - pluginMap:
        new_email:
          ref: emailValueProviderForEnvProd
      env: prod
    # property value for environment prod and context ctxA and a variable
    - pluginMap:
        new_email:
          ref: emailValueProviderForEnvProdAndContextA
      env: prod
      context: ctxA
      var:
        name: VALUEPROVIDERSSPEC

Sensitive values and externally stored secrets

Sensitive values are represented in YAML as shown in the following example:

Example

# different ways to represent sensitive values in YAML
properties:
  # a plain secret
  password1: thisIsMyNotSoSecretPassword
  # an obfuscated (not encrypted) secret
  password2: '[OBFUSCATED]3/rzKUNND/4LElZhvcm8sNFaMXrBjLQtoNevU5BJVnk='
  # a reference to an externally stored secret
  password3:
    - value:
        storageId: idInExternallyStoredSecret
  # same as above but in combination with a configuration context
  password4:
    - value:
        storageId: idInExternallyStoredSecret
      context: ctxA

Further information and links

Internal links

External links

https://yaml.org/spec/1.2.2/