Keystore Configuration

Last modified 07 Sep 2023 17:18 +02:00

Keystore is a small database that stores cryptographic material. MidPoint is using keystore to keep encryption keys and certificates. The most important pieces stored in the keystore are:

  • Symmetric key used to encrypt and decrypt passwords in midPoint repository.

  • Root and intermediate certificates used to validate SSL certificates of other hosts ("trust anchors") when midPoint acts as a SSL client. This usually happens during communication to SSL-enabled Connector Server.

MidPoint is using standard Java JCE keystore mechanism. This may allow moving the keystore to a cryptographic hardware or other forms using Java JCE methods.

Location and Form

The keystore is normally stored in midPoint home directory in a keystore.jceks file. It is using JCEKS keystore format because it allows to store both certificates and symmetric encryption keys (as opposed to JKS format).

The symmetric encryption key that is used to encrypt sensitive information in midPoint repository should have alias default. This key is used for encryption of any new data. However, there may be older data in the repository encrypted by keys that were used previously. There keys will still work for decryption as midpoint remembers the identifier (not alias) of the key that was used for encryption together with the encrypted data. MidPoint will look for this key by its ID when the data has to be decrypted. Therefore it is recommended to keep old keys in the keystore to allow decryption of older data.

The default keystore password is changeit.

The keystore content is usually inspected and manipulated by using keytool utility that is part of Java platform.

Note: Some applications servers (notably Glassfish) are using their own trust stores. Therefore the trusted root certificates needs to be imported in their own keystores intead of midPoint keystore. Please refer to the application server documentation for the details. For Glassfish the keystore to use is usually <installRoot>/glassfish/domains/domain1/config/keystore.jks.

MidPoint Keystore and JVM Keystore

MidPoint has its own keystore in midPoint home directory and this keystore is used for all operations that are under midPoint control. But there are operations that are not under direct midPoint control. Perhaps the most notable case are the connectors. Connector framework is by design isolating the connectors from the IDM system. Therefore connectors does not know anything about midPoint keystore. When a connector needs a keystore or truststore (store for trusted certificates) it falls back to JVM defalts. Therefore it means that putting a key to midPoint keystore may not work for these connectors.

Note: The isolation mentioned above does not apply when using Discovery with remote connector hosts secured with TLS. In this case the CA certificate(s) or self-signed certificate from the connector host must be imported into the midPoint keystore. Errors regarding "trustAnchors" and similar are probably due to the certificate not being available in the midPoint keystore.

Perhaps the best thing to do is to override the default JVM keystore/truststore location and point it midPoint keystore. You can do this with JVM options. E.g:

Common Administration Tasks

List Keystore Content

keytool -keystore keystore.jceks -storetype jceks -storepass changeit -list

Change keystore password

Newly generated keystore is protected with initial password changeit.

To change it you need to change the password and let the midPoint know to use the new one. No keys are being altered in this operation.

  1. stop midPoint

  2. cd to midpoint.home directory

  3. run following command: keytool -storepasswd -keystore keystore.jceks

    • enter the original password changeit

    • enter your new password

  4. open config.xml and replace the value of parameter /configuration/midpoint/keystore/keyStorePassword with the new password

  5. start midPoint

Change encryption key

Import Trusted CA Certificate

keytool -keystore keystore.jceks -storetype jceks -storepass changeit -import -alias evolveum -trustcacerts -file evolveum-cacert.der
Was this page helpful?
Thanks for your feedback