Upgrading to version 11 or later from pre version 11
Direct upgrading from version 8.3.18 onwards to version 11.0.1 or later is supported with automatic database schema upgrade. (8.3.24 for 11.0.0).
This process requires migrating the configuration settings from the modified xml settings into the local.properties file. It is assumed a keystore was previously configured.
Review the files in the archive at the following location $ARCHIVE/phixflow-<current date>/WEB-INF/classes/
| Property | Previous File | Previous location | Notes |
|---|
| phixflow-datasource.xml | <property name="url">
<value>CONNECTION-STRING</value>
</property>
|
|
| db.usernameKey | phixflow-datasource.xml | <property name="username">
<value>ALIAS-USERNAME</value>
</property>
|
|
| phixflow-datasource.xml | <property name="password">
<value>ALIAS-PASSWORD</value>
</property>
|
|
logging.file.phixflow.base | logback.xml | <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
<file>logs/${logging.file.phixflow.base}.log</file>
| Just the base filename (phixflow_webappName) should be populated |
| phixflow-secret.xml | <property name="keystoreType">
<value>${keystore.type}</value>
</property>
|
|
| keystore.file | phixflow-secret.xml | <property name="keystoreFile">
<value>${keystore.file}</value>
</property> |
|
| keystore.passwordKey | phixflow-secret.xml | <property name="keystorePassEnvironmentVariable">
<value>${keystore.passwordKey}</value>
</property>
| If an environment variable was used to store the keystore password |
phixflow-keystore-password | phixflow-secret.xml | <property name="keystorePass">
<value>${phixflow-keystore-password}</value>
</property> | If the password was stored in the config file. |
If Active Directory was previously used the following configuration settings may need to be configured. Refer to phixflow-secret.xml for existing values.
Login - Active Directory Configuration
PhixFlow supports multiple modes of supporting authentication users. Users can be authenticated either with local credentials, native active directory based credentials, or using SAML to authenticate with active directory or other services, such as Okta.
Property | Requires Configuration | Default Value | Explanation |
|---|
login.activeDirectory.enabled | Often | false | Whether Active Directory integration is enabled. |
login.activeDirectory.domain | Often | http://example.com | The domain being logged into |
login.activeDirectory.alternativeDomain | Rarely | http://example2.com | If a user is not found in Active Directory with the primary domain (login.activeDirectory.domain) then the alternative domain will be tried. |
login.activeDirectory.url | Often | ldaps://ldap.example.com | Space separated list of domain LDAP servers. |
login.activeDirectory.dn | Often | ou=user accounts,dc=example,dc=com | If you have a large AD tree, searches may take some time, and this could lead to slow authentication for users. Therefore it is possible to specify a root DN (Distinguished name) at which PhixFlow will begin searching for the user. The Distinguished Name format is standard and further details can be found on the web. |
login.activeDirectory.timeout | Rarely | 5000 | You can specify a timeout. For each server specified, if the server does not respond within the limit specified by the timeout, it will try the next server. If the last server in the list times out, then the authentication will fail. The timeout is specified in milliseconds. |
login.activeDirectory.authenticationOnly | Occasionally | false | If this is true Active Directory is used for authentication when logging in, but not authorisation. This is a mixed user. The user must be configured in PhixFlow before logging in and user groups must be configured for the user. External groups will not be used to determine access rights. |
If SAML was previously used the following configuration settings may need to be configured. Refer to phixflow-secret.xml for existing values.
Login - Saml Configuration
PhixFlow supports multiple modes of supporting authentication users. Users can be authenticated either with local credentials, native active directory based credentials, or using SAML to authenticate with active directory or other services, such as Okta.
Property | Requires Configuration | Default Value | Explanation |
|---|
login.saml.enabled=false | Often | false | Configures whether SAML login is enabled |
login.saml.key= <none> | Often | <none> | Configures the identity provider's entity id . |
login.saml.attribute.domain= <none> | Often | <none> | Configures the domain of the saml users. |
login.saml.label=Single Sign In | Rarely | Single Sign In | The label to display |
login.saml.attributeMap=authenticationOnly | Often | authenticationOnly | Configures the integration method. authenticationOnly - SAML used for authentication but PhixFlow manages user details and permissions. okta - configured to support Okta based authentication and details. userDetails - allows configuration of authentication and user details to be provided by saml. |
login.saml.keystore.file | Often | classpath:keystore/samlKeystore.jks | Configures the location of the saml keystore |
login.saml.keystore.password | Often | <none> | Configures the password to the saml keystore. |
login.saml.keystore.key.password | Often | <none> | Configures the password to the secret in the saml keystore |
login.saml.keystore.key.alias | Rarely | samlKey | Configures the alias of the secret stored in the saml keystore |
login.saml.url.host | Often | localhost | Configures the externally resolvable hostname of the PhixFlow server. If behind a reverse proxy this will be the proxy’s hostname. |
login.saml.url.port | Occasionally | 443 | Configures the port of the PhixFlow server, or that of the reverse proxy if it is being used. |
login.saml.url.includePort | Rarely | false | Whether the port should be included in the generated url. |
login.saml.url.path | Occasionally | phixflow | Path that the webapp is installed under. If behind a reverse proxy this should be the path that the proxy forwards. Make sure that you do not precede the path with a /, i.e. it should be the name of the webapp only, as in the example. |
login.saml.metadata.entityId | Rarely | https://${login.saml.url.host}/${login.saml.url.path} | The value that globally identifies the PhixFlow instance. |
login.saml.metadata.entityBaseUrl | Rarely | https://${login.saml.url.host}/${login.saml.url.path} | The public facing URL of the PhixFlow instance. |
login.saml.metadata.file | Often | file:/opt/phixflow/data/saml-metadata/idp-metadata.xml | Path to the Identity Provider Metadata file. |
login.saml.metadata.trustCheck | Rarely | true | Whether to validate incoming signatures. |
login.saml.attribute.username | Occasionally | nameid | Used with the authenticationOnly and userDetails attribute map to define the appropriate mapping from the incoming metadata. |
login.saml.attribute.fullname | Occasionally | displayname | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. |
login.saml.attribute.firstname | Occasionally | givenname | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. |
login.saml.attribute.lastname | Occasionally | surname | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. |
login.saml.attribute.phonenumber | Occasionally | phonenumber | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. |
login.saml.attribute.company | Occasionally | company | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. |
login.saml.attribute.department | Occasionally | department | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. |
login.saml.attribute.email | Occasionally | email | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. |
login.saml.attribute.groups | Occasionally | group | Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata. |
login.saml.attribute.globalLogout | Occasionally | false | Used with the authenticationOnly and userDetails attribute map to determine whether logging out of PhixFlow should also trigger a logout of the identity provider. |
Company Logo
If you have configured PhixFlow to show your company logo, also copy $ARCHIVE/phixflow-<current date>/gui/images/customerLogo.svg from the archive to the corresponding directory in the new PhixFlow webapp.
Soft Links
If you have configured soft links (also called symlinks or datalinks) between PhixFlow and Tomcat, recreate them. Example scripts are provided below, these examples assume your application is called phixflow. For more details see Configuring Soft Links.
Windows
mklink /D C:\app\tomcat\webapps\phixflow\datalink C:\app\phixflow\data\phixflow\datalink
Linux
sudo ln -sf /opt/phixflow/data/phixflow/datalink /opt/tomcat/webapps/phixflow/datalink