--- title: The IDM keystore description: Understand the PingIDM default JCEKS keystore, its auto-generated encryption keys, and how to change the keystore password and type component: pingidm version: 7.5 page_id: pingidm:security-guide:default-keystore canonical_url: https://docs.pingidentity.com/pingidm/8.1/security-guide/default-keystore.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Security", "Keystores", "Encryption Keys", "Secrets", "PKCS #12", "Keys", "Keystores", "JCEKS", "Keytool", "Password"] superseded_by: https://docs.pingidentity.com/pingidm/8.1/security-guide/default-keystore.html 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).