Authentication

FlowMQ provides unified client authentication. All protocols (MQTT, Kafka, AMQP) share the same account and credential system.

Whether authentication is enforced, and which authenticators are available, depend on the plan.

Plans and Project Isolation

Each project has its own accounts, credentials, and authorization policies, isolated from and invisible to other projects. How authentication works depends on the plan:

• Free plan: Authentication is always enforced and cannot be turned off. Every client must connect through the built-in Password authenticator with a valid username and password; anonymous access is not available, and only password authentication is supported.
• Pro / Enterprise plan: Projects run on a dedicated instance. Administrators choose which authenticator each protocol uses (Password or Webhook) and whether to require authentication at all. We strongly recommend keeping authentication enabled.

Authenticators

An authenticator verifies a client's credentials when it connects. FlowMQ supports the following authenticator types:

Type	Description	Plans
Password	Username/password authentication; credentials stored inside FlowMQ	All plans
Webhook	Forwards each authentication request to an external HTTP service that decides whether to allow it (see Webhook Authentication)	Pro / Enterprise

The password authenticator is built in: there is exactly one, and it cannot be created or deleted, only enabled or disabled. Other authenticators, such as Webhook, can be created as needed, each with its own name, and each protocol selects which one to use.

How each protocol carries credentials:

Protocol	Authentication method
MQTT	username / password in the CONNECT packet
Kafka	SASL/PLAIN
AMQP	SASL PLAIN

Managing Password Users

The built-in password authenticator stores its own username/password credentials. To manage them in the Dashboard:

1. Go to Authentication and open the built-in password authenticator.
2. Click Add User, enter a username and password, then click Create. To change a password or remove a user, select the entry in the user list and use Reset Password or Delete.
3. The password authenticator cannot be deleted; on the Pro / Enterprise plan, Disable it to stop using it (on the Free plan it stays enabled).

Choosing an Authenticator per Protocol

INFO

Available on dedicated Pro / Enterprise instances.

Each protocol uses at most one authenticator, and different protocols can use different ones. When a protocol has an authenticator selected, every connection on that protocol must pass the corresponding credential check; a protocol with no authenticator selected allows anonymous access.

This lets administrators configure authentication independently per protocol. For example, public MQTT access can use Webhook to integrate with an existing business system, internal Kafka access can use the built-in username/password authenticator, and AMQP can stay open and anonymous.

To set this up in the Dashboard:

1. Go to Authentication.
2. To use an external authenticator such as Webhook, click Create Authenticator, choose the type, enter a name and configuration, then click Create. The password authenticator is built in and does not need to be created.
3. In the per-protocol section, select the authenticator for the target protocol (MQTT, Kafka, AMQP), then click Save.

To remove authentication from a protocol, clear its authenticator in the per-protocol section and save; the protocol returns to anonymous access.

Anonymous Access

A protocol with no authenticator accepts connections without credentials, treating each as an anonymous identity that authorization policies can still allow or deny. To require credentials, select an authenticator for the protocol.

Webhook Authentication

INFO

Available on the Pro / Enterprise plan.

A Webhook authenticator delegates credential verification to an external authentication service: when a client connects, FlowMQ calls the service, which returns allow or deny and may attach an identity and attributes. It is well suited to reusing an existing account system, or to issuing attributes used for authorization at authentication time. Webhook currently handles username/password-style credentials only.

In the Dashboard's Create Authenticator flow, choose Webhook and fill in the following fields:

Field	Required	Default	Description
Webhook URL	Yes	—	The external authentication service address; must be reachable from FlowMQ over HTTP or HTTPS.
Timeout (seconds)	No	5	How long to wait for the service to respond before treating the attempt as failed.
Headers	No	—	Custom request headers as name/value pairs (e.g. an Authorization token); Content-Type: application/json is always included.
Custom Payload	No	—	A JSON object used as the request-body template, overriding the default; leave empty to send the default username/password fields. Values may use the placeholders below.
Principal ID Path	No	$.user_id	JSON path that extracts the identity from the service response.
Attributes Path	No	$.attributes	JSON path that extracts an attributes object from the response; the extracted attributes are attached to the identity for use by authorization policies, or referenced in resource names as ${principal.attributes.<name>}.

In the Headers values and the Custom Payload, the placeholders ${username}, ${password}, ${clientid}, ${peerhost}, and ${protocol} are available, expanded per connection at authentication time.

The authentication service should return success for allowed connections, and may include an identity and attributes in its JSON response, which FlowMQ extracts using the two paths above.

Example: to integrate an authentication service that requires a bearer token and returns a user ID and a team attribute, fill in:

• Webhook URL: https://auth.example.com/verify
• Timeout (seconds): 3
• Headers: Authorization = Bearer my-service-token
• Principal ID Path: $.data.id
• Attributes Path: $.data.attrs

For an allowed connection, the service returns:

{
  "result": "success",
  "data": {
    "id": "device-42",
    "attrs": { "team": "sensors" }
  }
}

FlowMQ then sets the identity to device-42 and the attributes to { "team": "sensors" }, which can be referenced in authorization policies as ${principal.attributes.team}.