Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Reverted from v. 22

Insert excerpt
_Banners
_Banners
nameadministration
nopaneltrue

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.


Note

You can export/import user accounts from one instance to another. However, user passwords will not work in the new instance if the pepper string is different. The user will need to reset their password in the import instance.

If you want local users to access different PhixFlow instances using the same password, set the same papper string for these instances.

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.

Code Block
titlephixflow-instance.xml encryption configuration
code
<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.
Warning

There is no way to check if passwords or security answers are still using the legacy encoder. Removing the old encoders from phixflow-instance.xml will disable passwords or security answers that still use the legacy encoder.  

  1.  In  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.

Tip

If you subsequently need to reinstate these encoders, you can copy them from webapp/WEB-INF/classes/phixflow-instance-example.xml.

Considerations for Pepper Strings
Anchor
instance
instance

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.


Live Search
spaceKey@self
additionalnone
placeholderSearch all help pages
typepage

Panel
borderColor#00374F
titleColorwhite
titleBGColor#00374F
borderStylesolid
titleSections on this page

Table of Contents
maxLevel3
indent12px
stylenone


Info

About the Pepper String
Anchor
pepper
pepper

During installation or upgrade to 8.3.0 or later, your administrator creates a string that PhixFlow uses to "pepper" all new or reset passwords.  If you are unfamiliar with the concept of pepper strings, see Wikipedia article on Pepper Encryption.

The pepper string itself is stored in the keystore along with an alias, called the pepper key; see Adding Data to a Keystore. The pepper key is used by phixflow-instance.xml to access the pepper string in the keystore.

Warning

Changing the pepper string or the pepper key disables all local user passwords, including administrator passwords.