Using Configuration Expressions in Exported Configuration Files

Working With Expressions

Expressions share their syntax and underlying implementation with other ForgeRock Identity Platform components. Expressions have the following characteristics:

Amster defines the following expressions by default:

Expression Evaluation and Order of Precedence

You must define expression values before importing the configuration into AM. When evaluated, an expression must return the appropriate type for the configuration property. For example, the smtp.port property takes an integer. If you set the property using an expression, the result of the evaluated expression must be an integer. If the type is wrong, AM may fail to start after a configuration import, with unexpected errors. For more information about data type coercion, see "Transforming Data Types".

Amster can obtain expressions from the following sources:

The following list reflects the order of precedence:

Transforming Data Types

By default, when configuration tokens are resolved, the result is always a string. However, when evaluated, an expression must return the appropriate type for the configuration property. For example, the smtp.port property takes an integer. If you set the property using an expression, the result of the evaluated expression must be an integer. If the type is wrong, AM may fail to start after a configuration import, with unexpected errors.

You can transform the output type of the evaluated token to match the type that is required by the property. Amster can coerce expressions to resolve as the following types:

To convert the value of a property into a different type in the exported configuration file, specify the new type as follows:

"port" : {
    "$int" : "&{smtp.port}"
}

You can also replace configuration values with the contents of a file by using the $inline coercion function. You can specify the path to the file, or replace it with an expression. For example:

{
 "message" : {
    "$inline" : "&{config.path}/emailcontent.txt"
 },
 "message2" : {
    "$inline" : "/path/to/emailcontent.txt"
 }
}

Consider the following points when using the $inline coercion function:

Expression Example Files

This section contains an example expression file and some excerpts of exported configuration files with expressions inserted in them.

Expression File

 {
   "env" : {
      "name" : "DEV"
   },
   "oauth" : {
      "authmodule" : {
         "issuer" : "dev-oathissuer.example.com",
         "authlevel" : 2,
         "checksum" : "true"
      },
      "devprof" : {
         "kstore" : {
            "path" : "&{product.install.dir}/&{env.name}/keystore.jceks",
            "type" : "JCEKS",
            "encpas" : "AAAAA0FFUwIQ1WDDMsxGoZMiRHhDQ+ywUfTMdGtYqEsvZZLV9W8ygfHi/5kBWjMpyg=="
         }
      }
   }
}

As well as configuration details, such as hostnames and ports, passwords and secrets are likely to differ between AM instances.

The previous example demonstrates an expression file tailored for the development environment. Note how the &{devprof.kstore.encpas} expression holds the value of the encrypted keystore password for the OAuth device profile keystore configuration.

For security reasons, Amster only exports passwords in configuration files if the transport key exists in AM's keystore.

If your environments have different passwords, you could manage passwords using expressions as follows:

Using this technique ensures that the passwords for all the environments are properly encrypted. You can safely create expression files by environment with the appropriate values.

Configuration File Excerpts

{
   "data":{
      "_id":"",
      "defaults":{
         "oathIssuerName":"&{oath.authmodule.issuer}",
         "totpTimeStepsInWindow":2,
         "authenticationLevel":{
            "$int":"&{oath.authmodule.authlevel}"
         }
      },
      "passwordLength":"6",
      "addChecksumToOtpEnabled":{
         "$bool":"&{oath.authmodule.checksum}"
      }
   },
   "data":{
      "_id":"",
      "defaults":{
         "oathAttrName":"oathDeviceProfiles",
         "authenticatorOATHDeviceSettingsEncryptionKeystorePrivateKeyPassword":null,
         "authenticatorOATHDeviceSettingsEncryptionScheme":"NONE",
         "authenticatorOATHDeviceSettingsEncryptionKeystore":"&{oath.devprof.kstore.path}",
         "authenticatorOATHDeviceSettingsEncryptionKeystoreType":"&{oath.devprof.kstore.type}",
         "authenticatorOATHDeviceSettingsEncryptionKeystorePassword":null,
         "authenticatorPushDeviceSettingsEncryptionKeystorePassword-encrypted":"&{oath.devprof.kstore.encpas}",
         "authenticatorOATHDeviceSettingsEncryptionKeystoreKeyPairAlias":null,
         "authenticatorOATHSkippableName":"oath2faEnabled"
      }
   },
   "data":{
      "_id":"01e1a3c0-038b-4c16-956a-6c9d89328cff",
      "name":"Authentication Tree Decision Node Script &{env.name}",
      "description":"&{product.install.dir}/&{env.name}/authdecisionnode_desc.txt",
      "script":{
         "$base64:encode":{
            "$inline":"&{product.install.dir}/&{env.name}/scripted-decision.groovy"
         }
      }
   }
}

Note how the files used by the $inline coercion function are stored under a directory that is referenced by the &{env.name} expression. For example:

"$inline":"&{product.install.dir}/&{env.name}/scripted-decision.groovy"

This is just an example of how you can separate your configuration files by environment.