MQTT broker
Run and secure the EMQX broker that carries messages between io.sign and its signers
Signers exchange messages with io.sign through an MQTT broker. A self-hosted deployment needs its own broker. io.sign is built and tested with EMQX, and this page describes an EMQX setup.
How signers connect
Mobile Signers and Virtual Signers connect to the broker over secure WebSockets, for example wss://mqtt.example.com:8084/mqtt. Each signer sends its identity provider token as the MQTT password, and the broker checks the token against your identity provider's JWKS endpoint. Only users of your identity provider can connect.
Tell signers where the broker is
Set the URL that io.sign gives signers:
SETTINGS_DEFAULT_MQTT_BROKER_URL=wss://mqtt.example.com:8084/mqtt
# Only if signers need the certificate to trust the broker:
# SETTINGS_DEFAULT_MQTT_BROKER_CERTIFICATE=<certificate>io.sign uses these values when its settings table holds no broker setting. A setting stored in the table takes precedence, so check the table before you rely on a changed variable. Configure each Virtual Signer's IOSIGN_SIGNER_MQTT_URL for the same broker. See Virtual Signer configuration.
Configure EMQX
Use these settings:
| Setting | Value | Why |
|---|---|---|
| Secure WebSocket listener | Enabled on port 8084, with your TLS certificate | Signers connect here. |
| Plain TCP and WebSocket listeners | Disabled, or reachable only inside your network | They carry tokens unencrypted. |
| Authentication | JWT with JWKS, reading the token from the password field | Only your identity provider's users can connect. |
mqtt.max_packet_size | 16MB | Signing messages can be large. |
mqtt.idle_timeout | 11m | Keeps idle signer connections open between requests. |
| Retainer | Enabled, 16MB maximum payload, 24-hour message expiry | Keeps the latest message on each topic for a signer that connects later. |
node.cookie | A long random value from your secret manager | The cookie lets EMQX nodes join a cluster. Never keep the default. |
| Dashboard | Credentials from your secret manager, reachable only from your administration network | The default admin/admin login gives full control of the broker. |
This is the authentication block, with your JWKS endpoint in place of the example:
authentication = [
{
enable = true
mechanism = jwt
use_jwks = true
endpoint = "https://identity.example.com/.well-known/jwks.json"
refresh_interval = 300
from = password
ssl { enable = true }
}
]The broker must be able to reach your identity provider's JWKS endpoint. The backend's JWT_PROVIDERS setting doesn't configure the broker.
Run more than one node
For high availability, run at least two EMQX nodes as a cluster behind a load balancer. All nodes must share the same node.cookie.
Pin the EMQX image to a specific version, rather than latest, so an upgrade happens only when you choose.
Check the broker
- Mobile Signers and Virtual Signers show as connected after they sign in.
- The EMQX dashboard lists a client for each connected signer.
- A connection attempt with an expired or forged token is refused.
If signers can't connect, check that their tokens come from the identity provider whose JWKS endpoint the broker uses. See Authentication.
Updated 20 days ago