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:

SettingValueWhy
Secure WebSocket listenerEnabled on port 8084, with your TLS certificateSigners connect here.
Plain TCP and WebSocket listenersDisabled, or reachable only inside your networkThey carry tokens unencrypted.
AuthenticationJWT with JWKS, reading the token from the password fieldOnly your identity provider's users can connect.
mqtt.max_packet_size16MBSigning messages can be large.
mqtt.idle_timeout11mKeeps idle signer connections open between requests.
RetainerEnabled, 16MB maximum payload, 24-hour message expiryKeeps the latest message on each topic for a signer that connects later.
node.cookieA long random value from your secret managerThe cookie lets EMQX nodes join a cluster. Never keep the default.
DashboardCredentials from your secret manager, reachable only from your administration networkThe 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.


Did this page help you?