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

> Secure RabbitMQ communication in Kourier using amqps or custom TLSConfig for advanced certificate management. Learn how to configure TLS SSL connections easily.

- Repository: [Guimauve Digital/kourier](https://github.com/guimauvedigital/kourier)
- Tags: how-to-guide
- Published: 2026-03-02

---

**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`](https://github.com/guimauvedigital/kourier/blob/main/DefaultAMQPConnection.kt), where the socket upgrade occurs:

```kotlin
// 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`](https://github.com/guimauvedigital/kourier/blob/main/UrlScheme.kt), the `AMQPS` scheme maps to port 5671 and triggers `AMQPConfig.Connection.Tls`:

```kotlin
// 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**

```kotlin
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`](https://github.com/guimauvedigital/kourier/blob/main/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`](https://github.com/guimauvedigital/kourier/blob/main/DefaultAMQPConnection.kt) during the socket upgrade.

**Example: Connecting with a self-signed certificate**

```kotlin
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.**

```kotlin
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`](https://github.com/guimauvedigital/kourier/blob/main/UrlScheme.kt) and [`Extensions.kt`](https://github.com/guimauvedigital/kourier/blob/main/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`](https://github.com/guimauvedigital/kourier/blob/main/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`](https://github.com/guimauvedigital/kourier/blob/main/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`](https://github.com/guimauvedigital/kourier/blob/main/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.