Documentation: Credentials
Flowy credentials
Flowy uniquely classifies credentials, required for accessing various systems or instances, as a distinct object type. This design choice brings several benefits and considerations in terms of security, functionality, and system integrity.
By treating credentials as a separate object type, Flowy ensures a clear demarcation between sensitive and non-sensitive data, which significantly reduces the risk of accidental exposure of credentials. This approach also simplifies the process of managing and changing credentials, making it more efficient and less prone to errors.
One of the key features of Flowy's credential management is the optional encryption of credential values. This feature allows users to add an extra layer of security to their sensitive data. It's worth noting that, intentionally, Flowy does not offer version control for credentials. This decision is a safety measure designed to prevent the potential risk of exposing previous versions of sensitive data, which could still be valuable for unauthorized access or malicious activities.
Note
While Flowy takes robust measures to protect credentials, it's important to be aware of certain security considerations. During the export to a module, specific properties and their values are intentionally omitted for security reasons. This is a deliberate design choice aimed at maintaining the security of the system and the confidentiality of the data. It helps prevent accidental leaks of sensitive information during the export process.
Flowy supports the following credential types:
AWS
Used by the S3 step, and for AWS SigV4 authentication in the REST step.
| Field | Required | Description |
|---|---|---|
accessKeyId | yes | AWS access key ID. |
secretKey | yes | AWS secret access key. |
region | yes | AWS region, for example eu-west-1. |
s3Bucket | no | S3 bucket name. The S3 step requires this field. Flowy always uses this bucket; you cannot override it per call. |
host | no | Custom endpoint URL, for an S3-compatible service. Leave empty to use the default AWS endpoint. |
Note
In the REST step, AWS SigV4 authentication reads only accessKeyId, secretKey and region. It does not use s3Bucket or host.
Flowy
Used for authentication against other Flowy instances, for example to call the Module Hub API.
| Field | Required | Description |
|---|---|---|
url | yes | Base URL of the other Flowy instance. |
apiKey | yes | API key for that instance. Flowy sends this value in the x-auth-token header, not as a bearer token. |
Gotenberg
Used to convert documents through a Gotenberg server.
| Field | Required | Description |
|---|---|---|
baseUrl | yes | Base URL of the Gotenberg server. Do not add a trailing slash. |
username | no | User name for HTTP Basic authentication. When empty, Flowy sends the request without authentication. |
password | no | Password for HTTP Basic authentication. Flowy always masks this field in API responses. |
IMAP
Used to connect to an IMAP mail server.
| Field | Required | Description |
|---|---|---|
host | yes | IMAP server host name or IP address. |
port | yes | IMAP server port. |
username | yes | Mail account user name. |
password | yes | Mail account password. |
Note
Enable or disable TLS on the step, not on the credential. The step property sslEnable controls this. When you give no folder on the step, Flowy reads the INBOX folder.
JDBC
Used to connect to a relational database.
| Field | Required | Description |
|---|---|---|
url | yes | JDBC connection URL. See the formats below. |
username | yes | Database user name. |
password | yes | Database user password. |
maxPoolSize | yes | Maximum number of pooled connections. Give a positive number. |
connectionTimeout | yes | Connection timeout, in milliseconds. Minimum value is 0. Default value is 30000. |
The following formats should be used for URL entry:
| Database | URL format |
|---|---|
| PostgreSQL | jdbc:postgresql://<host>:<port>/<databaseName> |
| MySql | jdbc:mysql://<host>:<port>/<databaseName> |
| Oracle | jdbc:oracle:thin:@<host>:<port>:<databaseName> |
| Sql Server | jdbc:sqlserver://<host>;databaseName=<databaseName> |
JMS
Used to connect to a JMS broker, through the Qpid JMS AMQP client.
| Field | Required | Description |
|---|---|---|
uri | yes | Connection URI. Use an AMQP URI, for example amqp://<host>:5672 or amqps://<host>:5671. Do not use an ActiveMQ tcp:// URI. |
username | no | User name. |
password | no | User password. Flowy connects anonymously when you leave username or password empty. |
destinationType | yes | One of QUEUE, TOPIC. |
destinationName | yes | Name of the queue or topic. |
JWT
Used to generate a signed JWT for use in a later step, for example as a bearer token in a REST step. This credential does not validate incoming JWTs.
| Field | Required | Description |
|---|---|---|
payload | no | Map of claims to put in the JWT. You can add more claims from the step. |
privateKey | yes | Private key, as PEM text (-----BEGIN PRIVATE KEY----- block), PKCS8 format. |
keyType | yes | Key algorithm name for java.security.KeyFactory, for example RSA or EC. |
signatureAlgorithm | no | Signature algorithm, one of HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512. |
Kafka
Used to produce and consume Kafka messages.
| Field | Required | Description |
|---|---|---|
bootstrapServers | yes | Comma-separated list of Kafka broker addresses. |
topic | yes | Topic name. |
groupId | no | Consumer group ID. Default value is flowy. |
Note
This credential does not support SSL or SASL configuration.
MongoDB
Used to connect to a MongoDB database.
| Field | Required | Description |
|---|---|---|
url | yes | Connection URL. See the format below. |
clientKey | no | Trust certificate, as PEM text. Give this field to enable a TLS connection, for example to connect to DocumentDB. |
inactiveTtl | yes | Maximum idle time for a pooled connection, in milliseconds. Minimum value is 0. Default value is 30000. |
Please enter the URL in the following format:
mongodb://<username>:<password>@host1:port1[,...hostN[:portN]]/<databaseName>?[options]
When attempting to connect to DocumentDB the following steps must be executed upfront:
# download certificates, these depend on the locaton of your server
# eu-west-1 is used throughout this example
wget https://truststore.pki.rds.amazonaws.com/eu-west-1/eu-west-1-bundle.pem
# convert the certificate
openssl x509 -outform der -in eu-west-1-bundle.pem -out eu-west-1-bundle.der
# import the certificate to the default keystore
keytool -import -alias eu-west-1-bundle -keystore $JAVA_HOME/lib/security/cacerts -file eu-west-1-bundle.der
Paymentsense Connect E
Used to call the Paymentsense Connect E payment API.
| Field | Required | Description |
|---|---|---|
hostUrl | yes | Base URL of the Connect E host. |
jwt | yes | JWT to send as a bearer token on every request. |
merchantUrl | yes | This field is not used by the current version. |
Paymentsense PAC
Used to call the Paymentsense PAC terminal API.
| Field | Required | Description |
|---|---|---|
hostUrl | yes | Base URL of the PAC host. |
username | yes | PAC user name. Flowy sends this with HTTP Basic authentication. |
apiKey | yes | PAC API key. Flowy sends this as the Basic authentication password. |
softwareHouseId | yes | Sent in the Software-House-Id header. |
installerId | yes | Sent in the Installer-Id header. |
Plugin
Used with the Plugin step. This credential has no fixed fields. Flowy merges the whole map into the plugin input, together with the plugin setting values and the step input. Each plugin defines which keys it reads.
Example: the HighMobility plugin reads serviceAccountApiKey, serviceAccountPrivateKey, clientCertificate, clientPrivateKey, oauthClientId and oauthClientSecret from this credential.
RabbitMQ
Used to produce and consume RabbitMQ messages.
| Field | Required | Description |
|---|---|---|
host | yes | Broker host name or IP address. |
port | yes | Broker port, for example 5672, or 5671 for TLS. |
username | yes | User name. |
password | yes | User password. |
virtualHost | no | RabbitMQ virtual host. When empty, Flowy uses the client library default, /. |
exchange | no | This field is not used by the current version. |
routingKey | yes (for the step to work) | Flowy uses this value as the queue name, not as an AMQP exchange routing key. |
rootCertificate | no | Root certificate for TLS connections. |
rootCertificatePassword | no | Password for rootCertificate. |
clientCertificate | no | Client certificate for mutual TLS. |
clientPrivateKey | no | Private key for clientCertificate. |
Note
Flowy enables TLS only when you give rootCertificate, clientCertificate and clientPrivateKey together.
Rest
Used with the REST step when the step does not need built-in authentication. This credential has no fixed fields and accepts free-form key-value pairs; Flowy does not validate the keys. Store any key-value pairs you need, and reference them from the step's URL, headers or body.
| Field | Required | Description |
|---|---|---|
certificate | no | Client certificate for mutual TLS. Flowy reads this key when present, regardless of the other keys you store. |
passphrase | no | Passphrase for certificate. |
Script
Used with the Script step. This credential has no fixed fields. Flowy merges the whole map into the script variables, so you can read each key from the script. In the script source, write #<key> to reference a credential field, for example #username.
Security
Used with the Security step, to encrypt, decrypt or sign a value.
| Field | Required | Description |
|---|---|---|
passphrase | no | Secret used as the encryption or signing key. When empty, Flowy uses the application default passphrase. Flowy uses this value as a raw text secret, not as a key file. |
key | no | This field is not used by the current version. |
Note
The AES method supports encryption and decryption. The HMAC-SHA256 method supports signing only; Flowy does not support decryption for this method.
Slack
Used with the Slack step, through the Slack Web API.
| Field | Required | Description |
|---|---|---|
token | yes | Slack API token. Flowy sends this value as a Bearer token. |
channelId | yes | Default channel ID. The step can override this value for a single call. |
SMTP
Used to send email through an SMTP server.
| Field | Required | Description |
|---|---|---|
host | yes | SMTP server host name or IP address. |
port | yes | SMTP server port. |
username | yes | Mail account user name. |
senderAddress | no | Sender email address. When empty, Flowy uses username. |
password | yes | Mail account password. |
connectionTimeout | no | Connection timeout, in milliseconds. Default value is 10000. |
timeout | no | Read timeout, in milliseconds. Default value is 10000. |
writeTimeout | no | Write timeout, in milliseconds. Default value is 10000. |
Note
Flowy always uses STARTTLS. The current version does not support an SSL-only connection.
Twilio
Used to send SMS messages through the Twilio REST API.
| Field | Required | Description |
|---|---|---|
sid | yes | Twilio account SID. Flowy sends this value as the HTTP Basic authentication user name. |
token | yes | Twilio auth token. Flowy sends this value as the Basic authentication password. |