# TLS and mTLS (/connectors/amqp/how-to/tls-and-mtls)



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.

<Callout type="info">
  TLS is configured server-side from the top-level &#x2A;*`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](/connectors/amqp/concepts/configuration). For the shared TLS/security model across
  KubeMQ connectors, see [Auth & security](/connectors/reference/auth-and-security).
</Callout>

## Ports and schemes [#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 [#tls-server-auth-vs-mtls]

The connector derives its TLS configuration from the `Security` mode.

### Server authentication only [#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.

```text
# conceptual: server-auth TLS + SASL PLAIN (JWT in password)
amqps://broker:5671   +   SASL PLAIN("audit-user", "<KUBEMQ_JWT>")
```

### Mutual TLS [#mutual-tls]

* The server presents its certificate **and** requires a client certificate
  (`RequireAndVerifyClientCert`), with the client-CA pool built from `Security.Ca`. The minimum
  protocol is **TLS 1.2**.
* A verified client certificate is the **precondition for SASL EXTERNAL**.

## SASL EXTERNAL — cert CN → ClientID [#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
  valid `ClientID` (`[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 `ClientID` exactly as for
  PLAIN — see [Authentication](/connectors/amqp/how-to/authentication).

```text
# conceptual: mTLS + SASL EXTERNAL (identity = client cert CN, no JWT)
amqps://broker:5671   +   client cert (CN=order-service)   +   SASL EXTERNAL
# resolved ClientID = "order-service"
```

<Callout type="warn">
  **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.
</Callout>

## How the TLS listener shares the `amqpmux` port [#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 [#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 [#related]

<Cards>
  <Card title="Authentication" href="/connectors/amqp/how-to/authentication" description="SASL PLAIN, EXTERNAL, and ANONYMOUS — identity precedence and the Casbin Read/Write checks at attach." />

  <Card title="Configuration" href="/connectors/amqp/concepts/configuration" description="The Security block, CONNECTORS_AMQP10_TLS_PORT, and the rest of the connector's server-side settings." />

  <Card title="Auth & security" href="/connectors/reference/auth-and-security" description="The shared TLS/mTLS and JWT security model across KubeMQ connectors." />
</Cards>