Skip to content

Commit fe0f768

Browse files
vishwa-ubervishwa-uber
authored
docs: mTLS documentation with example sample (#299)
* docs: mTLS documentation with example sample Signed-off-by: [email protected] <[email protected]> * docs: mTLS documentation with example sample Signed-off-by: [email protected] <[email protected]> * docs: Wiki for mTLS Signed-off-by: [email protected] <[email protected]> * docs: Wiki for mTLS Signed-off-by: [email protected] <[email protected]> * docs: Wiki for mTLS Signed-off-by: [email protected] <[email protected]> * docs: Wiki for mTLS Signed-off-by: [email protected] <[email protected]> * docs: Wiki for mTLS Signed-off-by: [email protected] <[email protected]> * docs: Wiki for mTLS Signed-off-by: [email protected] <[email protected]> --------- Signed-off-by: [email protected] <[email protected]>
1 parent 9af3053 commit fe0f768

File tree

1 file changed

+126
-0
lines changed

1 file changed

+126
-0
lines changed

‎docs/03-concepts/14-mutual-tls.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
layout: default
3+
title: Mutual TLS (mTLS) Authentication
4+
permalink: /docs/concepts/mutual-tls
5+
6+
---
7+
# Mutual TLS (mTLS) Authentication
8+
9+
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.
10+
11+
---
12+
13+
## Overview
14+
15+
### What is Mutual TLS?
16+
17+
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.
18+
19+
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:
20+
21+
- Clients can verify they're connecting to the legitimate server
22+
- Servers can verify the identity of connecting clients
23+
- All communication is encrypted end-to-end
24+
25+
---
26+
27+
## How mTLS Works
28+
29+
The mTLS handshake process involves the following steps:
30+
31+
```
32+
┌─────────────────────────────────────────────────────────────────────────┐
33+
│ mTLS Handshake Flow │
34+
└─────────────────────────────────────────────────────────────────────────┘
35+
36+
37+
CLIENT SERVER
38+
│ │
39+
│ (1) Client initiates connection │
40+
├─────────────────────────────────────────────────────--─> │
41+
│ │
42+
│ (2) Server sends its certificate │
43+
│ <────────────────────────────────────────────────────── ┤
44+
│ │
45+
│ (3) Client verifies server certificate │
46+
│ ✓ Check signature │
47+
│ ✓ Validate certificate chain │
48+
│ ✓ Check expiration │
49+
│ │
50+
│ (4) Client sends its certificate │
51+
├───────────────────────────────────────────────────--───> │
52+
│ │
53+
│ (5) Server verifies client certificate │
54+
│ ✓ Check signature │
55+
│ ✓ Validate certificate chain │
56+
│ ✓ Check expiration │
57+
│ │
58+
│ (6) Server grants access │
59+
│ <────────────────────────────────────────────────────── ┤
60+
│ │
61+
│ (7) Encrypted TLS connection established │
62+
│ <═══════════════════════════════════════════════════> │
63+
│ All subsequent data is encrypted │
64+
│ │
65+
```
66+
67+
### Step-by-Step Process
68+
69+
1. **Client connects to server**: The client initiates a connection to the server
70+
2. **Server presents its TLS certificate**: The server sends its certificate to prove its identity
71+
3. **Client verifies the server's certificate**: The client validates the server's certificate against trusted Certificate Authorities (CAs)
72+
4. **Client presents its TLS certificate**: The client sends its own certificate to prove its identity
73+
5. **Server verifies the client's certificate**: The server validates the client's certificate
74+
6. **Server grants access**: Once both certificates are verified, the server allows the connection
75+
7. **Client and server exchange information over encrypted TLS connection**: All data is now transmitted securely
76+
77+
---
78+
79+
## Implementing mTLS in Cadence
80+
81+
### Server Configuration
82+
83+
To enable mTLS in Cadence server, you need to configure TLS settings and start the server with the appropriate environment configuration.
84+
85+
#### Starting the Server with TLS
86+
87+
Use the `--zone` flag to specify the TLS configuration when starting the Cadence server:
88+
89+
```bash
90+
./cadence-server --env development --zone tls start
91+
```
92+
93+
This will load [config/development.yaml](https://github.com/cadence-workflow/cadence/blob/master/config/development.yaml) \+ [config/development\_tls.yaml](https://github.com/cadence-workflow/cadence/blob/master/config/development_tls.yaml). See [CONTRIBUTING.md](https://github.com/cadence-workflow/cadence/blob/master/CONTRIBUTING.md#4-run) for more details.
94+
95+
---
96+
97+
### Client Implementation
98+
99+
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.
100+
101+
---
102+
103+
## Complete Working Example
104+
105+
The [helloworld_tls sample](https://github.com/cadence-workflow/cadence-samples/tree/master/new_samples/client_samples/helloworld_tls) provides a complete, tested implementation of mTLS with Cadence, including:
106+
107+
- Certificate generation scripts
108+
- Complete client implementation with mTLS
109+
- Instructions for running with a TLS-enabled server
110+
- Step-by-step setup guide
111+
112+
For additional server configuration examples, refer to the [Cadence server repository](https://github.com/cadence-workflow/cadence)
113+
114+
---
115+
116+
## Testing Scenarios
117+
118+
The following table outlines various testing scenarios for mTLS configuration:
119+
120+
| Server | Client | Expected | Steps |
121+
| :---- | :---- | :---- | :---- |
122+
| Unsecured | Unsecured | Success | Server without TLS enabled; Client without TLS certs |
123+
| Secured | Unsecured | Fail | Server with TLS enabled; Client without TLS certs |
124+
| Unsecured | Secured | Fail | Server without TLS enabled; Client **with** TLS certs |
125+
| Secured | Secured | Success | Mutual TLS: Server with TLS enabled; Client with TLS enabled |
126+

0 commit comments

Comments
 (0)