Mutual TLS (mTLS) Authentication

This guide explains how to implement Mutual TLS (mTLS) authentication in Cadence to secure communication between clients and servers. mTLS provides bidirectional authentication, ensuring that both the client and server verify each other's identities before exchanging data.

Samples

Runnable mTLS sample:

Sample	Description	Code
mTLS client	Complete client setup with certificate generation scripts and a step-by-step guide	Go

Overview

What is Mutual TLS?

Mutual TLS (mTLS) is an enhanced version of the standard TLS protocol where both parties in a communication authenticate each other. Unlike standard TLS where only the server is authenticated, mTLS requires both the client and server to present and verify certificates.

In mTLS, both the client and server have a certificate, and both sides authenticate using their public/private key pair. This bidirectional authentication provides an additional layer of security, ensuring that:

Clients can verify they're connecting to the legitimate server
Servers can verify the identity of connecting clients
All communication is encrypted end-to-end

How mTLS Works

The mTLS handshake process involves the following steps:

┌─────────────────────────────────────────────────────────────────────────┐
│                            mTLS Handshake Flow                          │
└─────────────────────────────────────────────────────────────────────────┘


  CLIENT                                                    SERVER
    │                                                          │
    │  (1) Client initiates connection                         │
    ├─────────────────────────────────────────────────────--─> │
    │                                                          │
    │  (2) Server sends its certificate                        │
    │  <────────────────────────────────────────────────────── ┤
    │                                                          │
    │  (3) Client verifies server certificate                  │
    │       ✓ Check signature                                  │
    │       ✓ Validate certificate chain                       │
    │       ✓ Check expiration                                 │
    │                                                          │
    │  (4) Client sends its certificate                        │
    ├───────────────────────────────────────────────────--───> │
    │                                                          │
    │  (5) Server verifies client certificate                  │
    │                            ✓ Check signature             │
    │                            ✓ Validate certificate chain  │
    │                            ✓ Check expiration            │
    │                                                          │
    │  (6) Server grants access                                │
    │  <────────────────────────────────────────────────────── ┤
    │                                                          │
    │  (7) Encrypted TLS connection established                │
    │  <═══════════════════════════════════════════════════>   │
    │      All subsequent data is encrypted                    │
    │                                                          │

Step-by-Step Process

Client connects to server: The client initiates a connection to the server
Server presents its TLS certificate: The server sends its certificate to prove its identity
Client verifies the server's certificate: The client validates the server's certificate against trusted Certificate Authorities (CAs)
Client presents its TLS certificate: The client sends its own certificate to prove its identity
Server verifies the client's certificate: The server validates the client's certificate
Server grants access: Once both certificates are verified, the server allows the connection
Client and server exchange information over encrypted TLS connection: All data is now transmitted securely

Implementing mTLS in Cadence

Server Configuration

To enable mTLS in Cadence server, you need to configure TLS settings and start the server with the appropriate environment configuration.

Starting the Server with TLS

Use the --zone flag to specify the TLS configuration when starting the Cadence server:

./cadence-server --env development --zone tls start

This will load config/development.yaml + config/development_tls.yaml. See CONTRIBUTING.md for more details.

Client Implementation

To connect a Cadence client with mTLS, you need to configure TLS credentials and pass them to the Cadence client. Cadence client will use a gRPC transport object using your TLS settings to communicate with the server.

Complete Working Example

The client_tls sample provides a complete, tested implementation of mTLS with Cadence, including:

Certificate generation scripts
Complete client implementation with mTLS
Instructions for running with a TLS-enabled server
Step-by-step setup guide

For additional server configuration examples, refer to the Cadence server repository

Testing Scenarios

The following table outlines various testing scenarios for mTLS configuration:

Server	Client	Expected	Steps
Unsecured	Unsecured	Success	Server without TLS enabled; Client without TLS certs
Secured	Unsecured	Fail	Server with TLS enabled; Client without TLS certs
Unsecured	Secured	Fail	Server without TLS enabled; Client with TLS certs
Secured	Secured	Success	Mutual TLS: Server with TLS enabled; Client with TLS enabled

Samples​

Overview​

What is Mutual TLS?​

How mTLS Works​

Step-by-Step Process​

Implementing mTLS in Cadence​

Server Configuration​

Starting the Server with TLS​

Client Implementation​

Complete Working Example​

Testing Scenarios​