Property value substitution

For file-based configurations, property value substitution lets you create similar deployments, with environment-specific variations. For example, you might use property value substitution to specify different scripts and passwords for development, staging, and production environments. You might also use this feature to easily rotate configuration values, such as secrets.

Property value substitution uses configuration expressions to introduce variables into the server configuration. You set configuration expressions as the values of configuration properties, for example:

{
    "attribute" : "configuration-expression"
}

Only property values can be substituted, not the property names. The values can be set as follows:

As advanced server properties
As Java system properties on server startup
As environment variables

Properties values are evaluated with the following order of precedence, from greatest to least:

Environment variables
Java system properties
Server properties
Hardcoded property values

If you are using a file-based configuration, you should use external application and policy stores, especially if you have enabled dynamic client creation.
The following properties cannot be used with substituted values:
- Realm properties, such as the realm alias.
- SAML configuration properties.
- OAuth2 client configuration properties.
- Agent configuration properties.
- Tree configuration (tree name, nodes in tree, and so on). Configuration within each node can be substituted.

When you change configuration property values, the old value remains in effect until the affected service is restarted. To avoid having to restart AM when you change a substituted property value, you can clear the configuration cache and force the new property value to take effect.

Enable property value substitution

Property value substitution is disabled by default. To enable it, set the following advanced property, or the associated Java system property: org.forgerock.openam.core.sms.placeholder_api_enabled. This property takes the following values:

ON enables property value substitution for all property types.
STRING_ONLY enables property value substitution for properties with string values only.
OFF disables property value substitution.

Configuration expressions

To distinguish configuration expressions from static configuration values, the expression is preceded by an ampersand and enclosed in braces. For example, to set the account from which emails are sent, you could define a configuration expression such as &{email.from.address}.

To set a default value in a configuration expression, include it after a vertical bar. For example, the following expression sets a default email address: &{email.from.address|admin@example.com}. With this configuration, the server attempts to substitute the mail address with a defined configuration expression value. If no value is found, the server uses the default value, admin@example.com.

If you do not set a value for the configuration expression, and no default value is present, you will see an error similar to the following on startup:

Invalid config: Unable to evaluate the placeholder substitution.

A configuration property can include a mix of static values and expressions. For example, if you set hostname to am, then &{hostname}.example.com evaluates to am.example.com.

Configuration expression evaluation is recursive. For example, if you set the value of the port property to &{port.prefix}389, and set port.prefix to 2, then &{port} evaluates to 2389.

Transform data types

When configuration expressions are resolved, the result is always a string. However, you can transform or coerce the output type of the evaluated expression to match the type that is required by the property.

You transform a property’s data type by setting the $type before the property value, for example, "$int" : "&{expression}".

This functionality is not currently available through the UI.

The following coercion types are supported:

array ($array)

Transforms an array such as this:

{
    "properties" : {
        "$array" : "[\"prop1\", \"prop2\"]"
    }
}

to an array:

{
    "properties" : ["prop1", "prop2"]
}

boolean ($bool)

Transforms a string to a boolean.

decodeBase64 ($base64:decode)

Transforms a base64-encoded string into a decoded string.

encodeBase64 ($base64:encode)

Transforms a string into a base64-encoded string.

inline ($inline)

Takes file content that is too large to be written directly into a JSON file. The file can be a relative path to the current location.

For example, if the content at /path/to/myTemplate contains an email template, the following transformation:

{
    "attribute" : {
        "$inline" : "/path/to/myTemplate"
    }
}

would be converted to:

{
    "attribute" : "This content contains an email template that is too large\nto be written directly into a JSON file.\n"
}

integer ($int)

Transforms a string to an integer.

list ($list)

Transforms a list such as this:

{
    "properties" : {
        "$list" : "prop1,prop2"
    }
}

to an array:

{
    "properties" : ["prop1", "prop2"]
}

number ($number)

Transforms integers, doubles, longs, and floats.

object ($object)

Transforms a JSON object such as an encrypted password.

string ($string)

Transforms the property to a string value.

Example: Type Coercion to Integer

This example sets the value of the port in the email service configuration and transforms the value to an integer when it is evaluated:

{
    ...
    "port" : {
        "$int" : "&{smtp.port|587}",
    },
    ...
}

With this configuration, the server evaluates the email port property to the integer specified in the property resolver. If the server does not find a configuration expression for the port, it substitutes the default (587).

Property value substitution is not supported for MAP type attributes.

Property substitution and passwords

Passwords that are input through the UI are always encrypted. If property value substitution is enabled, variables for password properties must include the "$string" prefix. For example:

"myPassword": { "$string": "&{admin.password}" }

If you use a substituted property without this prefix, the value is encrypted and is not assessed as a substituted property. Values for properties that include $string are not encrypted and are resolved when used.

Try out property value substitution

ForgeRock provides a Postman collection to configure AM, and to run the REST requests that demonstrate property value substitution.

Download and install Postman.
Download the ForgeRock AM Configuration Postman Collection.
Import the collection to Postman:
- Go to File > Import … > Upload Files.
- Select the collection you downloaded, and click Open. Then, click Import.
Change the collection variables to suit your environment:
- On the Collections tab, select the ForgeRock AM Configuration Collection.
- Click on the Variables tab, and change at least the value of the following variables:
  - URL_base
  - admin_password
- Click Update to save your changes.
  
  You are ready to run the collection.

AM 7.3.1