About 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:

Search the /path/to/forgeops/config/7.0/cdk directory for the string am.encryption.pwd.

$ grep -Ri "am.encryption.pwd"

./am/config/services/realm/root/iplanetamplatformservice/1.0/globalconfig/default/com-sun-identity-servers/server-default.json:      "am.encryption.pwd=&{am.encryption.key}",

Notice the 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.
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.

Export utilities and configuration expressions

This section covers differences in how forgeops repository utilities export configuration that contains configuration expressions from a running CDK instance.

In the IDM configuration

The IDM admin UI is aware of configuration expressions.

Passwords specified as configuration expressions in the IDM admin UI are stored in IDM’s JSON-based configuration files as configuration expressions.

IDM static configuration export

The forgeops repository’s bin/config export idm command exports IDM static configuration from running CDK instances to your forgeops repository clone. The config utility makes no changes to IDM static configuration; if properties are specified as configuration expressions, the configuration expressions are preserved in the IDM configuration.

In the AM configuration

The AM admin UI is not aware of configuration expressions.

Properties cannot be specified as configuration expressions in the AM admin UI; they must be specified as string values. The string values are preserved in the AM configuration.

AM supports specifying configuration expressions in both static and dynamic configuration.

AM static configuration export

The forgeops repository’s bin/config export am command exports AM static configuration from running CDK instances to your forgeops repository clone. All AM static configuration properties in the CDK, including passwords, have string values. However, after the config utility copies the AM static configuration from the CDK, it calls the AM configuration upgrader. The upgrader transforms the AM configuration, following rules in the config/am-upgrader-rules/placeholders.groovy file.

These rules tell the upgrader to convert a number of string values in AM static configuration to configuration expressions. For example, there are rules to convert all the passwords in AM static configuration to configuration expressions.

You’ll need to modify the config/am-upgrader-rules/placeholders.groovy file if:

You add AM static configuration that contains new passwords.
You want to change additional properties in AM static configuration to use configuration expressions.

An alternative to modifying the config/am-upgrader-rules/placeholders.groovy file is using the jq command to modify the output from the config utility.

AM dynamic configuration export

The forgeops repository’s bin/amster export command exports AM dynamic configuration from running CDK instances to your forgeops repository clone. When dynamic configuration is exported, it contains properties with string values. The amster utility transforms the values of several types of properties to configuration expressions:

Passwords
Fully-qualified domain names
The Amster version

The Secret Agent configuration computes and propagates passwords for AM dynamic configuration. You’ll need to modify the kustomize/base/secrets/secret_agent_config.yaml file if:

You add new AM dynamic configuration that contains passwords to be generated.
You want to hard code a specific value for an existing password, instead of using a generated password.

Limitations on property value substitution in AM

AM does not support property value substitution for several types of configuration properties. Refer to Property value substitution in the AM documentation for more information.

ForgeOps