Overview

To keep the database username and password secure, PhixFlow is configured to use a keystore file. The database account credentials are encrypted and stored here, along with aliases.

To configure the keystore, you will use the Java keytool -importpass command at the command line.

Keytool Syntax

For reference, here is the full syntax and the values you will need to use. The steps below provide example commands.

<keytool> -importpass -alias <keyAlias> -keystore <pathToKeystoreFile> -storetype <keytype>

Step 1  Create the keystore and the alias for the database username

1.1 Run the -importpass command. In <keyAlias> specify the alias for the PhixFlow database username (pbdev in the following examples).

Windows:

"%JAVA_HOME%\bin\keytool" -importpass -alias pbdev -keystore C:\secure\hidden.jks -storetype PKCS12

Linux:

$JAVA_HOME/bin/keytool -importpass -alias pdbdev -keystore /opt/secure/hidden.jks -storetype PKCS12

1.2 When prompted, enter a password for the keystore file, then re-enter to confirm it.

1.3 When prompted, enter the actual username for the PhixFlow database. 

Step 2  Add the database password and alias to the keystore file

2.1.  Repeat the -importpass command. In <keyAlias> specify the alias for the PhixFlow database password. (123xyz in the following examples).

Windows:

"%JAVA_HOME%\bin\keytool" -importpass -alias 123xyz -keystore C:\secure\hidden.jks -storetype PKCS12

Linux:

$JAVA_HOME/bin/keytool -importpass -alias 123xyz -keystore C:\secure\hidden.jks -storetype PKCS12

2.2  When prompted, enter the password for the keystore file.

2.3 When prompted enter the actual password for the PhixFlow database.

Step 3  Configure phixflow-datasource.xml

Edit phixflow-datasource.xml to add the aliases for the PhixFlow database username and password. For example:

<property name="username">
	<value>pdbdev</value>
</property>
<property name="password">
	<value>123xyz</value>
</property>

Step 4  Set the Environment Variable

Create an environment variable with the form <variable-name>: <keystore-password>

Step 5  Configure phixflow-secret.xml

Copy phixflow-secret.xml.example to phixflow-secret.xml and edit it to set the values as follows:

Understanding How PhixFlow Uses A Keystore

When PhixFlow is running, it provides the account credentials to its database as follows:

1. phixflow-datasource.xml stores alias credentials for the database. It requests actual credentials from phixflow-secret.xml.
2. phixflow-secret.xml asks the keystore for the actual credentials.
   1. This file stores the location of the keystore file and optionally its password (2a in the diagram below).
   2. Alternatively, the keystore password is configured as an environment variable (2b in the diagram below)
3. The keystore file returns the actual account credentials to phixflow-secret,
4. which, in turn, passes the actual credentials to phixflow-datasource.xml.
5. phixflow-datasource.xml then uses the actual credentials to log into the database, so that PhixFlow can update it.

This is shown in the diagram below.

Figure 1: How PhixFlow authenticates to its database