Skip to main content

Protocol-Level Authentication

Authentication in MAPS Messaging is protocol-aware.
While all protocols ultimately delegate to the configured AuthManager realms, the way credentials are exchanged depends on the protocol.

General Model​

  • Each listener (NetworkManager.yaml) declares an auth: realm (mapped in SecurityManager.yaml).
  • The protocol handler extracts credentials from the connect frame or handshake.
  • MAPS validates those credentials against the chosen identity provider (built-in, LDAP, OIDC, mTLS, etc.).
  • On success, the connection is associated with a user identity and group memberships, which can be used by ACLs or auditing.

MQTT (3.1 / 3.1.1 / 5.0)​

  • Username / Password: taken from the MQTT CONNECT packet.
  • SASL mechanisms: supported over MQTT with sasl: config, e.g., CRAM-MD5.
  • TLS + Username/Password: common for IoT devices. Use ssl:// URLs for encrypted transport.
  • Example
- name: "MQTT SSL Listener"
  url: "ssl://0.0.0.0:8883/"
  protocol: mqtt
  auth: public
  sasl:
    mechanism: "CRAM-MD5"
    identityProvider: system

AMQP 1.0​

  • SASL: AMQP 1.0 has a built-in SASL negotiation phase.
  • Supported mechanisms: PLAIN, CRAM-MD5, others depending on provider.
  • MAPS binds SASL to the chosen auth: realm.
  • Example
- name: "AMQP 1.0 over TLS"
  url: "amqps://0.0.0.0:5671/"
  protocol: amqp
  auth: private
  sasl:
    mechanism: "PLAIN"

NATS​

  • User/Password or Token: provided in the CONNECT frame.
  • TLS + mTLS: NATS clients often use certificates for identity.
  • Anonymous mode: set auth: anon for test/dev.
  • Example
- name: "NATS TCP Listener"
  url: "tcp://0.0.0.0:4222/"
  protocol: nats
  auth: anon

REST API​

  • Bearer Tokens (JWT/OIDC): typically used with Auth0 or Cognito providers.
  • mTLS: client certificate validation is also supported.
  • Basic Auth: username/password in HTTP headers is supported for legacy integrations.
  • Example
- name: "REST API (Cognito)"
  url: "https://0.0.0.0:8443/"
  protocol: rest
  auth: public

Clients send an Authorization: Bearer <JWT> header.

STOMP​

  • CONNECT frame includes login and passcode headers.
  • Mapped into the chosen auth: realm.
  • Works with username/password providers (built-in, LDAP, Apache, etc.).

CoAP / MQTT-SN (UDP)​

  • Use DTLS for transport security.
  • Support for mTLS certificate-based authentication.
  • DTLS handshake enforces the chosen auth: realm.
  • CoAP/MQTT-SN message headers themselves do not carry username/password fields.

Bridging & Propagation​

When MAPS bridges between protocols:

  • Authentication is always enforced at the entry protocol.
  • Identity can propagate internally, so messages retain information about their origin.
  • Optional: MAPS can strip credentials when forwarding to external brokers, or re-authenticate with bridge-specific credentials.

Notes & Best Practices​

  • Always prefer TLS/DTLS transports for security.
  • Use per-protocol realms to mix anonymous, password-based, and OIDC auth as needed.
  • For large IoT deployments, combine built-in auth for bootstrap and OIDC (Auth0/Cognito) for production.
  • Enable debug=true in JAAS config during setup; disable it for production.