Table of Contents
Configuration files
Configuration options can be specified in a number of different ways. These take precedence in the following orderJava System properties – set using the -D propertyName=value on the java command line / tomcat launch configuration
webapps/<phixflow>/WEB-INF/classes/local.properties – optional java properties file
webapps/<phixflow>/WEB-INF/classes/phixflow.properties – optional java properties file
Environment variables – using the environment form of the property name as described below
webapps/<phixflow>/WEB-INF/classes/context/server.properties – this contains the default values and should not be modified.
Keystore Files
Optionally, secrets such as database passwords can be kept encrypted in external secret files. Refer to XXX for instructions on how to configure this before proceeding with the installation.
Environment form of property names
As operating systems have stricter rules around valid characters in environment variable names, and prefer them to be in upper case, when using environment variables the property name should be converted as follows:
Replace dots (.) with underscores (_).
Remove any dashes (-).
Convert to uppercase.
For instance “db.url” would be looked up as “DB_URL” when resolved from environment variables.
Guidelines and advice for configuration
The context/server.properties file should never be changed. This is replaced on upgrade.
For a multi instance environment (e.g. DEV, QA and Prod) it is recommended that a common phixflow.properties file is used on all the instances, containing configuration settings that are identical on all environments. The local.properties file is then used for local overrides such as database url and passwords.
For single instance environments it is recommended to follow the same structure as with multi instance environments, but alternatively just one of either the phixflow.properties or local.properties files can be used to have all the configuration in a single file.
Only properties that have differing values from the default settings in the server.properties should be configured. This makes it easier to review and manage the configuration and ensures that fixes and improvements to the default settings will be applied automatically.
In docker environments it may be beneficial to use environment variables rather than settings in the local.properties file. Theis allows the same container image to be started as multiple instances with different configurations.
Configuration Properties
Java properties files use the \ as an escape character. When configuring paths on Windows either use forward slashes (e.g. c:/apps/phixflow) or double up the backslashes (e.g. c:\\apps\\phixflow).
Other properties can be referenced within a property value using the syntax ${property}
Installation Specific Properties
These properties are required for installation to succeed and are populated in the database. After installation is complete the values are not used any further.
Property | Requires Configuration | Default Value | Explanation |
|---|---|---|---|
install.customer_name | Always | <none> | The customer name as provided with your licence |
install.licence_key | Always | <none> | Licence key as provided with your licence. |
install.user.password | Often | <autogenerated> | Initial password of the default administrator user created during installation. If no value is configured a password is autogenerated and written to the security.log file. |
install.user.username | Often | admin | Username of the default administrator user created during installation. |
install.user.email | Often | <none> | Email address of the default administrator user created during installation. Can be updated after install in the User Details screen. |
install.user.firstname | Often | admin | First name of the default administrator user created during installation. Can be updated after install in the User Details screen. |
install.user.lastname | Often | admin | Last name of the default administrator user created during installation. Can be updated after install in the User Details screen. |
install.data.base | Often | ${install.application_loc}/data | Base location for the default data directory paths. This will commonly be configured to be “/opt/phixflow/data” |
install.data.temp | Occasionally | ${install.data.base}/temp | Populates an initial value in the System Configuration Temporary File Location |
install.data.email | Occasionally | ${install.data.base}/email | Populates an initial value in the System Configuration File Upload Directory |
install.data.import | Occasionally | ${install.data.base}/import | Populates an initial value in the System Configuration Import File Location |
install.data.export | Occasionally | ${install.data.base}/export | Populates an initial value in the System Configuration Export File Location |
install.data.template | Occasionally | ${install.data.base}/template | Populates an initial value in the System Configuration Template Location |
install.data.archive | Occasionally | ${install.data.base}/archive | Populates an initial value in the System Configuration Archive Directory |
install.data.restore | Occasionally | ${install.data.base}/restore | Populates an initial value in the System Configuration Restore Directory |
install.data.driver | Occasionally | ${install.data.base}/driver | Populates an initial value in the System Configuration Data Driver Directory |
install.data.download | Occasionally | ${install.data.base}/download | Populates an initial value in the System Configuration Download Location |
install.data.plugin | Occasionally | ${install.data.base}/plugin | Populates an initial value in the System Configuration Plugin Location |
install.data.file | Occasionally | ${install.data.base}/file | Populates an initial value in the System Configuration File Table Upload Location |
install.application_loc | Rarely | <autodetected> | Base application install location, e.g. |
install.pepperKey | Rarely | <none> | Externally defined value for the pepperKey. If not specified and a pepper key isn’t configured in the keystore then a value is autogenerated. |
install.phixflow_api_key | Rarely | <none> | Externally defined value for the Phixflow API credential signing key. If not specified and the api key isn’t configured in the keystore then a value is autogenerated. |
Database Connection Configuration
These are the basic settings to enable connection to the Phixflow database.
Property | Requires Configuration | Default Value | Explanation |
|---|---|---|---|
db.url | Always | <none> | The jdbc url of the database including any required parameters. |
phixflow-database-user | Often | <none> | Default key name containing the database username. May also be stored in the keystore. |
phixflow-database-password | Often | <none> | Default key name containing the database password. May also be stored in the keystore. |
Keystore Configuration
The keystore must be configured and populated during installation before Phixflow is first started. Using a keystore is optional.
Property | Requires Configuration | Default Value | Explanation |
|---|---|---|---|
keystore.file | Optional | /opt/secure/keystore.jks | Location of the keystore file. Only used if the keystore password is provided, otherwise use of the keystore is disabled. |
phixflow-keystore-password | Optional | <none> | Default key name containing the keystore password |
keystore.passwordKey | Rarely | phixflow-keystore-password | Name of the key containing the keystore password. |
pepper.key.name | Rarely | pepperKey | Name of the key containing the pepper key which is used for encrypting passwords |
api.key.name | Rarely | phixflow-api-key | Name of the key containing the api key which is used for signing api credentials. |
Login 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.
login.defaultForm=local Often Selects the form displayed when a user connects. #local - only allows local authentication, full - allows selecting any of the enabled authentication methods, auto - if SAML SSO is enabled allows logging in without displaying the login form if the user is already authenticated, activedirectory - supports active directory login only.
login.local.enabled=true rarely Allows disabling support of local login. This will prevent any local administrator accounts from being used.
login.saml.enabled=false Often Configures whether SAML login is enabled
login.saml.key= <none> Often Configures the identity provider's entity id .
login.saml.attribute.domain= <none> Often configures the domain of the saml users.
login.saml.label=Single Sign In Rarely The label to display
login.saml.attributeMap=authenticationOnly Often 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=classpath:keystore/samlKeystore.jks Often Configures the location of the saml keystore
login.saml.keystore.password=<none> Often Configures the password to the saml keystore.
login.saml.keystore.key.password=<none> Often Configures the password to the secret in the saml keystore
login.saml.keystore.key.alias=samlKey Rarely Configures the alias of the secret stored in the saml keystore
login.saml.url.host=localhost Often Configures the externally resolvable hostname of the Phixflow server. If behind a reverse proxy this will be the proxies hostname.
login.saml.url.port=443 Occasionally Configures the port of the Phixflow server, or that of the reverse proxy if it is being used.
login.saml.url.includePort=false Rarely Whether the port should be included in the generated url
login.saml.url.path=/phixflow Occasionally Path that the webapp is installed under. If behind a reverse proxy this should be the path that the proxy forwards.
login.saml.metadata.entityId=https://${login.saml.url.host}/${login.saml.url.path} Rarely The value that globally identifies the Phixflow instance .
login.saml.metadata.entityBaseUrl=https://${login.saml.url.host}/${login.saml.url.path} Rarely The public facing URL of the Phixflow instance
login.saml.metadata.file=file:/opt/phixflow/data/saml-metadata/idp-metadata.xml Often Path to the Identity Provider Metadata file
login.saml.metadata.trustCheck=true Rarely Whether to validate incoming siguatures.
login.saml.attribute.username=nameid Occasionally Used with the authenticationOnly and userDetails attribute map to define the appropriate mapping from the incoming metadata.
login.saml.attribute.fullname=displayname Occasionally Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.
login.saml.attribute.firstname=givenname Occasionally Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.
login.saml.attribute.lastname=surname Occasionally Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.
login.saml.attribute.phonenumber=phonenumber Occasionally Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.
login.saml.attribute.company=company Occasionally Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.
login.saml.attribute.department=department Occasionally Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.
login.saml.attribute.email=email Occasionally Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.
login.saml.attribute.groups=group Occasionally Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.
login.saml.attribute.globalLogout=false Occasionally Used with the authenticationOnly and userDetails attribute map to determine whether logging out of Phixflow should also trigger a logout of the identity provider.
login.activeDirectory.enabled=false Often Whether Active Directory integration is enabled
login.activeDirectory.domain=example.com Often The domain being logged into
login.activeDirectory.url=ldaps://ldap.example.com Often Space seperated list of domain LDAP servers.
login.activeDirectory.dn=ou=user accounts,dc=example,dc=com Often The root distinguished name to search under
login.activeDirectory.timeout=5000 Rarely Timeout for attempt to authenticate against each server.
login.activeDirectory.authenticationOnly=false Occasionally Whether only authentication is used from active directory, with user permissions and details being stored in Phixflow.