TLS and mTLS
Securing the AMQP 1.0 connector — amqps on port 5671, server-auth TLS vs mutual TLS, and SASL EXTERNAL with the certificate CN as ClientID.
The KubeMQ AMQP 1.0 connector exposes TLS on amqps://:5671, mutual TLS (mTLS), and SASL
EXTERNAL so you can harden it for production. This guide documents how to configure them.
TLS is configured server-side from the top-level Security block (not from any AMQP-specific
field). The runnable examples all use plain amqp:// against a stock dev broker; to use
amqps://, supply your own certificates and configure the Security block — see
Configuration. For the shared TLS/security model across
KubeMQ connectors, see Auth & security.
Ports and schemes
The connector listens on two ports, both shared with the AMQP 0-9-1 connector through the
amqpmux listener:
| Scheme | Port | When active |
|---|---|---|
amqp://host:5672 | 5672 (plain / SASL) | always (unless CONNECTORS_AMQP10_PORT=0) |
amqps://host:5671 | 5671 (TLS) | only when the top-level Security block is configured |
The TLS port is controlled by CONNECTORS_AMQP10_TLS_PORT (default 5671; 0 disables it). The
certificate material, the CA, and the mode all come from the top-level Security block. There
is no AMQP-over-WebSocket: raw TCP and TLS only.
TLS server-auth vs mTLS
The connector derives its TLS configuration from the Security mode.
Server authentication only
- The server presents its certificate; the minimum protocol is TLS 1.2.
- No client certificate is requested or verified.
- The client authenticates separately, at the SASL layer (PLAIN with a JWT, or ANONYMOUS if auth
is off). Use
amqps://for the transport and SASL PLAIN for identity.
# conceptual: server-auth TLS + SASL PLAIN (JWT in password)
amqps://broker:5671 + SASL PLAIN("audit-user", "<KUBEMQ_JWT>")Mutual TLS
- The server presents its certificate and requires a client certificate
(
RequireAndVerifyClientCert), with the client-CA pool built fromSecurity.Ca. The minimum protocol is TLS 1.2. - A verified client certificate is the precondition for SASL EXTERNAL.
SASL EXTERNAL — cert CN → ClientID
EXTERNAL is offered only when the connection is mTLS and the client presented a
verified client certificate. When you authenticate with EXTERNAL:
- No JWT is sent. The certificate is the credential.
- The client identity (
ClientID) becomes the client certificate's Subject CN, sanitized to a validClientID([a-zA-Z0-9_-], ≤ 256). An empty CN is rejected as an auth failure. - Authorization (Read/Write at attach) then runs against that CN-derived
ClientIDexactly as for PLAIN — see Authentication.
# conceptual: mTLS + SASL EXTERNAL (identity = client cert CN, no JWT)
amqps://broker:5671 + client cert (CN=order-service) + SASL EXTERNAL
# resolved ClientID = "order-service"EXTERNAL is available only when Security.Mode == mtls. Plain TLS (server-auth only) does
not present a verified client certificate, so EXTERNAL is not offered there — fall back to PLAIN
(JWT) or ANONYMOUS. The offered-mechanism order is EXTERNAL → PLAIN → ANONYMOUS, so on an mTLS
connection a spec-conformant client that supports EXTERNAL picks it first.
How the TLS listener shares the amqpmux port
Both AMQP dialects (0-9-1 and 1.0) coexist on the same ports. The amqpmux listener accepts
every connection, reads the 8-byte AMQP protocol header, and dispatches by dialect:
| Header bytes | Meaning |
|---|---|
AMQP\x00\x00\x09\x01 | AMQP 0-9-1 |
AMQP\x00\x01\x00\x00 | AMQP 1.0, plain (bare/AMQP layer) |
AMQP\x03\x01\x00\x00 | AMQP 1.0, SASL layer |
AMQP\x02\x01\x00\x00 | AMQP 1.0, TLS token — only meaningful on the TLS listener |
For TLS, the connection is wrapped in the Security-block TLS configuration before the header
is interpreted. The upshot for clients: point an amqps:// AMQP 1.0 client at :5671, and the
same listener that serves 0-9-1 routes you to the 1.0 engine.
Production checklist
| Goal | Configuration |
|---|---|
| Encrypt transport, authenticate clients with JWT | Security mode tls + amqps://:5671 + SASL PLAIN (JWT in password) |
| Authenticate clients with certificates (no JWT) | Security mode mtls + amqps://:5671 + SASL EXTERNAL (CN → ClientID) |
Keep plain amqp:// for local/dev | leave CONNECTORS_AMQP10_PORT=5672; the examples use this |
| Disable the TLS port | CONNECTORS_AMQP10_TLS_PORT=0 (or leave the Security block unset) |
Related
Authentication
SASL PLAIN, EXTERNAL, and ANONYMOUS — identity precedence and the Casbin Read/Write checks at attach.
Configuration
The Security block, CONNECTORS_AMQP10_TLS_PORT, and the rest of the connector's server-side settings.
Auth & security
The shared TLS/mTLS and JWT security model across KubeMQ connectors.
Was this page helpful?
Reliability
AMQP 1.0 delivery guarantees on KubeMQ — settlement modes, delivery-state to Ack/NAck mapping, at-least-once vs at-most-once, and durable subscriptions.
Address Mapping
The reference for how an AMQP 1.0 terminus address maps to a KubeMQ pattern and channel — grammar, longest-prefix rules, charset, and anonymous routing.