IDM 7.4.1

Secret stores

Secret stores are repositories for cryptographic keys and credentials. IDM supports the following secret store types:

  • File secret stores, which have one file that stores many secrets

  • Filesystem secret stores, which have many files that each store one secret

  • Property secret stores, which store secrets in properties

  • Hardware Security Module (HSM) secret stores, which involve security devices (for example, a YubiKey)

Configure secret stores

You can configure secret stores in your project’s conf/secrets.json file, which has the following default configuration:

{
    "stores" : [
        {
            "name" : "mainKeyStore",
            "class" : "org.forgerock.openidm.secrets.config.FileBasedStore",
            "config" : {
                "file" : "&{idm.data.dir}/security/keystore.jceks",
                "storetype" : "JCEKS",
                "providerName" : "SunJCE",
                "storePassword" : "changeit",
                "mappings" : [
                    {
                        "secretId" : "decrypt",
                        "aliases" : [
                            "openidm-sym-default"
                        ],
                        "types" : [
                            "ENCRYPT",
                            "DECRYPT"
                        ]
                    }
                ]
            }
        },
        {
            "name" : "mainTrustStore",
            "class" : "org.forgerock.openidm.secrets.config.FileBasedStore",
            "config" : {
                "file" : "&{idm.data.dir}/security/truststore",
                "storetype" : "JKS",
                "providerName" : "SUN",
                "storePassword" : "changeit",
                "mappings" : [
                    {
                        "secretId" : "sign",
                        "aliases" : [
                            "server-cert"
                        ],
                        "types" : [
                            "SIGN"
                        ]
                    }
                ]
            }
        }
    ],
    "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.

You can manage these keystores and truststores using the keytool command, included in your Java installation. For information about the keytool command, refer to 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 truststore, the password is changeit. You should change this password in a production deployment, as described in Changing the default keystore password.

mappings

This object lets you map keys and certificates in the secret stores to 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 is the name of the secret. The secretId should indicate the purpose that the secret should be used for. For example, idm.config.encryption indicates that the mapping is used to encrypt and decrypt sensitive configuration properties, while idm.password.encryption indicates that the mapping is used to encrypt and decrypt passwords.

  • types indicates what the keys are used for. The supported types are:

    Type Definition

    GENERIC

    Used for credentials, such as passwords

    ENCRYPT

    Used to encrypt data

    DECRYPT

    Used to decrypt data

    SIGN

    Used to sign data

    VERIFY

    Used to verify data

  • 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 The IDM keystore.

The default secret IDs and the aliases they are mapped to are listed in Mapping secretIDs to key aliases.

All these properties have a resolvable property value by default; for example &{openidm.keystore.location}, that allows you to use property value substitution. If no configuration expression has been set for a 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, refer to Property value substitution.

Mapping secretIDs to key aliases

The following table describes the default secrets and their alias mappings:

secretId alias Description Supported types

idm.default

openidm-sym-default

Encryption keystore for legacy JSON objects that do not contain a purpose value in their $crypto block

ENCRYPT, DECRYPT

idm.config.encryption

openidm-sym-default

Encrypts configuration information

ENCRYPT, DECRYPT

idm.password.encryption

openidm-sym-default

Encrypts managed user passwords

ENCRYPT, DECRYPT

idm.jwt.session.module.encryption

openidm-localhost

Encrypts JWT session tokens

ENCRYPT, DECRYPT

idm.jwt.session.module.signing

openidm-jwtsessionhmac-key

Signs JWT session tokens using HMAC

SIGN, VERIFY

idm.selfservice.encryption

openidm-selfservice-key

Encrypts JWT self-service tokens

ENCRYPT, DECRYPT

idm.selfservice.signing

selfservice

Signs JWT session tokens using RSA

SIGN, VERIFY

idm.assignment.attribute.encryption

openidm-sym-default

Encrypts confidential assignment attributes

ENCRYPT, DECRYPT

idm.rs.filter.client.secret

rsFilter/clientSecret field in authentication.json

The rsFilter client_secret

GENERIC

idm.prometheus.password

openidm.prometheus.password property in boot.properties

The password for Prometheus

GENERIC

idm.felix.webconsole.password

password property in felix.webconsole.json

The password for the Felix web console

GENERIC

idm.workflow.email.password

mail/password property in workflow.json

The password for Workflow emails

GENERIC

idm.http.client.proxy.password

openidm.http.client.proxy.password property in boot.properties

The password for the default HTTP client proxy

GENERIC