This page is for administrators who need to migrate local user information to use BCrypt encryption.

Overview

PhixFlow users can be set up as:

• external - all user authentication and permissions are handled externally for example by a SAML single-sign-on service or Active Directory.
• mixed - user authentication is handled externally but a assigned to user groups in PhixFlow, which handle permissions
• local - both user authentication and permissions are handled locally.

For local users, in version 8.3.0 and later, PhixFlow's encryption method was upgraded to one-way encrypt:

• User passwords using a pepper string and Bcrypt; see About the Pepper String, right. 
  • This requires an exact string match for the password.
  • The pepper string is stored in the keystore.
    It is more secure to set different pepper strings for each PhixFlow instance.

• Security answers using normalized Bcrypt.
  
  • This changes all letters to lower case and removes spaces before encrytpting.
  • It does not use the pepper string, so security answers will work if the user account is imported to another instance.

When PhixFlow Switches to Bcrypt

Upgrading to PhixFlow 8.3.0 or later does not change the encryption of existing passwords and security answers that were created in older versions of PhixFlow. Passwords and security answers will continue to work with legacy encryption. 

PhixFlow starts using Bcrypt encryption with the pepper string when:

• a new user creates a password and security answers
• an existing user resets their password and security answers.

How to Migrate Security Information

As Bcrypt is more secure, we recommend all security information is migrated to Bcrypt as soon as possible.

To do this, all users must change their passwords and their security answers.

You can use your Password Policy to ensure users reset their passwords within a defined period, such as 1 month.

How PhixFlow Checks Passwords

To check the string provided for a password or security answer, PhixFlow:

1. Identifies which encryption method was used when the security information was set.
2. Adds the pepper string to a password, if it was set using Bcrypt.
3. Encrypts the string using the original encryption method.
4. Compares the two encrypted strings.

Encryption Configuration

The different encryption methods are recorded in phixflow-login.xml.

<bean id="passwordEncoder" class="com.accipia.centerview.util.security.ConfigurablePasswordEncoder">
  <property name="matchEncoders">
    <list>
      <ref bean="pepperedBcrypt" />
      <ref bean="legacyEncoder" />
      <ref bean="startupEncoder" />
    </list>
  </property>
  <property name="setterEncoder" ref="pepperedBcrypt" />
</bean>

Removing Old Encoders

Optionally, you can update phixflow-instance.xml to comment-out or remove old encoders lines:

• <ref bean="legacyEncoder" /> 
• <ref bean="startupEncoder" />  

The line <ref bean="pepperedBcrypt" /> is required.

Only remove old encoders when:

• At least one administration user can log into PhixFlow.
  This means the startup user is no longer required.
• You installed PhixFlow version 8.3.0 or later as a new instance.
  In a new instance, all passwords and security answers automatically use BCrypt encryption and the legacyEncoder is not required.
• After upgrading to 8.3.0 or later and all users have updated their passwords and security answers.
  This means all existing passwords and security answers have been migrated to use BCrypt encryption.

1.  In your PhixFlow installation directory,  go to webapp/WEB-INF/classes/ and edit phixflow-instance.xml.
2. Find the bean: <bean id="passwordEncoder"
3. Delete the lines
   • <ref bean="legacyEncoder" /> to disable passwords or security answers that do not use BCrypt
   • <ref bean="startupEncoder" /> to disable the startup user account.

For passwords disabled by this process, users can reset their password; see Changing or Resetting Your Password.

Considerations for Pepper Strings

If you have multiple instances of PhixFlow installed, you must choose whether:

• All instances have their own unique pepper string
  Use this strategy for greater security where different users are accessing different PhixFlow instances 
• Some/all instances have the same pepper string.
  Consider using this strategy when the same users are accessing different PhixFlow instances. 

With different pepper strings, users may need to reset their passwords in the following situation:

1. The same user account exists in both instances.
2. The user has reset their password in instance A.
3. You export instance A and import to instance B. This process updates the user account with a new password that uses the wrong pepper string.
4. The next time the user logs in to instance B, their password no longer works.
5. The user resets their password, so it now uses the correct pepper string for the instance;  see Changing or Resetting Your Password.