Skip to content

Commit 17f221d

Browse files
OreoxmtOreoxmt
authored
Add client authentication support for ticdc (#17227)
1 parent 4d68bac commit 17f221d

3 files changed

Lines changed: 129 additions & 0 deletions

File tree

‎TOC.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -564,6 +564,7 @@
564564
- [Replicate Data to Pulsar](/ticdc/ticdc-sink-to-pulsar.md)
565565
- [Replicate Data to Storage Services](/ticdc/ticdc-sink-to-cloud-storage.md)
566566
- [Manage Changefeeds](/ticdc/ticdc-manage-changefeed.md)
567+
- [TiCDC Client Authentication](/ticdc/ticdc-client-authentication.md)
567568
- [Log Filter](/ticdc/ticdc-filter.md)
568569
- [DDL Replication](/ticdc/ticdc-ddl.md)
569570
- [Bidirectional Replication](/ticdc/ticdc-bidirectional-replication.md)

‎ticdc/ticdc-client-authentication.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: TiCDC Client Authentication
3+
summary: Introduce how to perform TiCDC client authentication using the command-line tool or OpenAPI.
4+
---
5+
6+
# TiCDC Client Authentication
7+
8+
Starting from v8.1.0, TiCDC supports client authentication using Mutual Transport Layer Security (mTLS) or TiDB username and password.
9+
10+
- mTLS authentication provides security control at the transport layer, enabling TiCDC to verify the client identity.
11+
- TiDB username and password authentication provides security control at the application layer, ensuring that only authorized users can log in through the TiCDC node.
12+
13+
These two authentication methods can be used either independently or in combination to meet different scenarios and security requirements.
14+
15+
> **Note:**
16+
>
17+
> To ensure the security of network access, it is strongly recommended to use TiCDC client authentication only when [TLS is enabled](/enable-tls-between-clients-and-servers.md). If TLS is not enabled, the username and password are transmitted as plaintext over the network, which can lead to serious credential leaks.
18+
19+
## Use mTLS for client authentication
20+
21+
1. In the TiCDC server, configure the `security.mtls` parameter as `true` to enable mTLS authentication:
22+
23+
```toml
24+
[security]
25+
# This parameter controls whether to enable the TLS client authentication. The default value is false.
26+
mtls = true
27+
```
28+
29+
2. Configure the client certificate.
30+
31+
<SimpleTab groupId="cdc">
32+
<div label="TiCDC command-line tool" value="cdc-cli">
33+
34+
When using the [TiCDC command-line tool](/ticdc/ticdc-manage-changefeed.md), you can specify the client certificate using the following methods. TiCDC will attempt to read the client certificate in the following order:
35+
36+
1. Specify the certificate and private key using the command-line parameters `--cert` and `--key`. If the server uses a self-signed certificate, you also need to specify the trusted CA certificate using the `--ca` parameter.
37+
38+
```bash
39+
cdc cli changefeed list --cert client.crt --key client.key --ca ca.crt
40+
```
41+
42+
2. Specify the paths to the certificate, private key, and CA certificate using the environment variables `TICDC_CERT_PATH`, `TICDC_KEY_PATH`, and `TICDC_CA_PATH`.
43+
44+
```bash
45+
export TICDC_CERT_PATH=client.crt
46+
export TICDC_KEY_PATH=client.key
47+
export TICDC_CA_PATH=ca.crt
48+
```
49+
50+
3. Specify the certificate using the shared credential file `~/.ticdc/credentials`. You can modify the configuration using the `cdc cli configure-credentials` command.
51+
52+
</div>
53+
54+
<div label="TiCDC OpenAPI" value="cdc-api">
55+
56+
When using [TiCDC OpenAPI](/ticdc/ticdc-open-api-v2.md), you can specify the client certificate and private key using `--cert` and `--key`. If the server uses a self-signed certificate, you also need to specify the trusted CA certificate using the `--cacert` parameter. For example:
57+
58+
```bash
59+
curl -X GET http://127.0.0.1:8300/api/v2/status --cert client.crt --key client.key --cacert ca.crt
60+
```
61+
62+
</div>
63+
</SimpleTab>
64+
65+
## Use TiDB username and password for client authentication
66+
67+
1. [Create a user](/sql-statements/sql-statement-create-user.md) in TiDB and grant the user permission to log in from the TiCDC node.
68+
69+
```sql
70+
CREATE USER 'test'@'ticdc_ip_address' IDENTIFIED BY 'password';
71+
```
72+
73+
2. In the TiCDC server, configure `security.client-user-required` and `security.client-allowed-user` to enable username and password authentication:
74+
75+
```toml
76+
[security]
77+
# This parameter controls whether to use username and password for client authentication. The default value is false.
78+
client-user-required = true
79+
# This parameter lists the usernames that are allowed for client authentication. Authentication requests with usernames not in this list will be rejected. The default value is null.
80+
client-allowed-user = ["test"]
81+
```
82+
83+
3. Specify the username and password of the user created in step 1.
84+
85+
<SimpleTab groupId="cdc">
86+
<div label="TiCDC command-line tool" value="cdc-cli">
87+
88+
When using the [TiCDC command-line tool](/ticdc/ticdc-manage-changefeed.md), you can specify the username and password using the following methods. TiCDC will attempt to read the client certificate in the following order:
89+
90+
1. Specify the username and password using the command-line parameters `--user` and `--password`:
91+
92+
```bash
93+
cdc cli changefeed list --user test --password password
94+
```
95+
96+
2. Specify the username using the command-line parameter `--user`. Then, enter the password in the terminal:
97+
98+
```bash
99+
cdc cli changefeed list --user test
100+
```
101+
102+
3. Specify the username and password using the environment variables `TICDC_USER` and `TICDC_PASSWORD`:
103+
104+
```bash
105+
export TICDC_USER=test
106+
export TICDC_PASSWORD=password
107+
```
108+
109+
4. Specify the username and password using the shared credential file `~/.ticdc/credentials`. You can modify the configuration using the `cdc cli configure-credentials` command.
110+
111+
</div>
112+
113+
<div label="TiCDC OpenAPI" value="cdc-api">
114+
115+
When using [TiCDC OpenAPI](/ticdc/ticdc-open-api-v2.md), you can specify the username and password using `--user <user>:<password>`. For example:
116+
117+
```bash
118+
curl -X GET http://127.0.0.1:8300/api/v2/status --user test:password
119+
```
120+
121+
</div>
122+
</SimpleTab>

‎ticdc/ticdc-server-config.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,12 @@ gc-tuner-memory-threshold = 0
4747
ca-path = ""
4848
cert-path = ""
4949
key-path = ""
50+
# This parameter controls whether to enable the TLS client authentication. The default value is false.
51+
mtls = false
52+
# This parameter controls whether to use username and password for client authentication. The default value is false.
53+
client-user-required = false
54+
# This parameter lists the usernames that are allowed for client authentication. Authentication requests with usernames not in this list will be rejected. The default value is null.
55+
client-allowed-user = ["username_1", "username_2"]
5056

5157
# The session duration between TiCDC and etcd services, measured in seconds. This parameter is optional and its default value is 10.
5258
capture-session-ttl = 10 # 10s

0 commit comments

Comments
 (0)