Keysafe Original User Guide
Arabella Kochanski
Amster is a command-line interface built upon the ForgeRock Access Management REST interface. Use Amster in DevOps processes, such as continuous integration, command-line installations, and scripted cloud deployments.
Encryption of Sensitive Data. Amster can encrypt exported password and sensitive data in the configuration files that are stored on disk. Only a correctly configured AM instance with the required transport key installed is able to decrypt and import the values.
Amster requires a Java developer environment. Check the output of the java -version command to make sure your version is supported according to "Java Requirements" in the Release Notes.
When a command does not proceed as expected, it can sometimes be helpful to start the amster command in debug mode and try again. To activate debug mode, start the amster command using the -d flag. For example:
To establish an interactive connection with AM, Amster makes use of the default authentication chain for administrator users configured in the AM instance. To locate this property, log in to AM and navigate to Realms > Top Level Realm > Authentication > Settings > Core.
The ldapService authentication chain, configured by default after AM installation, requires a valid user in AM. Log in as an administrative user, for example amadmin, to perform operations such as export and import of the configuration.
Amster can connect to an AM instance by using a private key pair and an authentication module and a chain in AM. The private key must be available to the Amster client, and the AM instance must trust the client IP address and have the public key in its authorized_keys file. Successful connections create an amAdmin session in AM.
The Forgerock Amster authentication module in the Top Level Realm. The module is enabled by default in new AM installations and disabled by default when upgrading an existing AM. For more information on how to configure this module, see "Amster Authentication Module Properties".
Holds the public keys of trusted Amster clients. AM check incoming Amster connections against these trusted keys. By default, contains a copy of the public key of a generated key pair that Amster can use.
To import and export encrypted password values in the configuration files you must generate a transport key, and install it in the keystore of each AM instance that you will be transporting passwords between.
The presence of the transport key causes additional fields containing encrypted password values to appear in the exported configuration files. These additional fields have a -encrypted suffix, as shown below:
Run the keytool command, specifying the location of the .storepass file as the password to use for the keystore and the location of the .keypass file as the password to use for the key aliases:
This command exports the transport key to a temporary keystore file /path/to/openam/openam/transport_keystore.jceks, and set a store and key password of myTransp0rtK3yP4ssword. You need to use these temporary passwords when importing to the target instance.
This command imports the transport key from the temporary keystore file /path/to/openam/openam/transport_keystore.jceks into the AM keystore, and set the transport key password to match the password used by the target keystore.
The presence of the transport key includes encrypted passwords in requests made by an administrative user, causing significant performance degredation. You MUST delete the transport key when imports and exports have been completed.
You must ensure that each external datastore configured in the source instance has an equivalent datastore available and running before importing Amster configuration into the destination AM instance.
For production environments, you can specify an external configuration store. Configuring AM to use an external configuration store also requires an external identity store, which will use the specified configuration store by default, unless otherwise specified.
When installing AM locally to Amster, Amster stores AM's configuration in the home directory of the user that is running the amster command. For example, for the tomcat user, the configuration is stored in /path/to/tomcat_home/openam.
As part of the site installation with embedded configuration store, Amster configures the new configuration store to replicate the data from the configuration store defined in the dsEmbReplHost2 option.
The cookie domain is specified in the --cookieDomain option. When unspecified, Amster sets the cookie domain to the URL of the AM instance, which will cause issues when having multiple instances in a site.
This example installs an AM instance with as part of the TestSite01 site. Note that the configuration store details are the same as those used for the first server, since they are sharing the same DS instance.
The cookie domain is specified in the --cookieDomain option. The cookie domain must be the same as the one used when installing the first instance, in this case, example.com. When unspecified, Amster sets the cookie domain to the URL of the AM instance, which is not optimal when having multiple instances in a site.
Keystore and secret store infrastructure is shared across all the AM instances in the site. This is so that every instance in the site can encrypt, decrypt, and verify messages, JWTs, and others, with the same keys.
The install process creates the required keystores and secret stores on the first instance in the site only. You must configure the keystore and secret store infrastructure in the rest of the instances manually.
Amster allows you to export the configuration of an AM instance and customize it ready for import into any other AM instance in your environment. For example, you can export the configuration from the development environment, customize the passwords and keystore values, and import it in your QA or integration environment for testing.
To make this process easier, Amster allows you to configure variables inside the exported configuration files and also, to script a series of commands and Amster tasks so they can be easily included in your processes or pipelines.
Amster supports the use of configuration expressions as the values of configuration properties in the exported configuration files. Amster substitutes the expressions with values obtained from the Amster shell, expression files, environment variables, and others, when importing the configuration files into an AM instance. Property value substitution enables you to achieve the following:
Property value substitution uses expressions to introduce variables into the server configuration. You set expressions as the values of configuration properties. The effective property values can be evaluated in a number of ways.
You can use a default value in a configuration expression by including it after a vertical bar () character following the token. For example, the following SMTP port expression sets the default value of the SMTP port to 1349: &1349.
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 does not have a predictable order of precedence for handling multiple configuration tokens with the same name. You are responsible for ensuring name uniqueness of configuration tokens across multiple expression files.
Expressions are evaluated and replaced with the expected values when importing a configuration into an AM instance. Attempting to import AM JSON configuration files containing expressions that are not defined causes an error message similar to the following:
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.
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.
This example shows the high-level steps required to clone an AM instance, from exporting the configuration of the original instance, to installing the new instance and importing the configuration into it.
Keep the transport key safe by exporting it to another keystore. The key is required to import the configuration into the new AM instance. For more information, see "To Duplicate and Install a Transport Key".
Specifies the path to an SSH public key file. The content of this file is appended to the authorized_keys file of the newly-installed AM instance, allowing users to connect to it with Amster after the install completes.
When you install AM with an external configuration store, you must also use an external user store. By default, the external user store is the same directory server instance as the external configuration store.
c80f0f1006