Configuring Secret Stores

Secret stores are configured in your project's conf/secrets.json file. The secrets.json file has the following configuration by default:

{
  "stores": [
    {
      "name": "mainKeyStore",
      "class": "org.forgerock.openidm.secrets.config.FileBasedStore",
      "config": {
        "file": "&{openidm.keystore.location|&{idm.install.dir}/security/keystore.jceks}",
        "storetype": "&{openidm.keystore.type|JCEKS}",
        "providerName": "&{openidm.keystore.provider|SunJCE}",
        "storePassword": "&{openidm.keystore.password|changeit}",
        "mappings": [
          {
            "secretId" : "idm.default",
            "types": [ "ENCRYPT", "DECRYPT" ],
            "aliases": [ "&{openidm.config.crypto.alias|openidm-sym-default}" ]
          },
          ...
        ]
      }
    },
    {
      "name": "mainTrustStore",
      "class": "org.forgerock.openidm.secrets.config.FileBasedStore",
      "config": {
        "file": "&{openidm.truststore.location|&{idm.install.dir}/security/truststore}",
        "storetype": "&{openidm.truststore.type|JKS}",
        "providerName": "&{openidm.truststore.provider|SUN}",
        "storePassword": "&{openidm.truststore.password|changeit}",
        "mappings": [
        ]
      }
    }
  ],
  "populateDefaults": true
}

The mainKeyStore and mainTrustStore properties configure the default secret stores. IDM requires these properties in order to start up. Do not change the property names because they are also provided to third-party products that need a single keystore and a single truststore.

mainKeyStore: The main keystore references a Java Cryptography Extension Keystore (JCEKS) located at /path/to/openidm/security/keystore.jceks.
mainTrustStore: The main truststore references a file-based truststore located at /path/to/openidm/security/truststore.
populateDefaults: When IDM first starts up, it checks the secrets configuration. If "populateDefaults": true, IDM writes a number of encryption keys to the keystore, required to encrypt specific data.

You can manage these keystores and truststores using the keytool command, included in your Java installation. For information about the keytool command, see https://docs.oracle.com/en/java/javase/11/tools/keytool.html.

Each configured store has a name and class and the following configuration properties:

file

For file-based secret stores, this property references the path to the store file, for example, &{idm.install.dir}/security/keystore.jceks}. Hardware security modules do not have a file property.

storetype

The type of secret store. IDM supports a number of store types, including JCEKS, JKS, PKCS #11, and PKCS #12.

providerName

Sets the name of the cryptographic service provider, for example, SunPKCS11 or softHSM. If no provider is specified, the JRE default is used.

storePassword

The password to the secret store. For the default IDM keystore and trustore, the password is changeit. You should change this password in a production deployment, as described in "Changing the Default Keystore Password".

mappings

This object enables you to map keys and certificates in the secret stores to specific encryption and decryption functionality in IDM. A secrets mapping object has the following structure:

{
    "secretId" : "idm.config.encryption",
    "types": [ "ENCRYPT", "DECRYPT" ],
    "aliases": [ "&{openidm.config.crypto.alias|openidm-sym-default}" ]
}

secretId enables you to map a secret to one or more aliases and gives an indication of the secret's purpose. For example, idm.config.encryption indicates the aliases that are used to encrypt and decrypt sensitive configuration properties.
types indicates what the keys are used for, for example, encryption and decryption of sensitive property values.
aliases are the key aliases in the secret store that are used for this purpose. You can add as many aliases as necessary. The first alias in the list determines which alias is the active one. Active secrets are used for signature generation and encryption.
The aliases in the default keystore are described in "Working With the Default Keystore".

The default secret IDs and the aliases to which they are mapped are listed in "Mapping SecretIDs to Key Aliases".

Note

All these properties have a resolvable property value by default, for example &{openidm.keystore.location}, that enables you to use property value substitution. If no configuration expression has been set for that specific property, the value following the vertical bar is used. In the following property, the password is changeit unless you have set a configuration expression in one of the property resolver locations:

"storePassword": "&{openidm.keystore.password|changeit}"

For more information, see "Property Value Substitution".

Mapping SecretIDs to Key Aliases

`secretId`	`alias`	Description
`idm.default`	`openidm-sym-default`	Encryption keystore for legacy JSON objects that do not contain a `purpose` value in their `$crypto` block
`idm.config.encryption`	`openidm-sym-default`	Encrypts configuration information
`idm.password.encryption`	`openidm-sym-default`	Encrypts managed user passwords
`idm.jwt.session.module.encryption`	`openidm-localhost`	Encrypts JWT session tokens
`idm.jwt.session.module.signing`	`openidm-jwtsessionhmac-key`	Signs JWT session tokens using HMAC
`idm.selfservice.signing`	`selfservice`	Signs JWT session tokens using RSA
`idm.selfservice.encryption`	`openidm-selfservice-key`	Encrypts JWT self-service tokens