Scramble sensitive data in Identity Manager files

This article includes updates for Identity Manager 5.0.1.

You can scramble sensitive data in Identity Manager configuration files, to avoid showing PIN codes and passwords, or other sensitive data. The data is encrypted with AES-256, with a key stored in a java class.

Scrambling can be used for example in database.properties (WAR deployment only), system.properties (WAR deployments only), and engineSignEncryptConfig.xml / signencrypt.xml (WAR and Docker deployments).

Prerequisites and limitations

All properties files must use UTF-8 character encoding.
Property files used in CA connector configurations cannot be scrambled.
The .encrypted syntax is allowed only in property files that are passed to the ScramblingPropertyConfigurers. Other property files will not be scrambled and the setting of the values will fail, since .encrypted will be interpreted as part of the key.
Properties files inside .jar files will not be scrambled and using the .encrypted syntax will lead to errors, since spring will try to set a property named encrypted. You can set already encrypted properties inside a .jar file.

Trying to scramble a property that spans over several lines will result in an error.
Docker deployments have limited scrambling support. For more information, see below.

Step-by-step instruction

Add encryption to a parameter in a file

To scramble sensitive information in a .properties file or in engineSignEncryptConfig.xml / signencrypt.xml, do the following:

Open the file for editing.
Append .encrypted to any sensitive keys in the file, for example password or pin.
The values will be encrypted with a key stored in Identity Manager upon next Tomcat restart (for WAR deployments). See the examples below.

Only properties files outside of a .jar file will be replaced.

For Docker deployments, see Docker deployments below.

Examples

View examples

Encrypt the database username and password in database.properties:

Example: encrypt keys in database.properties

CODE

# A placeholder:
maxActive=200
# A property override:
dataSource.jdbcUrl=jdbc:h2:mem:prime;DB_CLOSE_DELAY=-1;LOCK_TIMEOUT=60000
dataSource.user.encrypted=sa
dataSource.password.encrypted=s3cr3t!

Example result:

Example result: scrambled keys in database.properties

NONE

# A placeholder:
maxActive=200
# A property override:
dataSource.jdbcUrl=jdbc:h2:mem:prime;DB_CLOSE_DELAY=-1;LOCK_TIMEOUT=60000
dataSource.user=encrypted:3I5rVis6scgAzEGg0MtqLw==
dataSource.password=encrypted:K41LmsAmxiIMcTq3k8sAS8l=

Encrypt the certificate PIN in engineSignEncryptConfig.xml:

Example: encrypt keys in engineSignEncryptConfig.xml

XML

     <key name="encCert">
         <type name="pkcs12" locationValue="classpath:hybridEncKeypair2.p12" pin.encrypted="1234567"/>
     </key>

Example result:

Example result: scrambled keys in engineSignEncryptConfig.xml

XML

     <key name="encCert">
         <type name="pkcs12" locationValue="classpath:hybridEncKeypair2.p12" pin="encrypted:JMyVZtk9WIWQQEfpC4CEVg==" />
     </key>

If you use the truststore in system.properties, encrypt the truststore password:

Example: encrypt keys in engineSignEncryptConfig.xml

CODE

# CERTIFICATE VALIDATION:
# -----------------------
# Path to the truststore to use for certificate path validation
jksKeyStoreProvider.keyStorePath=file:apache-tomcat-8.5.24/conf/prime.truststore

# The password for the truststore
jksKeyStoreProvider.keyStorePassword.encrypted=prime

Example result:

Example result: scrambled keys in engineSignEncryptConfig.xml

CODE

# CERTIFICATE VALIDATION:
# -----------------------
# Path to the truststore to use for certificate path validation
jksKeyStoreProvider.keyStorePath=file:apache-tomcat-8.5.24/conf/prime.truststore

# The password for the truststore
jksKeyStoreProvider.keyStorePassword=encrypted:CYyVZis7WITDOIfpC1CNDx==

Docker deployments

Docker deployments currently only support pin scrambling in the docker/compose/identitymanager/config/signencrypt.xml configuration file.

The pins must be scrambled with a dedicated tool while no IDM Admin/Operator container is running (execute docker compose down from docker/compose/identitymanager/admin/ and docker/compose/identitymanager/operator/ to stop them first).

Scrambling is then done by running docker compose run --rm scramble_sign_encrypt_config from the docker/compose/identitymanager/bootstrap folder.

Afterwards you can restart the Identity Manager Admin and Identity Manager Operator containers (by running docker compose up -d from docker/compose/identitymanager/admin/ and docker/compose/identitymanager/operator/).

Additional information

Useful links