How To

How does AM (All versions) bind to the configuration store on startup?

Last updated Jun 25, 2019

The purpose of this article is to provide information on how AM binds to the configuration store on startup, and the purpose of boot.json and the keystore file in this process.


Binding to the configuration store

The Configuration directory ($HOME/[am_instance]) contains files created during the install process. Some of these files contain critical information that is required when AM initializes; AM cannot start if these files become corrupt or are missing. In particular, there are two files within AM’s configuration directory that are used to bind to the configuration store when AM starts up:

On startup, AM binds to the configuration store as follows:

  1. AM reads the boot.json file to get the bind DNs to access the Configuration Store and the location of the JCEKS keystore file.
  2. AM then uses the .storepass file to access the keystore.jceks file. The .storepass file is created at build time and consists of a base 64 encoded secure random string.
  3. AM then uses the .keypass file to access the configstorepwd and dsameuserpwd password entries in the keystore, which are then used to bind to DS.

boot.json

This file contains connection details to the configuration store, but does not include any passwords or key material. An example boot.json file looks like this:

{
  "instance" : "http://host1.example.com:8080/openam",
  "dsameUser" : "cn=dsameuser,ou=DSAME Users,ou=am-config",
  "keystores" : {
    "default" : {
      "keyStorePasswordFile" : "/path/to/openam/openam/.storepass",
      "keyPasswordFile" : "/path/to/openam/openam/.keypass",
      "keyStoreType" : "JCEKS",
      "keyStoreFile" : "/path/to/openam/openam/keystore.jceks"
    }
  },
  "configStoreList" : [ {
    "baseDN" : "ou=am-config",
    "dirManagerDN" : "uid=am-config,ou=admins,ou=am-config",
    "ldapHost" : "ds.example.com",
    "ldapPort" : 1636,
    "ldapProtocol" : "ldaps"
  } ]
}

See Installation Guide › Replacing the Bootstrap File for further information about the individual properties in the boot.json file.

keystore.jceks

The keystore.jceks file contains entries of type SecretKeyEntry for the following aliases:

  • configstorepwd - maps to the password for the dirManagerDN entry in boot.json.
  • dsameuserpwd - maps to the password for the dsameUser entry in boot.json.

See Setup and Maintenance Guide › Configuring the Bootstrap Keystore for further information about these aliases.

See Also

Setup and Maintenance Guide › Setting Up Keys and Keystores

How do I check if AM/OpenAM (All versions) is up and running?

Attempting to access AM/OpenAM (All versions) fails with ConfigurationException: Configuration store is not available

Data stores in AM/OpenAM

How do I make a backup of configuration data in AM/OpenAM (All versions)?

FAQ: Backing up AM/OpenAM

Related Training

N/A

Related Issue Tracker IDs

N/A



Copyright and TrademarksCopyright © 2019 ForgeRock, all rights reserved.
Loading...