Property Value Substitution

Many property values in ForgeRock’s canonical CDK configuration profile are specified as configuration expressions instead of as hard-coded values. Fully-qualified domain names (FQDNs), passwords, and several other properties are all specified as configuration expressions.

Configuration expressions are property values in the AM and IDM configurations that are set when AM and IDM start up. Instead of being set to fixed, hard-coded values in the AM and IDM configurations, their values vary, depending on conditions in the run-time environment.

Using configuration expressions lets you use a single configuration profile that takes different values at run-time depending on the deployment environment. For example, you can use a single configuration profile for development, test, and production deployments.

In the ForgeRock Identity Platform, configuration expressions are preceded by an ampersand and enclosed in braces. For example, &{am.encryption.key}.

The statement, am.encryption.pwd=&{am.encryption.key} in the AM configuration indicates that the value of the property, am.encryption.pwd, is determined when AM starts up. Contrast this with a statement, am.encryption.pwd=myPassw0rd, which sets the property to a hard-coded value, myPassw0rd, regardless of the run-time environment.

How Property Value Substitution Works

This example shows how property value substitution works for a value specified as a configuration expression in the AM configuration:

  1. Search the /path/to/forgeops/config/7.0/cdk directory for the string &{.

  2. Locate this line in your search results:

    "am.encryption.pwd=&{am.encryption.key}",

    Because the property am.encryption.pwd is being set to a configuration expression, its value will be determined when AM starts up.

  3. Search the forgeops repository for the string AM_ENCRYPTION_KEY. You’ll see that the secret agent operator sets the environment variable, AM_ENCRYPTION_KEY. The property, am.encryption.pwd, will be set to the value of the environment variable, AM_ENCRYPTION_KEY when AM starts up.

Configuration expressions take their values from environment variables as follows:

  • Uppercase characters replace lowercase characters in the configuration expression’s name.

  • Underscores replace periods in the configuration expression’s name.

For more information about configuration expressions, see Property Value Substitution in the IDM documentation.

AM and IDM Differences

There are several subtle but important differences between the AM and IDM implementations of configuration expressions:

  • Canonical configuration profile.

    AM: Contains configuration expressions for usernames, passwords, FQDNs, and the URL access protocol.

    IDM: Contains configuration expressions for usernames, passwords, FQDNs, the URL access protocol, and additional properties.

  • Administration console handling of configuration expressions.

    AM: The console is not aware of configuration expressions. Values specified as configuration expressions in configuration profiles are displayed as run-time values in the console. You cannot specify property values as configuration expressions in the console.

    IDM: The Admin UI is aware of configuration expressions. Values specified as configuration expressions in configuration profiles are displayed as configuration expressions in the Admin UI. You can specify property values as configuration expressions in the Admin UI.

  • Export configuration behavior.

    AM: Configuration expressions are reinserted into the AM configuration, overriding hard-coded property values you might have set using the console.

    IDM: Configuration expressions are exported to the IDM configuration profile.

  • Replacing a hard-coded property value with a configuration expression.

    AM: Edit the AM configuration manually, replacing a property value with a configuration expression. Then, open the /path/to/forgeops/docker/7.0/am-config-upgrader/rules/placeholders.groovy file and add a rule that preserves the new configuration expression.

    IDM: Change the property’s value to a configuration expression in the Admin UI. When the configuration is exported, the exported configuration contains the configuration expression.

  • Replacing a configuration expression with a hard-coded property value.

    AM: Edit the AM configuration manually, replacing a configuration expression with a hard-coded property value. Then, open the /path/to/forgeops/docker/7.0/am-config-upgrader/rules/placeholders.groovy file and remove the rule that preserved the configuration expression you replaced.

    IDM: Hard-code the property’s value in the IDM Admin UI. When the configuration is exported, the exported configuration contains the hard-coded property value.

  • Configuration expressions' run-time values.

    AM: Configuration expressions get their values from environment variables.

    IDM: Configuration expressions can get their values from a variety of sources: environment variables, Java system properies, and configuration files.