How to Configure TLS/SSL Connections in Kourier for Secure RabbitMQ Communication

Enable secure RabbitMQ connections in Kourier by using the amqps:// URL scheme for automatic TLS or by passing a custom TLSConfig instance to the AMQP configuration DSL for advanced certificate management.

Kourier is a Kotlin-based AMQP client library built on Ktor's asynchronous networking stack. According to the guimauvedigital/kourier source code, TLS encryption is handled natively through Ktor's TLSConfig, allowing you to configure everything from system default trust stores to custom client certificates and SNI settings.

Understanding Kourier's TLS Architecture

Kourier delegates all transport-layer security to Ktor's io.ktor.network.tls module. When you configure TLS/SSL connections in Kourier, you are essentially supplying parameters that Ktor uses to wrap a plain TCP socket with TLS encryption.

The core logic resides in DefaultAMQPConnection.kt, where the socket upgrade occurs:

// From DefaultAMQPConnection.kt lines 94-98
val socket = tcpClient.connect(hostname, port)
    .apply {
        if (connectionConfig is AMQPConfig.Connection.Tls) {
            tls(coroutineContext, connectionConfig.tlsConfig)
        }
    }

This shows that Kourier first establishes a TCP connection, then conditionally upgrades it to TLS if the configuration specifies Connection.Tls.

Method 1: URL-Based TLS Configuration (Automatic)

The simplest way to configure TLS/SSL connections in Kourier is using the amqps:// URL scheme. When the broker URL starts with amqps://, Kourier automatically selects the TLS connection type and applies default system trust settings.

As defined in UrlScheme.kt, the AMQPS scheme maps to port 5671 and triggers AMQPConfig.Connection.Tls:

// Conceptual representation from UrlScheme.kt
enum class UrlScheme(val scheme: String, val defaultPort: Int) {
    AMQP("amqp", 5672),
    AMQPS("amqps", 5671)  // Automatically enables TLS
}

Example: Basic secure connection

import dev.kourier.amqp.connection.createAMQPConnection
import kotlinx.coroutines.runBlocking

runBlocking {
    // Kourier automatically uses system trust store
    val connection = createAMQPConnection(
        coroutineScope = this,
        url = "amqps://my-broker.example.com:5671"
    )
    
    // Open channels and begin publishing/consuming
    val channel = connection.createChannel()
}

This approach, found in Extensions.kt (lines 31-41), requires no explicit TLSConfig object—Ktor uses the platform's default TLS settings.

Method 2: Programmatic TLS Configuration (Custom Certificates)

For production environments requiring custom Certificate Authorities (CAs), client certificate authentication, or specific cipher suites, you must explicitly pass a TLSConfig instance to the AMQP configuration DSL.

The TLSConfig type comes from io.ktor.network.tls and is consumed in DefaultAMQPConnection.kt during the socket upgrade.

Example: Connecting with a self-signed certificate

import dev.kourier.amqp.connection.*
import io.ktor.network.tls.*
import kotlinx.coroutines.runBlocking
import java.io.File
import java.security.KeyStore
import java.security.cert.CertificateFactory
import java.security.cert.X509Certificate

runBlocking {
    // 1. Load your CA certificate into a KeyStore
    val trustStore = KeyStore.getInstance(KeyStore.getDefaultType()).apply {
        load(null, null) // Initialize empty
        
        val caCert = File("certs/ca.pem").inputStream().use { stream ->
            CertificateFactory.getInstance("X.509")
                .generateCertificate(stream) as X509Certificate
        }
        setCertificateEntry("myCa", caCert)
    }

    // 2. Build TLSConfig with custom trust store
    val customTls = TLSConfig(
        trustStore = trustStore,
        // Optional: enforce specific TLS version
        // protocols = listOf(TLSVersion.TLS12, TLSVersion.TLS13)
    )

    // 3. Create connection with explicit TLS config
    val connection = createAMQPConnection(
        coroutineScope = this,
        url = "amqps://my-broker.example.com",
        tls = customTls,
        sniServerName = "my-broker.example.com" // Optional SNI
    )
    
    // Use the connection...
}

Key configuration points:

• trustStore: Contains CA certificates used to verify the broker's identity.
• sniServerName: Specifies the Server Name Indication (SNI) hostname, critical when the broker hosts multiple virtual hosts behind a single IP.
• Client certificates: While the example shows trust store configuration, TLSConfig also accepts keyStore parameters for mutual TLS (mTLS) authentication.

Method 3: Disabling TLS Verification (Development Only)

In development or testing environments, you may need to bypass certificate validation. This is insecure and should never be used in production.

import dev.kourier.amqp.connection.*
import io.ktor.network.tls.*
import kotlinx.coroutines.runBlocking

runBlocking {
    val insecureTls = TLSConfig(
        trustManager = TrustManagerConfig(
            trustAll = true // Accepts any certificate
        )
    )

    val connection = createAMQPConnection(
        coroutineScope = this,
        url = "amqps://localhost:5671",
        tls = insecureTls
    )
}

This configuration uses Ktor's TrustManagerConfig to disable all certificate checks, allowing connections to brokers with self-signed or invalid certificates.

Summary

• Automatic TLS: Use amqps:// URLs to enable TLS with system default trust settings, as handled in UrlScheme.kt and Extensions.kt.
• Custom TLS: Pass a TLSConfig object to createAMQPConnection() or the amqpConfig DSL to specify custom trust stores, client certificates, or SNI settings, processed in DefaultAMQPConnection.kt lines 94-98.
• Ktor Integration: Kourier relies on io.ktor.network.tls.TLSConfig for all cryptographic parameters, ensuring compatibility with standard JVM TLS infrastructure.
• Security Warning: Never disable certificate verification (trustAll = true) in production environments.

Frequently Asked Questions

Does Kourier support client certificate authentication for mutual TLS?

Yes. When you configure TLS/SSL connections in Kourier programmatically, you can supply a KeyStore containing client certificates to the TLSConfig constructor. Ktor's TLS implementation handles the mutual authentication handshake during the socket upgrade in DefaultAMQPConnection.kt.

What TLS versions and cipher suites does Kourier use by default?

By default, Kourier uses Ktor's platform-specific TLSConfig defaults, which typically include TLS 1.2 and TLS 1.3 with standard cipher suites. You can override these by explicitly setting the protocols and cipherSuites parameters in your TLSConfig instance when calling createAMQPConnection().

How do I configure SNI for virtual hosts in Kourier?

Pass the sniServerName parameter to the createAMQPConnection() function or the amqpConfig DSL. This sets the Server Name Indication hostname during the TLS handshake, which is essential when connecting to RabbitMQ brokers hosting multiple virtual hosts behind a single IP address.

Can I use the robust client with TLS connections?

Yes. The robust client module (amqp-client-robust) extends the same connection DSL found in Extensions.kt. When you configure TLS/SSL connections using amqps:// URLs or explicit TLSConfig objects, the robust client wraps these connections with automatic reconnection and topology recovery logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}