LDAP

注意

此页面不适用于 ClickHouse Cloud。此处记录的功能在 ClickHouse Cloud 服务中不可用。有关更多信息，请参阅 ClickHouse 云兼容性指南。

LDAP 服务器可用于对 ClickHouse 用户进行身份验证。有两种不同的方法可以执行此操作

将 LDAP 用作现有用户的外部身份验证器，这些用户在 users.xml 或本地访问控制路径中定义。
将 LDAP 用作外部用户目录，并允许在 LDAP 服务器上存在的情况下对本地未定义的用户进行身份验证。

对于这两种方法，都必须在 ClickHouse 配置中定义一个内部命名的 LDAP 服务器，以便配置的其他部分可以引用它。

LDAP 服务器定义

要定义 LDAP 服务器，必须将 ldap_servers 部分添加到 config.xml 中。

示例

<clickhouse>
    <!- ... -->
    <ldap_servers>
        <!- Typical LDAP server. -->
        <my_ldap_server>
            <host>localhost</host>
            <port>636</port>
            <bind_dn>uid={user_name},ou=users,dc=example,dc=com</bind_dn>
            <verification_cooldown>300</verification_cooldown>
            <enable_tls>yes</enable_tls>
            <tls_minimum_protocol_version>tls1.2</tls_minimum_protocol_version>
            <tls_require_cert>demand</tls_require_cert>
            <tls_cert_file>/path/to/tls_cert_file</tls_cert_file>
            <tls_key_file>/path/to/tls_key_file</tls_key_file>
            <tls_ca_cert_file>/path/to/tls_ca_cert_file</tls_ca_cert_file>
            <tls_ca_cert_dir>/path/to/tls_ca_cert_dir</tls_ca_cert_dir>
            <tls_cipher_suite>ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384</tls_cipher_suite>
        </my_ldap_server>

        <!- Typical Active Directory with configured user DN detection for further role mapping. -->
        <my_ad_server>
            <host>localhost</host>
            <port>389</port>
            <bind_dn>EXAMPLE\{user_name}</bind_dn>
            <user_dn_detection>
                <base_dn>CN=Users,DC=example,DC=com</base_dn>
                <search_filter>(&amp;(objectClass=user)(sAMAccountName={user_name}))</search_filter>
            </user_dn_detection>
            <enable_tls>no</enable_tls>
        </my_ad_server>
    </ldap_servers>
</clickhouse>

请注意，您可以使用不同的名称在 ldap_servers 部分中定义多个 LDAP 服务器。

参数

host — LDAP 服务器主机名或 IP，此参数是必需的，不能为空。
port — LDAP 服务器端口，如果 enable_tls 设置为 true，则默认为 636，否则为 389。
bind_dn — 用于构建要绑定到的 DN 的模板。
- 在每次身份验证尝试期间，通过将模板的所有 {user_name} 子字符串替换为实际用户名来构建生成的 DN。
user_dn_detection — 包含用于检测绑定用户的实际用户 DN 的 LDAP 搜索参数的部分。
- 这主要用于服务器为 Active Directory 时的进一步角色映射的搜索过滤器。当替换允许的 {user_dn} 子字符串时，将使用生成的 DN。默认情况下，用户 DN 设置为等于绑定 DN，但一旦执行搜索，它将使用检测到的实际用户 DN 值进行更新。
  - base_dn — 用于构建 LDAP 搜索的基本 DN 的模板。
    - 在 LDAP 搜索期间，通过将模板的所有 {user_name} 和 {bind_dn} 子字符串替换为实际用户名和绑定 DN 来构建生成的 DN。
  - scope — LDAP 搜索的范围。
    - 可接受的值为：base、one_level、children、subtree（默认值）。
  - search_filter — 用于构建 LDAP 搜索的搜索过滤器的模板。
    - 在 LDAP 搜索期间，通过将模板的所有 {user_name}、{bind_dn} 和 {base_dn} 子字符串替换为实际用户名、绑定 DN 和基本 DN 来构建生成的过滤器。
    - 请注意，必须在 XML 中正确转义特殊字符。
verification_cooldown — 在成功绑定尝试后的一段时间（以秒为单位），在此期间，将假定用户已成功通过身份验证，所有连续请求都无需联系 LDAP 服务器。
- 指定 0（默认值）以禁用缓存并强制每次身份验证请求都联系 LDAP 服务器。
enable_tls — 用于触发对 LDAP 服务器使用安全连接的标志。
- 对于纯文本 ldap:// 协议（不推荐）指定 no。
- 对于 SSL/TLS 上的 LDAP ldaps:// 协议（推荐，默认值）指定 yes。
- 对于旧版 StartTLS 协议（纯文本 ldap:// 协议，升级到 TLS）指定 starttls。
tls_minimum_protocol_version — SSL/TLS 的最低协议版本。
- 可接受的值为：ssl2、ssl3、tls1.0、tls1.1、tls1.2（默认值）。
tls_require_cert — SSL/TLS 对等证书验证行为。
- 可接受的值为：never、allow、try、demand（默认值）。
tls_cert_file — 证书文件的路径。
tls_key_file — 证书密钥文件的路径。
tls_ca_cert_file — CA 证书文件的路径。
tls_ca_cert_dir — 包含 CA 证书的目录的路径。
tls_cipher_suite — 允许的密码套件（使用 OpenSSL 表示法）。

LDAP 外部身份验证器

远程 LDAP 服务器可以用作验证本地定义的用户（在 users.xml 或本地访问控制路径中定义的用户）密码的方法。为此，请在用户定义中的 password 或类似部分中指定先前定义的 LDAP 服务器名称。

