--- title: The IDM keystore description: 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. component: pingidm version: 8.1 page_id: pingidm:security-guide:default-keystore canonical_url: https://docs.pingidentity.com/pingidm/8.1/security-guide/default-keystore.html keywords: ["Security", "Keystores", "Encryption Keys", "Secrets", "PKCS #12", "Keys", "Keystores", "JCEKS", "Keytool", "Password"] section_ids: security-keystore-password: Change the default keystore password --- # 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](secret-stores.html#secret-mappings). 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](../install-guide/chap-install.html#stop-openidm) 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](secret-stores.html#secret-mappings), 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 changeit New key password for : newPassword Re-enter new key password for : newPassword ``` ``` keytool \ -keypasswd \ -alias openidm-sym-default \ -keystore /path/to/openidm/security/keystore.jceks \ -storetype jceks \ -storepass newPassword Enter key password for changeit New key password for : newPassword Re-enter new key password for : newPassword ``` ``` keytool \ -keypasswd \ -alias openidm-selfservice-key \ -keystore /path/to/openidm/security/keystore.jceks \ -storetype jceks \ -storepass newPassword Enter key password for changeit New key password for : newPassword Re-enter new key password for : newPassword ``` ``` keytool \ -keypasswd \ -alias selfservice \ -keystore /path/to/openidm/security/keystore.jceks \ -storetype jceks \ -storepass newPassword Enter key password for changeit New key password for : newPassword Re-enter new key password for : newPassword ``` ``` keytool \ -keypasswd \ -alias openidm-jwtsessionhmac-key \ -keystore /path/to/openidm/security/keystore.jceks \ -storetype jceks \ -storepass newPassword Enter key password for changeit New key password for : newPassword Re-enter new key password for : newPassword ``` 4. Configure a new [expression resolver file](../setup-guide/chap-configuration.html#expression-evaluation) 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: ```bash 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: ```bash 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 ```properties openidm.keystore.password=newPassword ``` ```json { "openidm" : { "keystore" : { "password" : "newPassword" } } } ``` 5. [Restart IDM](../install-guide/chap-install.html#run-openidm).