Use the encrypted properties editor

Contrast includes several configuration files in the $CONTRAST_HOME/data/conf directory. By default, Contrast encrypts the configuration files for security, but you can modify some of these files through workflows in Contrast.

For example, these are some of the encrypted properties files for on-premises installations:

Name

Contents

ad.properties

Settings to connect and configure Contrast to authenticate Active Directory groups.

ldap.properties

Settings to connect and configure Contrast to authenticate LDAP groups.

database.properties

Host and connection settings for communication between Contrast and MySQL.

saml.properties

SAML keystore security settings.

Contrast also includes an editing tool to decrypt these files and assist with configuration. This is helpful when you are running Contrast and need to get values from encrypted properties files outside of the application or automatically update a property in the files, such as automatic password rotation.

To edit encrypted properties files:

  1. Find the decryption tool in the $CONTRAST_HOME/bin directory.

    • Linux: the file is a shell script called edit-properties.

    • Windows: the file is a Windows command file called edit-properties.cmd.

  2. Run the tool from a command prompt. This opens an application that allows you to update the value of an encrypted property:

    $CONTRAST_HOME/bin/edit-properties -e $CONTRAST_HOME/data/esapi -f $CONTRAST_HOME/data/conf/ad.properties
  3. You must provide input details to view or edit encrypted properties files. The basic inputs you need are:

    • The path to ESAPI.properties.

    • The target properties file to edit.

    To find this information for the encrypted properties editor, execute edit-properties with no arguments:

    contrast@EOP-TeamServer:~/contrast/bin$ ./edit-properties 
    
    usage: property-editor
     -c,--comment <text>      The comment for the top of the file
     -e,--esapi <path>        The path to the ESAPI.properties file
     -f,--targetFile <file>   The properties file to edit
     -o,--print-value         Print out the value of the property and exit
     -p,--property <name>     The name of the property to set
     -v,--value <val>         The value of the property
  4. This example shows you how to edit an encrypted file. Provide the path to ESAPI.properties and the target properties file to edit. You will see the existing values encrypted in the file that you can edit. The usage options above allow you to view or edit a single property.

    contrast@TeamServer:~/contrast/bin$ ./edit-properties -e ../data/esapi/ -f ../data/conf/ad.properties
    
    ad.userDn                                         : cn=Directory Manager
    ad.identity.attribute.name                        : mail
    ad.password                                       : NotaRealPassword
    ad.nested.groups.enabled                          : false
    ad.group.users                                    : cn=ContrastUsers,cn=Users,dc=contrastsecurity,dc=com
    ad.group.admin                                    : cn=ContrastAdmins,cn=Users,dc=contrastsecurity,dc=com
    ad.url                                            : ldap://localhost:389
    ad.base                                           : dc=contrastsecurity,dc=com
  5. You can also retrieve or update unencrypted values for a property. To retrieve values, pass another parameter to the properties editor. In this example, the user is looking for details about database properties:

    $CONTRAST_HOME/bin/edit-properties \
       -e $CONTRAST_HOME/data/esapi \
       -f $CONTRAST_HOME/data/conf/database.properties \
       -p jdbc.username \
       -o

    To update unencrypted values, pass a different set of arguments to the properties editor:

    $CONTRAST_HOME/bin/edit-properties \
       -e $CONTRAST_HOME/data/esapi \
       -f $CONTRAST_HOME/data/conf/database.properties \
       -p jdbc.username \
       -v joe.user \
       -c "Updating JDBC Password"

Note

Add comments to indicate edits to encrypted properties files. This is useful for auditors or others who need to track configuration changes.