在每次登录尝试时，ClickHouse 都会尝试使用提供的凭据“绑定”到 LDAP 服务器定义中 bind_dn 参数定义的指定 DN，如果成功，则认为用户已通过身份验证。这通常称为“简单绑定”方法。

示例

<clickhouse>
    <!- ... -->
    <users>
        <!- ... -->
        <my_user>
            <!- ... -->
            <ldap>
                <server>my_ldap_server</server>
            </ldap>
        </my_user>
    </users>
</clickhouse>

请注意，用户 my_user 引用 my_ldap_server。此 LDAP 服务器必须如前所述在主 config.xml 文件中进行配置。

启用 SQL 驱动的访问控制和帐户管理后，也可以使用 CREATE USER 语句创建通过 LDAP 服务器进行身份验证的用户。

查询

CREATE USER my_user IDENTIFIED WITH ldap SERVER 'my_ldap_server';

LDAP 外部用户目录

除了本地定义的用户之外，远程 LDAP 服务器还可以用作用户定义的来源。为此，请在 config.xml 文件的 users_directories 部分内的 ldap 部分中指定先前定义的 LDAP 服务器名称（请参阅 LDAP 服务器定义）。

在每次登录尝试时，ClickHouse 都会尝试在本地查找用户定义并照常对其进行身份验证。如果未定义用户，ClickHouse 将假定该定义存在于外部 LDAP 目录中，并将尝试使用提供的凭据“绑定”到 LDAP 服务器上的指定 DN。如果成功，则认为用户存在并已通过身份验证。用户将被分配到 roles 部分中指定的列表中的角色。此外，可以执行 LDAP“搜索”，并将结果转换为角色名称，然后如果也配置了 role_mapping 部分，则将其分配给用户。所有这些都意味着启用了 SQL 驱动的访问控制和帐户管理，并且角色是使用 CREATE ROLE 语句创建的。

示例

进入 config.xml。

<clickhouse>
    <!- ... -->
    <user_directories>
        <!- Typical LDAP server. -->
        <ldap>
            <server>my_ldap_server</server>
            <roles>
                <my_local_role1 />
                <my_local_role2 />
            </roles>
            <role_mapping>
                <base_dn>ou=groups,dc=example,dc=com</base_dn>
                <scope>subtree</scope>
                <search_filter>(&amp;(objectClass=groupOfNames)(member={bind_dn}))</search_filter>
                <attribute>cn</attribute>
                <prefix>clickhouse_</prefix>
            </role_mapping>
        </ldap>

        <!- Typical Active Directory with role mapping that relies on the detected user DN. -->
        <ldap>
            <server>my_ad_server</server>
            <role_mapping>
                <base_dn>CN=Users,DC=example,DC=com</base_dn>
                <attribute>CN</attribute>
                <scope>subtree</scope>
                <search_filter>(&amp;(objectClass=group)(member={user_dn}))</search_filter>
                <prefix>clickhouse_</prefix>
            </role_mapping>
        </ldap>
    </user_directories>
</clickhouse>

请注意，user_directories 部分内的 ldap 部分中引用的 my_ldap_server 必须是先前定义并在 config.xml 中配置的 LDAP 服务器（请参阅 LDAP 服务器定义）。

参数

server — 上述 ldap_servers 配置部分中定义的 LDAP 服务器名称之一。此参数是必需的，不能为空。
roles — 包含将分配给从 LDAP 服务器检索到的每个用户的本地定义角色列表的部分。
- 如果此处未指定角色或在角色映射（下面）期间分配，则用户在身份验证后将无法执行任何操作。
role_mapping — 包含 LDAP 搜索参数和映射规则的部分。
- 当用户进行身份验证时，在仍绑定到 LDAP 的同时，将使用 search_filter 和登录用户的名称执行 LDAP 搜索。对于在该搜索期间找到的每个条目，都会提取指定属性的值。对于具有指定前缀的每个属性值，都会删除前缀，其余值将成为 ClickHouse 中定义的本地角色的名称，预计该角色之前已通过 CREATE ROLE 语句创建。
- 可以在同一 ldap 部分内定义多个 role_mapping 部分。所有这些都将被应用。
  - base_dn — 用于构建 LDAP 搜索的基本 DN 的模板。
    - 在每次 LDAP 搜索期间，生成的 DN 将通过用实际的用户名称、绑定 DN 和用户 DN 替换模板中的所有{user_name}、{bind_dn} 和 {user_dn} 子字符串来构建。
  - scope — LDAP 搜索的范围。
    - 可接受的值为：base、one_level、children、subtree（默认值）。
  - search_filter — 用于构建 LDAP 搜索的搜索过滤器的模板。
    - 在每次 LDAP 搜索期间，生成的过滤器将通过用实际的用户名称、绑定 DN、用户 DN 和基础 DN 替换模板中的所有{user_name}、{bind_dn}、{user_dn} 和 {base_dn} 子字符串来构建。
    - 请注意，必须在 XML 中正确转义特殊字符。
  - attribute — LDAP 搜索将返回其值的属性名称。默认情况下为 cn。
  - prefix — 前缀，预期存在于 LDAP 搜索返回的原始字符串列表中每个字符串的前面。该前缀将从原始字符串中删除，生成的字符串将被视为本地角色名称。默认为空。

LDAP 服务器定义​

LDAP 外部身份验证器​

LDAP 外部用户目录​

LDAP 服务器定义

LDAP 外部身份验证器

LDAP 外部用户目录