Skip to main content

Security

YedMQ combines transport encryption, tenant isolation, plugin-driven access control, and authenticated management APIs. This page describes what is wired into the current implementation.

Transport security​

YedMQ can expose encrypted listeners for native MQTT clients and browser-based clients.

MQTT over TLS​

[listener.tcp_tls]
external = "0.0.0.0:8883"
verify_client_cert = false
cacert_file = "/path/to/ca.crt"
cert_file = "/path/to/server.crt"
key_file = "/path/to/server.key"

MQTT over WSS​

[listener.wss]
external = "0.0.0.0:8084"
verify_client_cert = false
cacert_file = "/path/to/ca.crt"
cert_file = "/path/to/server.crt"
key_file = "/path/to/server.key"

With verify_client_cert = false, the listener only authenticates the server and provides encrypted transport. With verify_client_cert = true, the listener switches to mTLS and requires client certificates signed by the CA configured in cacert_file. See Listener Configuration for the full listener layout.

Authentication and authorization​

YedMQ delegates identity checks and ACL decisions to the plugin system.

YedMQ currently has two separate authentication surfaces:

  • [listener.api.auth].users protects the REST management API only
  • MQTT client login and topic authorization are evaluated through the plugin hook chain

Adding a REST API user does not create a MQTT username and password login.

Default behavior when no plugin answers​

[plugin]
default_authenticate_result = false
default_authorize_result = false

With the shipped defaults, MQTT clients are rejected until an authentication or ACL plugin answers the request, or you temporarily relax the fallback for a local smoke test.

What plugins can decide​

During connect and message flows, plugins can validate or reject requests based on:

  • username and password
  • client ID
  • client IP
  • the already-verified client certificate presented on mTLS listeners
  • publish or subscribe action
  • topic name
  • tenant assignment

An authentication plugin can return a tenant_id, which becomes the isolation boundary for the client.

REST API protection​

The management API uses HTTP Basic Authentication configured in yedmq.toml. The example config binds the API to 127.0.0.1 and starts with an empty user list:

[listener.api]
external = "127.0.0.1:3456"

[listener.api.auth]
users = []
# Example:
# users = [{ username = "admin", password = "replace_me" }]

All /api/v1/* requests must include valid credentials after you configure them. In real deployments, add at least one strong password and avoid exposing the management API directly to untrusted networks.

Tenant isolation as a security boundary​

  • Different tenants cannot see each other's sessions, topics, or retained messages.
  • A client ID only needs to be unique inside one tenant.
  • Tenant-scoped REST paths reduce accidental cross-tenant operations.

For more detail on tenant assignment and routing, see Multiple Tenant.