Using YAML

Using YAML to configure Airlock IAM

The Airlock IAM configuration can be represented in a YAML format. Even if most of the configuration is expected to be designed using the Config Editor, the YAML configuration is important for configuration automation and management tasks. This article introduces the YAML config format and its complementary tools.

Introduction

YAML has been chosen as a basis for the IAM configuration because it is widely used for configuration automation tasks. Compared to the alternative XML configuration format (see Configuration management in Airlock IAM for a comparison), the YAML-based format is organized in a way to make it more readable and maintainable by both humans and code. This is especially true for hierarchical structures within the IAM configuration.

The YAML format covers all config management concepts like environments, contexts, and config variables. It is supported by the Config Editor and the config upgrade CLI tool.

 
Info

Recommendation: Use YAML instead of XML

Features supporting config automation (CLIs) and config modularization (snippets) only work with YAML. Upcoming config automation features are very likely to work only with YAML.

If using the XML format, it is recommended to migrate to the YAML format.

 
Example

Example (excerpt, simplified):

The full format specification can be found in YAML format specification.

type: TaskSchedule
id: Airlock2FA-letterTaskSchedule
displayName: Schedule for Airlock 2FA Activation Letters
properties:
  interval: never
  task:
    type: Airlock2FAActivationLetterOrderTaskConfig
    properties:
      languageContextDataName: language
      outputDirectory: instances/auth/pdfs
      renderer:
        type: WordTemplateReportRenderer
        properties:
          defaultTemplate: instances/common/report-templates/airlock-2fa-letter-de.docx
          saveOptions:
            type: PdfSaveActionConfig
            displayName: PDF Save Options with custom Fonts
            properties:
              fontsPath: instances/common/report-templates
          template:
          - pluginList:
            - type: LanguageSpecificReportTemplate
              properties:
                language: en
                template: instances/common/report-templates/airlock-2fa-letter-en.docx
      workingDirectory: instances/auth/pdfs/inwork
 
Notice

Short vs. long plugin type identifiers

Note that the above example contains short plugin types.

In Airlock IAM 8.4, fully-qualified class names are required as type identifiers (like com.airlock.iam.servicecontainer.app.application.configuration.TaskSchedule).

Short plugin type identifiers are supported as of IAM 8.5.

Enable YAML mode

An Airlock IAM instance is configured to use YAML or XML as a configuration format. The two formats cannot be mixed.

To enable YAML as the active configuration format, use the application parameter iam.config.format (instance.properties):

 
Example
## Defines the format to use for the plugin configuration file.
## If set to "xml", then Airlock IAM will read and write the config in XML format, using a file named "medusa-configuration.xml".
## If set to "yaml", then Airlock IAM will read and write the config in YAML format, using a file named "iam-config.yaml".
## Possible values: xml, yaml
iam.config.format = yaml

Alternatively, use the environment variable IAM_CONFIG_FORMAT=yaml when starting up Airlock IAM. If in YAML mode, Airlock IAM expects the main configuration to be in file iam-config.yaml within the instance directory (e.g. instances/auth/iam-config.yaml).

Migrating from XML to YAML

To migrate an XML file to YAML, a command-line tool (CLI) is provided. It can be used to migrate an IAM instance but can also be applied to single XML files outside an IAM instance. It is not possible to convert YAML back to XML.

To convert an IAM instance, use

 
Example
iam config convert -i auth

To convert a single XML file, use

 
Example
iam config convert -f medusa-configuration.xml -o iam-config.yaml

Please read the usage message (iam config convert -h) before using the CLI. Note that existing files may be overwritten and a config root directory may have to be provided as an argument.

 
Info

Note that after changing an IAM instance to YAML mode, the Config Editor only reads and writes YAML files. It may be worthwhile to convert the configuration history as well:

Apply the config migration CLI to the XML files in the instance's /workingcopies/ directory.

Upgrading IAM configuration files

To upgrade YAML configuration files from one version to the next, use the iam upgrade command-line tool. It works for both XML and YAML.

 
Example

Example: upgrade instance auth:

iam upgrade -c /home/airlock/iam -i auth
 
Example

Example: upgrade file iam-config.yaml:

iam upgrade -f iam-config.yaml