RabbitMQ TLS Tutorial

The following guide deploys the Minimus RabbitMQ image together with custom self-signed, locally issued certificates generated with OpenSSL to help you get started. The tutorial is appropriate for local development, internal services, and private clusters.

What this guide demonstrates

TLS handshake validation
Server certificate trust
Basic auth and RabbitMQ DB operations
Image compatibility

Components

RabbitMQ image built by Minimus: RabbitMQ configured for TLS on both the AMQP port (5671) and the management API port (15671).
certgen.sh script: Dynamic certificate generation shell script that uses OpenSSL.
minidebug image: A Minimus dev toolkit that provides a shell, OpenSSL, and other utilities used to generate the certificates.

Directory Structure

.
├── certgen.sh             # Certificate generation script
├── create-certs.yml       # Compose file to run certgen container
├── certs/                 # Generated certificates (created by certgen.sh)
│   ├── ca_certificate.pem
│   ├── server_certificate.pem
│   └── server_key.pem
├── rabbitmq.conf          # RabbitMQ config file for TLS
├── enabled_plugins        # Enables the management plugin
└── docker-compose.yml     # Compose file to run RabbitMQ

2 TLS listeners for 2 trust models

This setup configures two independent TLS listeners, each with a different trust requirement:

AMQP (5671) — This is the protocol port your messaging clients connect to. ssl_options.verify = verify_none means the server presents its certificate for the client to trust, but never asks the client for one back. Hence, no client certificate is required.
Management API (15671) — This is used by rabbitmqadmin, curl, and the management UI. management.ssl.verify = verify_peer means the server will validate a client certificate if one is presented, but fail_if_no_peer_cert = false makes presenting one optional.

For local development and testing, server-side trust is sufficient: the CA certificate alone (--cacert / --ssl-ca-cert-file) is all a client needs to establish the TLS connections, so this guide skips generating a client certificate. If you later move this setup toward a multi-tenant or zero-trust environment, you can require client certificates on either listener by switching fail_if_no_peer_cert to true.

Deploy RabbitMQ with TLS certificates

Step 1: Generate TLS certificates

Save script that generates TLS certificates

Save the following script to a file named certgen.sh. The script is used to generate the self-signed CA and server certificates and store them in a certs folder in a Docker volume.

certgen.sh

#!/bin/sh
set -e
cd /certs

cat > openssl.cnf <<EOF
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
CN = rabbitmq

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = rabbitmq
DNS.2 = localhost
IP.1 = 127.0.0.1
IP.2 = 192.168.20.0
IP.3 = 192.168.20.2
IP.4 = 192.168.20.3

[v3_ca]
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, keyCertSign, cRLSign
EOF

# Generate CA
openssl genrsa -out ca-key.pem 2048
openssl req -x509 -new -nodes -key ca-key.pem -sha256 -days 365 \
  -out ca_certificate.pem \
  -subj "/CN=Test CA" -extensions v3_ca -config openssl.cnf

# Generate server cert
openssl genrsa -out server_key.pem 2048
openssl req -new -key server_key.pem -out server.csr -config openssl.cnf -extensions v3_req
openssl x509 -req -in server.csr -CA ca_certificate.pem -CAkey ca-key.pem -CAcreateserial \
  -out server_certificate.pem -days 365 -sha256 -extfile openssl.cnf -extensions v3_req

