Versions Compared

Old Version 10

changes.mady.by.user Thomas Swindells

Saved on

compared with

New Version Current

changes.mady.by.user Chris Welford

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

...

Table of Contents

Table of Contents
minLevel1
maxLevel6
include
outlinefalse
indent
stylenone
excludeTable of Contents
typelist
class
printabletrue

Configuration Files

Excerpt
nameConfigurationFiles

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

  1. Java System properties – set using the -D propertyName=value on the java command line / tomcat launch configuration

  2. webapps/<phixflow>/WEB-INF/classes/local.properties – optional java properties filejava properties file

  3. webapps/<phixflow>/WEB-INF/classes/phixflow.properties – optional java properties file

  4. Environment variables – using the environment form of the property name as described below

  5. webapps/<phixflow>/WEB-INF/classes/context/phixflow.properties – optional java properties file

  6. Environment variables – using the environment form of the property name as described below

  7. webapps/<phixflow>/WEB-INF/classes/context/server.properties – this contains the default values and should not be modifiedserver.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 recommended 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.

...

The jdbc url of the database including any required parameters.
E.g.
jdbc:mysql://localhost/phixflow?defaultFetchSize=2000&?allowPublicKeyRetrieval=true
jdbc:oracle:thin:@//localhost:1521/pdb.local
jdbc:sqlserver://;database=webtrunk;sendStringParametersAsUnicode=false
Excerpt
nameInstallTimeProperties

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.

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>

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.

It is strongly recommended this is changed immediately after installation.

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 installation in the User Details screen.

install.user.firstname

Often

admin

First name of the default administrator user created during installation. Can be updated after installation in the User Details screen.

install.user.lastname

Often

admin

Last name of the default administrator user created during installation. Can be updated after installation 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.upload

Occasionally

${install.data.base}/upload

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.

ZB example missing here

install.pepperKey

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 pepperKeyPhixFlow API credential signing key. If not specified and a pepper the API 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.

Excerpt
nameBasicDatabase

.

Excerpt
nameBasicDatabase

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.
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;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
nameKeystore

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.

Excerpt
nameLoginLoginBasic

Login - Basic 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.defaultForm

Often

local

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.default=local

Often

local

The default domain for login.

login.local.enabled=true

Rarely

true

Allows disabling support of local login. This will prevent any local administrator accounts from being used.used.

Configures the password to the saml keystore
Excerpt
nameLoginSaml

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.

file

password

Often

classpath:keystore/samlKeystore.jks

<none>

Configures the password to the secret in the saml keystore

login.saml.keystore.key.alias

Rarely

samlKey

Configures the

location

alias of the secret stored in the saml keystore

login.saml.

keystore

url.

password

host

Often

<none>

localhost

Configures the externally resolvable hostname of the PhixFlow server. If behind a reverse proxy this will be the proxy’s hostname.

login.saml.

keystore

url.

key.password

port

Often

Occasionally

<none>

443

Configures the

password to the secret in the saml keystore

port of the PhixFlow server, or that of the reverse proxy if it is being used.

login.saml.

keystore

url.

key.aliasConfigures the alias of the secret stored in the saml keystore

includePort

Rarely

samlKey

false

Whether the port should be included in the generated url.

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

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.

url

metadata.

port

entityId

Occasionally

443

Configures the port of the PhixFlow server, or that of the reverse proxy if it is being used.

Rarely

https://${login.saml.url.

includePort

Rarely

false

Whether the port should be included in the generated url.

host}/${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

}

The value that globally identifies the PhixFlow instance.

login.saml.metadata.

entityId

entityBaseUrl

Rarely

https://${login.saml.url.host}/${login.saml.url.path}

The

value that globally identifies

public facing URL of 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

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.

metadata

attribute.

filePath to the Identity Provider Metadata file

firstname

Often

file:/opt/phixflow/data/saml-metadata/idp-metadata.xml

Occasionally

givenname

Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.

login.saml.

metadata

attribute.

trustCheck

lastname

Rarely

Occasionally

true

Whether to validate incoming signatures

surname

Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.

login.saml.attribute.

username

phonenumber

Occasionally

nameid

phonenumber

Used with the

authenticationOnly and

userDetails attribute map to define the appropriate mapping from the incoming metadata.

login.saml.attribute.

fullname

company

Occasionally

displayname

company

Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.

login.saml.attribute.

firstname

department

Occasionally

givenname

department

Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.

login.saml.attribute.

lastname

email

Occasionally

surname

email

Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.

login.saml.attribute.

phonenumber

groups

Occasionally

phonenumber

group

Used with the userDetails attribute map to define the appropriate mapping from the incoming metadata.

login.saml.attribute.

company

globalLogout

Occasionally

company

false

Used with the authenticationOnly and 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

determine whether logging out of PhixFlow should also trigger a logout of the identity provider.

Whether Active Directory integration is enabled
Excerpt
nameLoginActiveDirectory

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.

enabled

url

Often

false

ldaps://ldap.example.com

Space separated list of domain LDAP servers.

login.activeDirectory.

domain

dn

Often

ou=user accounts,dc=example

.com

The domain being logged into.

login.activeDirectory.url

Often

ldaps://ldap.example.com

Space separated list of domain LDAP servers

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

dn

timeout

Rarely

Often

ou=user accounts,dc=example,dc=com

The root distinguished name to search under.

login.activeDirectory.timeout

Rarely

5000

Timeout for attempt to authenticate against each server

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

Whether only authentication is used from active directory, with user permissions and details being stored in PhixFlow.

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.

Excerpt
nameLogging

Logging Configuration

valid Where a level is required this can be one of level values: OFF, ERROR, WARN, INFO, DEBUG, TRACE, ALL

Property

Requires Configuration

Default Value

Explanation

logging.file.directory

Occasionally

logs

The directory logs are written into, relative to the Tomcat root directory.

logging.file.phixflow.base

Occasionally

phixflow

Base name of the standard PhixFlow log file.

logging.file.security.base

Occasionally

security

Base name of the security log file.

logging.stdout.level

Occasionally

OFF

Used to control the minimum log message level permitted to be output to stdout.ZB is “stdout” a typo?standard output.

logging.root.level

Rarely

INFO

Configures the default minimum log level that can be generated.

logging.file.phixflow.main

Rarely

${logging.file.directory}/${logging.file.phixflow.base}.log

Defines the path and name of the standard PhixFlow log file

logging.file.phixflow.archive

Rarely

${logging.file.directory}/${logging.file.phixflow.base}.%d{yyyy-MM-dd}.log

Defines the path and name of archived standard PhixFlow log files.

logging.file.security.main

Rarely

${logging.file.directory}/${logging.file.security.base}.log

Defines the path and name of the security log file.

logging.file.security.archive

Rarely

${logging.file.directory}/${logging.file.security.base}.%d{yyyy-MM-dd}.log

Defines the path and name of archived security log files.

logging.file.phixflow.level

Rarely

ALL

Used to control the minimum log message level permitted to be output to standard log file.

logging.file.security.level

Rarely

ALL

Used to control the minimum log message level permitted to be output to security log file.