> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置用于身份验证的 SSL 用户证书

> 本指南提供最简配置，说明如何使用 SSL 用户证书进行身份验证。

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            ClickHouse Cloud 不支持此功能
        </div>;
};

<CloudNotSupportedBadge />

<Note>
  本页不适用于 [ClickHouse Cloud](https://clickhouse.com/cloud)。本文档介绍的功能不适用于 ClickHouse Cloud 服务。
  更多信息，请参阅 ClickHouse 的 [Cloud Compatibility](/docs/zh/products/cloud/guides/cloud-compatibility) 指南。
</Note>

本指南介绍如何以最少的配置，使用 SSL 用户证书来设置身份验证。本教程基于 [配置 TLS 指南](/docs/zh/concepts/features/security/tls/configuring-tls)。

<Note>
  使用 `https`、`native`、`mysql` 和 `postgresql` 接口时，支持 SSL 用户身份验证。

  为实现安全身份验证，ClickHouse 节点需要设置 `<verificationMode>strict</verificationMode>` (不过在测试场景下，`relaxed` 也可用) 。

  如果你将 AWS NLB 与 MySQL 接口一起使用，则需要联系 AWS 支持以启用以下未公开的选项：

  > 我希望能够按如下方式配置我们的 NLB proxy protocol v2：`proxy_protocol_v2.client_to_server.header_placement,Value=on_first_ack`。
</Note>

<Steps>
  <Step title="创建 SSL 用户证书" id="1-create-ssl-user-certificates">
    <Note>
      此示例使用由自签名 CA 签发的自签名证书。对于生产环境，请创建 CSR 并提交给你的 PKI 团队或证书提供商，以获取正式证书。
    </Note>

    1. 生成证书签名请求 (CSR) 和密钥。基本格式如下：
       ```bash theme={null}
       openssl req -newkey rsa:2048 -nodes -subj "/CN=<my_host>:<my_user>"  -keyout <my_cert_name>.key -out <my_cert_name>.csr
       ```
       在此示例中，对于此示例环境中使用的域名和用户，可使用以下命令：
       ```bash theme={null}
       openssl req -newkey rsa:2048 -nodes -subj "/CN=chnode1.marsnet.local:cert_user"  -keyout chnode1_cert_user.key -out chnode1_cert_user.csr
       ```

    <Note>
      CN 是任意的，可以使用任何字符串作为证书的标识符。在后续步骤中创建用户时会用到它。
    </Note>

    2. 生成并签署将用于身份验证的新用户证书。基本格式如下：
       ```bash theme={null}
       openssl x509 -req -in <my_cert_name>.csr -out <my_cert_name>.crt -CA <my_ca_cert>.crt -CAkey <my_ca_cert>.key -days 365
       ```
       在此示例中，对于此示例环境中使用的域名和用户，可使用以下命令：
       ```bash theme={null}
       openssl x509 -req -in chnode1_cert_user.csr -out chnode1_cert_user.crt -CA marsnet_ca.crt -CAkey marsnet_ca.key -days 365
       ```
  </Step>

  <Step title="创建 SQL 用户并授予权限" id="2-create-a-sql-user-and-grant-permissions">
    <Note>
      有关如何启用 SQL 用户并设置角色的详细信息，请参阅 [定义 SQL 用户和角色](/docs/zh/concepts/features/security/access-rights) 用户指南。
    </Note>

    1. 创建一个使用证书身份验证的 SQL 用户：
       ```sql theme={null}
       CREATE USER cert_user IDENTIFIED WITH ssl_certificate CN 'chnode1.marsnet.local:cert_user';
       ```

    2. 向新的证书用户授予特权：
       ```sql theme={null}
       GRANT ALL ON *.* TO cert_user WITH GRANT OPTION;
       ```

    <Note>
      出于演示目的，本练习中为该用户授予了完整的管理员特权。有关 permissions 设置，请参阅 ClickHouse 的 [RBAC 文档](/docs/zh/concepts/features/security/access-rights)。
    </Note>

    <Note>
      我们建议使用 SQL 来定义用户和角色。不过，如果你当前是在 configuration files 中定义用户和角色，则该用户将如下所示：

      ```xml theme={null}
      <users>
          <cert_user>
              <ssl_certificates>
                  <common_name>chnode1.marsnet.local:cert_user</common_name>
              </ssl_certificates>
              <networks>
                  <ip>::/0</ip>
              </networks>
              <profile>default</profile>
              <access_management>1</access_management>
              {/* 其他选项*/}
          </cert_user>
      </users>
      ```
    </Note>
  </Step>

  <Step title="测试" id="3-testing">
    1. 将用户证书、用户密钥和 CA 证书复制到远程节点。

    2. 在 ClickHouse [客户端配置](/docs/zh/concepts/features/interfaces/client#configuration_files)中配置 OpenSSL，并指定证书和路径。

       ```xml theme={null}
       <openSSL>
           <client>
               <certificateFile>my_cert_name.crt</certificateFile>
               <privateKeyFile>my_cert_name.key</privateKeyFile>
               <caConfig>my_ca_cert.crt</caConfig>
           </client>
       </openSSL>
       ```

    3. 运行 `clickhouse-client`。
       ```bash theme={null}
       clickhouse-client --user <my_user> --query 'SHOW TABLES'
       ```

    <Note>
      请注意，如果在配置中指定了证书，传递给 clickhouse-client 的密码将被忽略。
    </Note>
  </Step>

  <Step title="HTTP 测试" id="4-testing-http">
    1. 将用户证书、用户密钥和 CA 证书复制到远程节点。

    2. 使用 `curl` 测试一条示例 SQL 命令。基本格式如下：
       ```bash theme={null}
       echo 'SHOW TABLES' | curl 'https://<clickhouse_node>:8443' --cert <my_cert_name>.crt --key <my_cert_name>.key --cacert <my_ca_cert>.crt -H "X-ClickHouse-SSL-Certificate-Auth: on" -H "X-ClickHouse-User: <my_user>" --data-binary @-
       ```
       例如：
       ```bash theme={null}
       echo 'SHOW TABLES' | curl 'https://chnode1:8443' --cert chnode1_cert_user.crt --key chnode1_cert_user.key --cacert marsnet_ca.crt -H "X-ClickHouse-SSL-Certificate-Auth: on" -H "X-ClickHouse-User: cert_user" --data-binary @-
       ```
       输出将类似于以下内容：
       ```response theme={null}
       INFORMATION_SCHEMA
       default
       information_schema
       system
       ```

    <Note>
      请注意，这里未指定密码；证书将代替密码使用，ClickHouse 会通过这种方式对用户进行身份验证。
    </Note>
  </Step>
</Steps>

<div id="summary">
  ## 摘要
</div>

本文介绍了为 SSL 证书身份验证创建和配置用户的基本方法。此方法可用于 `clickhouse-client`，也适用于任何支持 `https` 接口且可设置 HTTP 请求头的客户端。生成的证书和私钥应妥善保管并严格限制访问，因为证书用于对用户进行身份验证和授权，以执行 ClickHouse 数据库上的操作。请像保护密码一样保护证书和私钥。