chmod 600 *.pem
chown -R 1000:1000 /certs/*.pem
chmod 644 /certs/*.pem

Save Docker Compose configuration

Save the following YAML configuration to a file named create-certs.yml. The configuration uses the Minimus minidebug image to generate the certificates with the certgen.sh shell script. Minidebug is a Minimus dev toolkit that provides a shell, OpenSSL, and other utilities.

create-certs.yml

services:
  create_certs:
    image: reg.mini.dev/minidebug:latest
    container_name: rabbit_certs
    volumes:
    - ./certs:/certs
    - ./certgen.sh:/certgen.sh:ro
    entrypoint:
    - /bin/sh
    - /certgen.sh
    network_mode: none

Generate certificates

Run the following to generate the certificates:

docker compose -f create-certs.yml up

WARN[0000] No services to build
[+] up 1/1
 ✔ Container rabbit_certs Created                                                                        0.2s
Attaching to rabbit_certs
rabbit_certs  | Certificate request self-signature ok
rabbit_certs  | subject=CN=rabbitmq
rabbit_certs exited with code 0

Congrats! You have just generated the following self-signed certificates:

CA certificate (ca_certificate.pem)
Server certificate and key (server_certificate.pem, server_key.pem) valid for rabbitmq, localhost, 127.0.0.1, 192.168.20.0, 192.168.20.2, and 192.168.20.3

The setup ensures:

Proper SANs for rabbitmq and localhost
Server cert with both serverAuth and clientAuth extended key usage

In the next steps, you will mount these certificates into the RabbitMQ container.

Step 2: Deploy RabbitMQ server

Save the configuration file

Save the configuration to a file named rabbitmq.conf.

rabbitmq.conf

## AMQP TLS listener
listeners.ssl.default = 5671

ssl_options.cacertfile = /certs/ca_certificate.pem
ssl_options.certfile   = /certs/server_certificate.pem
ssl_options.keyfile    = /certs/server_key.pem
ssl_options.verify     = verify_none
ssl_options.fail_if_no_peer_cert = false

## Allow remote login for non-guest users
loopback_users.guest = false

## Management API over HTTPS
management.ssl.port = 15671
management.ssl.cacertfile = /certs/ca_certificate.pem
management.ssl.certfile   = /certs/server_certificate.pem
management.ssl.keyfile    = /certs/server_key.pem
management.ssl.verify     = verify_peer
management.ssl.fail_if_no_peer_cert = false

Save the enabled plugins

Save the enabled plugins file.

enabled_plugins

[rabbitmq_management].

Save Docker Compose script

Save the following Docker Compose script to a file named docker-compose.yml. This script sets up the RabbitMQ service with a healthcheck, mounts a volume with the certificates, maps ports 15671 and 5671.

docker-compose.yml

services:
  rabbitmq:
    image: reg.mini.dev/rabbitmq:latest-dev
    container_name: rabbitmq-lts
    volumes:
      - ./certs:/certs:ro
      - ./rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro
      - ./enabled_plugins:/etc/rabbitmq/enabled_plugins:ro
    environment:
      RABBITMQ_DEFAULT_USER: testuser
      RABBITMQ_DEFAULT_PASS: testpass
    ports:
      - "5671:5671"     # AMQP over TLS
      - "15671:15671"   # Management UI over TLS

Run RabbitMQ

Start the RabbitMQ container:

docker compose -f docker-compose.yml up -d

 ✔ Image reg.mini.dev/rabbitmq:latest-dev Pulled                                                        15.1s
...
 ✔ Network rabbitmq-test_default          Created                                                        0.1s
 ✔ Container rabbitmq-lts                 Created   

Step 3: Test your RabbitMQ server

We will use rabbitmqadmin, the RabbitMQ CLI, to connect over TLS and run tests. For example, here are a few commands you can try out:

Check db health:

docker exec -it rabbitmq-lts rabbitmqctl status
curl -u testuser:testpass https://localhost:15671/api/healthchecks/node \
  --cacert ./certs/ca_certificate.pem

Runtime

OS PID: 13
OS: Linux
Uptime (seconds): 356
Is under maintenance?: false
RabbitMQ version: ...
RabbitMQ release series support status: see https://www.rabbitmq.com/release-information
Node name: rabbit@...
Erlang configuration: ...
Crypto library: OpenSSL ...
Erlang processes: 411 used, 1048576 limit
Scheduler run queue: 1
Cluster heartbeat timeout (net_ticktime): 60

Plugins

Enabled plugin file: /etc/rabbitmq/enabled_plugins
Enabled plugins:

 * rabbitmq_management
 * rabbitmq_management_agent
 * rabbitmq_web_dispatch
 * amqp_client
 * cowboy
 * oauth2_client
...

Listeners

Interface: [::], port: 15671, protocol: https, purpose: HTTP API over TLS (HTTPS)
Interface: [::], port: 25672, protocol: clustering, purpose: inter-node and CLI tool communication
Interface: [::], port: 5672, protocol: amqp, purpose: AMQP 0-9-1 and AMQP 1.0
Interface: [::], port: 5671, protocol: amqp/ssl, purpose: AMQP 0-9-1 and AMQP 1.0 over TLS

Verify the AMQP TLS listener itself (port 5671) with openssl s_client. This confirms the handshake and certificate the broker presents to actual messaging clients, independent of the management API tested in the next step:
echo | openssl s_client -connect localhost:5671 -CAfile ./certs/ca_certificate.pem
CONNECTED(00000003) depth=1 CN = Test CA verify return:1 depth=0 CN = rabbitmq verify return:1 --- Certificate chain 0 s:CN = rabbitmq i:CN = Test CA 1 s:CN = Test CA i:CN = Test CA --- ... subject=CN = rabbitmq issuer=CN = Test CA --- Verification: OK --- New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384 ... Verify return code: 0 (ok) --- DONE
openssl s_client runs on your host machine, not inside the container, so the verify result depends on the OpenSSL build installed there. You may see either Verify return code: 0 (ok) or 19 (self-signed certificate in certificate chain) — both mean the handshake succeeded using the certificate signed by your CA. Messaging client libraries (pika, amqplib, etc.) that trust the CA connect the same way regardless.

Test connectivity using rabbitmqadmin. Note that rabbitmqadmin talks to the management HTTP API, so it connects on port 15671 (the TLS management port), not the AMQP port 5671:

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  list queues

No items

Create a test vhost (for example test_vhost). A vhost is RabbitMQ’s equivalent of a database — a logically separate group of queues, exchanges, and permissions:

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  declare vhost name=test_vhost

vhost declared

List all vhosts.

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  list vhosts

+------------+----------+
|    name    | messages |
+------------+----------+
| /          |          |
| test_vhost |          |
+------------+----------+

Declare a durable queue named docs in test_vhost (the equivalent of creating a collection):

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  --vhost=test_vhost \
  declare queue name=docs durable=true

Then publish a message to it:

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  --vhost=test_vhost \
  publish exchange=amq.default routing_key=docs payload="Welcome to TLS RabbitMQ running on a Minimus image"

Create a user (for example, appuser with read/write/configure permissions on test_vhost), get the user’s permission details, and delete the user:

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  declare user name=appuser password=apppass tags=management

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  declare permission vhost=test_vhost user=appuser configure=.* write=.* read=.*

docker exec -it rabbitmq-lts rabbitmqctl list_user_permissions appuser

Listing permissions for user "appuser" ...
vhost   configure       write   read
test_vhost      .*      .*      .*

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  delete user name=appuser

Publish a new message to the queue:

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  --vhost=test_vhost \
  publish exchange=amq.default routing_key=docs payload="Welcome to TLS RabbitMQ running Minimus image"

Message published

Get all messages from the queue:

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  --vhost=test_vhost \
  get queue=docs count=10 ackmode=ack_requeue_false

Delete the vhost:

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  delete vhost name=test_vhost

vhost deleted

Building Secure Apps

Tutorials

K8s Guides

TLS Guides

Troubleshooting

Debugging

What this guide demonstrates

Components

Directory Structure

2 TLS listeners for 2 trust models

Deploy RabbitMQ with TLS certificates

Step 1: Generate TLS certificates

Step 2: Deploy RabbitMQ server

Step 3: Test your RabbitMQ server

​What this guide demonstrates

​Components

​Directory Structure

​2 TLS listeners for 2 trust models

​Deploy RabbitMQ with TLS certificates

​Step 1: Generate TLS certificates

​Step 2: Deploy RabbitMQ server

​Step 3: Test your RabbitMQ server

What this guide demonstrates

Components

Directory Structure

2 TLS listeners for 2 trust models

Deploy RabbitMQ with TLS certificates

Step 1: Generate TLS certificates

Step 2: Deploy RabbitMQ server

Step 3: Test your RabbitMQ server