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.
When PhixFlow is running, it provides the account credentials to its database as follows:
- phixflow-datasource.xml stores alias credentials for the database. It requests actual credentials from phixflow-secret.xml.
- phixflow-secret.xml asks the keystore for the actual credentials.
- This file stores the location of the keystore file and optionally its password (2a in the diagram below).
- Alternatively, the keystore password is configured as an environment variable (2b in the diagram below)
- The keystore file returns the actual account credentials to phixflow-secret,
- which, in turn, passes the actual credentials to phixflow-datasource.xml.
- 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
| Tip |
|---|
You can use the same keystore to encrypt credentials for several PhixFlow instances. We recommend that you use actual credentials and aliases that clearly relate to their instance. |
How to Configure a Keystore
The examples in the instructions below use the following names, passwords or variables.
...
PhixFlow-DB-Dev
...
pdbdev
...
Step 1 Create the keystore
1.1. At the command line, use the Java keytool command -importpass to create a keystore. At the same time, you will add the alias for the database username.
...
To configure the keystore, you will use the following 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.
| Code Block |
|---|
<keytool> -importpass -alias <keyAlias> -keystore <pathToKeystoreFile> -storetype <keytype> |
...
| Where: | Is | |
|---|---|---|
| ||
...
...
| Windows command |
...
| prompt | |
...
| Windows |
...
| PowerShell | |
...
| Linux | |
|
...
| The alias for a username or password. The keytool prompts you to enter the | |
...
| corresponding username or password. | ||
| <pathToKeystoreFile> | The full path to the keystore file, for | |
...
example:
|
...
| |
| <keytype> | |
...
| either PKCS12 or JCEKS. | ||
Step 1 Create the keystore and the alias for the database username
- Run the
-importpasscommand
In <keyAlias> specify the alias for the PhixFlow database username. - When prompted, enter a password for the keystore file and confirm it.
...
- When prompted, enter the username for the PhixFlow database.
| Tip |
|---|
The command's prompts are not very clear. The second prompt may ask for a password, but you need to enter the username. |
Example commands
Windows:
| Code Block |
|---|
"%JAVA_HOME%\bin\keytool" -importpass -alias pdbdevdatabasealias -keystore C:\secure\hidden.jks -storetype PKCS12 |
...
| Required? | Property | Value | Example |
|---|---|---|---|
| Required | keystoreType | The type of the keystore, either PKCS12 or JCEKS |
|
| Required | keystoreFile | The path to the keystore. |
|
| Either (recommended) | keystorePassEnvironmentVariable | The name of the environment variable. Use |
|
| Or | keystorePass | The password for the keystore. Use |
|
Understanding How PhixFlow Uses A Keystore
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.
When PhixFlow is running, it provides the account credentials to its database as follows:
- phixflow-datasource.xml stores alias credentials for the database. It requests actual credentials from phixflow-secret.xml.
- phixflow-secret.xml asks the keystore for the actual credentials.
- This file stores the location of the keystore file and optionally its password (2a in the diagram below).
- Alternatively, the keystore password is configured as an environment variable (2b in the diagram below)
- The keystore file returns the actual account credentials to phixflow-secret,
- which, in turn, passes the actual credentials to phixflow-datasource.xml.
- 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