PingIDM 7.5.0

The IDM keystore

IDM generates a number of encryption keys in a JCEKS keystore the first time the server starts up. These keys map to the secrets defined in Mapping secretIDs to key aliases. The keystore and the keys are generated at startup and are not prepackaged. The keys are generated only if they do not already exist. You cannot specify custom aliases for these default keys.

To use a different keystore type, such as PKCS #12, create the keystore and generate the keys before you start IDM. This prevents IDM from generating the keys on startup. You can also convert the existing JCEKS keystore to a PKCS #12 keystore. If you use a different keystore type, you must edit the openidm.keystore.type property (in the conf/secrets.json file) to match the new type.

Use the keytool command to list the default encryption keys, as follows:

keytool \
-list \
-keystore /path/to/openidm/security/keystore.jceks \
-storepass changeit \
-storetype JCEKS
Keystore type: JCEKS
Keystore provider: SunJCE

Your keystore contains 5 entries

openidm-sym-default, Nov 5, 2019, SecretKeyEntry,
openidm-jwtsessionhmac-key, Nov 5, 2019, SecretKeyEntry,
selfservice, Nov 5, 2019, PrivateKeyEntry,
Certificate fingerprint (SHA-256): E9:0B:BA:FB:58:73:02:FC...:7B
openidm-selfservice-key, Nov 5, 2019, SecretKeyEntry,
openidm-localhost, Nov 5, 2019, PrivateKeyEntry,
Certificate fingerprint (SHA-256): 21:50:6C:90:C7:A7:F7:32...:1B

If you are using IDM in a cluster, you must share these keys among all nodes in the cluster. The easiest way to do this is to generate a keystore with the appropriate keys and share the keystore in some way; for example, by using a filesystem that is shared between the nodes.

Change the default keystore password

The default keystore password is changeit. You should change this password in a production environment.

Repeat this procedure on each node if you run multiple nodes in a cluster to ensure that the new password is present on all nodes.

  1. Shut down the server if it is running.

  2. Use the keytool command to change the keystore password. The following command changes the keystore password to newPassword:

    keytool \
-storepasswd \
-keystore /path/to/openidm/security/keystore.jceks \
-storetype jceks \
-storepass changeit
New keystore password: newPassword
Re-enter new keystore password: newPassword

  3. Change the passwords of the default encryption keys.

    IDM uses the encryption keys listed in Mapping secretIDs to key aliases, whose passwords are also changeit by default. The passwords of each of these keys must match the password of the keystore.

    To get the list of keys in the keystore, run the following command:

    keytool \
-list \
-keystore /path/to/openidm/security/keystore.jceks \
-storetype jceks \
-storepass newPassword
Keystore type: JCEKS
Keystore provider: SunJCE

Your keystore contains 5 entries

openidm-sym-default, May 4, 2021, SecretKeyEntry,
selfservice, May 4, 2021, PrivateKeyEntry, Certificate fingerprint (SHA-256): fingerprint
openidm-jwtsessionhmac-key, May 4, 2021, SecretKeyEntry,
openidm-localhost, May 4, 2021, PrivateKeyEntry, Certificate fingerprint (SHA-256): fingerprint
openidm-selfservice-key, May 4, 2021, SecretKeyEntry,

    Change the passwords of each default encryption key as follows:

    keytool \
-keypasswd \
-alias openidm-localhost \
-keystore /path/to/openidm/security/keystore.jceks \
-storetype jceks \
-storepass newPassword
Enter key password for <openidm-localhost> changeit
New key password for <openidm-localhost>: newPassword
Re-enter new key password for <openidm-localhost>: newPassword
    keytool \
-keypasswd \
-alias openidm-sym-default \
-keystore /path/to/openidm/security/keystore.jceks \
-storetype jceks \
-storepass newPassword
Enter key password for <openidm-sym-default> changeit
New key password for <openidm-sym-default>: newPassword
Re-enter new key password for <openidm-sym-default>: newPassword
    keytool \
-keypasswd \
-alias openidm-selfservice-key \
-keystore /path/to/openidm/security/keystore.jceks \
-storetype jceks \
-storepass newPassword
Enter key password for <openidm-selfservice-key> changeit
New key password for <openidm-selfservice-key>: newPassword
Re-enter new key password for <openidm-selfservice-key>: newPassword
    keytool \
-keypasswd \
-alias selfservice \
-keystore /path/to/openidm/security/keystore.jceks \
-storetype jceks \
-storepass newPassword
Enter key password for <selfservice> changeit
New key password for <selfservice>: newPassword
Re-enter new key password for <selfservice>: newPassword
    keytool \
-keypasswd \
-alias openidm-jwtsessionhmac-key \
-keystore /path/to/openidm/security/keystore.jceks \
-storetype jceks \
-storepass newPassword
Enter key password for <openidm-jwtsessionhmac-key> changeit
New key password for <openidm-jwtsessionhmac-key>: newPassword
Re-enter new key password for <openidm-jwtsessionhmac-key>: newPassword

  4. Configure a new expression resolver file to store only the keystore password:

    1. Create a new directory in /path/to/openidm/resolver/ that will contain only the properties file for keystore passwords. For example:

      mkdir /path/to/openidm/resolver/keystore
      Substituted properties are not encrypted by default. You must therefore secure access to this directory, using the appropriate permissions.

    2. Set the IDM_ENVCONFIG_DIRS environment variable to include the new directory:

      export IDM_ENVCONFIG_DIRS=/path/to/openidm/resolver/,/path/to/openidm/resolver/keystore

    3. Create a .json or .properties file in that secure directory, that contains the new keystore password as a resolvable IDM property. For example, add one of the following files to that directory:

      • keystorepwd.properties

      • keystorepwd.json

      openidm.keystore.password=newPassword
      {
    "openidm" : {
        "keystore" : {
            "password" : "newPassword"
        }
    }
}

  5. Restart IDM.