Using environment variables in the IAM configuration

Configuration variables make it possible to outsource parts of the configuration to environment variables. Configuration variables are resolved at configuration activation time during the startup of Airlock IAM. This way, it is possible to include values in the IAM configuration that are not yet available when creating the configuration.

Configuration environments vs. configuration variables

Some use cases of the configuration variables feature overlap with applications of the Configuration environments feature.

• The main difference between the two features are:
• Using the configuration environment feature, environment-specific values for all environments are stored in the IAM configuration file medusa-configuration.xml. The environment-specific values, therefore, need to be known at configuration time.
• Values are assigned to configuration variables at start-up time during configuration activation and do not have to be known at configuration time. Moreover, they are not stored in the IAM configuration file medusa-configuration.xml.

• Configuration variables are, for example, used in the following scenarios:
• Dynamic config values – Use of values in the IAM configuration that are dynamically determined at startup time and not available when editing the configuration.
• Staging or multi-tenancy – Separate stage- or tenant-specific values from the IAM configuration. Keeping such values in a list of variables with sensible names makes it easy to diff them.
• Avoid redundancy – Use of values from the environment that would have to be stored in and kept in synch with the environment and in the IAM configuration. Use config values from Kubernetes config maps.
• Deployment automation – In general, configuration variables make deployment automation easier.

This list is not exhaustive.

• In general, configuration variables work as follows.
• Step 1 – Define configuration variables on IAM configuration properties using the Config Editor.
• Step 2 – Define environment variables with the values to be assigned to the configuration variables.
• Step 3 – During IAM startup, the values from the environment variables are used in the configuration.

For a detailed configuration example, see the steps below.

To define configuration variables, use the Config Editor.

Enabling configuration variables in the Config Editor

• The Config Editor's configuration variable feature is disabled by default. It can be enabled as follows:
• In the instance configuration, e.g., instances/auth/instance.properties set the property iam.config-editor.show-variables to true.
• Stop and restart the IAM instance.

copy

## Whether configuration variables are displayed 
##  and editable in the Config Editor.
iam.config-editor.show-variables = true

0. To define a configuration variable for a configuration property, proceed as follows:
1. Open the corresponding plugin in the Config Editor.
2. Click on the ⁺v button on the right of the property you wish to define a variable for. A dialog opens.
   
   
    
3. In the dialog, define the name of the configuration variable.
   
   
    
4. Enable the checkbox Sensitive value (masked in logs) if the value(s) assigned to the variable must not be written to the log file.
   Typically, sensitive credentials such as passwords must not be logged.
5. Click the Save button to store the variable name.
6. The variable is now defined and may be used. A red v indicates that a variable is defined for the property. The property is also listed in the Variables tab in the lower part of the Config Editor.
   
   
    

The XML representation of the example from the above screenshots is as follows:
<property name="skin" var="SKIN_COLOR">green</property>

Why are there configuration properties without ⁺v?

The ⁺v symbol used to define a configuration variable is only available on properties that explicitly have a value set. It is neither available for properties using the default value of the product (marked with the D) or inheriting the value from another plugin nor for undefined properties. See Plugin properties for further information on undefined and defined properties.

• To define a configuration variable for a property without the ⁺v:
• For default values, explicitly specify a value - the D is then not displayed anymore.
• For inherited values, click the icon used to override the inherited value.

Values that are assigned to the variables when IAM is starting up are defined in environment variables.

0. There are various ways to define environment variables for the IAM process:
1. In shell scripts starting Airlock IAM.
   export SKIN_COLOR=green
2. In systemd service files. See Customizing systemd services.

Environment='SKIN_COLOR=green'

3. Using a Kubernetes config map.
4. Using docker CLI or docker compose as described in Application parameters as environment variables.
5. Using other OS-related means.

The above examples only showed how to set a variable value for a simple property using a string, e.g. green. The following table shows how to set variable values for all supported property types.

Airlock IAM reads, validates, and activates the configuration when starting up. During this process, values from environment variables are assigned to configuration values.

0. For each configuration variable, IAM does the following:
1. Read the value for the variable from the environment.
2. If a value is defined, it is used in the corresponding property.
3. If no value is defined, the value from the configuration is used as if no variable was present.

After assigning values to the variables, the configuration is validated and variable usage is logged in the log output of the IAM module. The following example log message shows the usage of three configuration variables. The middle one is marked to be sensitive and its value is not logged in plain.

The following environment variables have been used in the current configuration:
 
FUTURAE_SERVICE_SETTINGS = Futurae Test Account Settings for Airlock
SERVICE_CONTAINER_SECRET = ***(masked)***
SKIN_COLOR = green

The configuration variables feature has the following functional limitations.

Configuration validation

Values assigned to the configuration variables are not known in the Config Editor. Thus, an IAM configuration that is valid in the Config Editor is not guaranteed to be valid after variables have been applied. Configuration activation at startup time may therefore fail.

Configuration migration

IAM automatically migrates configuration files when upgrading (Upgrade Airlock IAM). Manual steps may be possible if using configuration values for migration steps that depend on configuration values.

Since the values for the configuration variables are not known during configuration migration, the migration process cannot rely on these values.

If using configuration variables, carefully pay attention to the output of the configuration migration process - the iam upgrade command - and look for messages regarding configuration variables.

Limited to main IAM configuration (XML)

Configuration variables can only be used in the main IAM configuration file medusa-configuration.xml and do not apply to other artifacts like the instance configuration or SAML metadata files.