Configuration Files

Excerpt

name	ConfigurationFiles

Configuration options can be specified in a number of different ways. These take precedence in the following order:

Java 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

In other words

a setting in phixflow.properties takes precedence over a setting for that same property in server.properties
a setting in local.properties takes precedence over a setting for that same property in either or both server.properties or phixflow.properties

Keystore Files

Optionally, secrets, such as database passwords, can be kept encrypted in external secret files. Refer to Configure a Keystore and Aliases 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 example, “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 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 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 you use only the local.properties 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. This allows the same container image to be started as multiple instances with different configurations.

...

Excerpt

name	BasicDatabase

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. For more information on defining the database URL consult your Database Administrator.
E.g.
Example URLs

MySQL

jdbc:mysql://localhost/phixflow?defaultFetchSize=2000&?allowPublicKeyRetrieval=true
Note the allowPublicKeyRetrieval parameter may be required depending on your setup

Oracle

jdbc:oracle:thin:@//localhost:1521/pdb.local

SQL Server

jdbc:sqlserver://;database=webtrunk;sendStringParametersAsUnicode=false/;database=webtrunk;sendStringParametersAsUnicode=false;encrypt=false

MS SQL Server JDBC driver version 12.6.1 onwards, defaults to using an encrypted connection which may require additional parameters to be added to the URL. If encryption is not required, add 'encrypt=false' to the URL.

See https://learn.microsoft.com/en-us/sql/connect/jdbc/microsoft-jdbc-driver-for-sql-server?view=sql-server-ver16

phixflow-database-user

Often

<none>

Default key name containing the database username. May This can also be stored in the keystore.

phixflow-database-password

Often

<none>

Default key name containing the database password. May This can also be stored in the keystore.

...

Excerpt

name	LoginSaml

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 forwardsthis 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.

Excerpt

name	LoginActiveDirectory

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.

...

Versions Compared

Old Version 15

New Version Current

Key

Table of Contents

Configuration Files

Keystore Files

Environment Form of Property Names

Guidelines and Advice for Configuration

Database Connection Configuration

Page Comparison

Versions Compared

Old Version 15

New Version Current

Key

Table of Contents

Configuration Files

Keystore Files

Environment Form of Property Names

Guidelines and Advice for Configuration

Database Connection Configuration

Login - Saml Configuration

Login - Active Directory Configuration