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
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
etc/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 etc/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 etc/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.