LDAP
本页面不适用于 ClickHouse Cloud。此处介绍的功能在 ClickHouse Cloud 服务中不可用。 有关更多信息，请参阅 ClickHouse 的 Cloud Compatibility 指南。
LDAP 服务器可用于对 ClickHouse 用户进行身份验证。实现这一点有两种不同的方法：
- 将 LDAP 用作现有用户的外部认证器，这些用户定义在
users.xml或本地访问控制配置中。 - 将 LDAP 用作外部用户目录，允许那些本地未定义但在 LDAP 服务器上存在的用户通过身份验证。
对于这两种方法，必须在 ClickHouse 配置中定义一个具有内部名称的 LDAP 服务器，以便配置的其他部分可以引用它。
LDAP 服务器定义
要定义 LDAP 服务器，必须在 config.xml 中添加 ldap_servers 配置节。
示例
请注意，您可以在 ldap_servers 部分中定义多个 LDAP 服务器，只需使用不同的名称进行区分即可。
参数
host— LDAP 服务器的主机名或 IP，此参数为必需参数，且不能为空。port— LDAP 服务器端口，如果enable_tls设置为true，默认值为636，否则为389。bind_dn— 用于构造绑定 DN 的模板。- 最终的 DN 将在每次认证尝试期间，通过将模板中所有
{user_name}子串替换为实际用户名来构造。
- 最终的 DN 将在每次认证尝试期间，通过将模板中所有
user_dn_detection— 包含用于检测绑定用户实际用户 DN 的 LDAP 搜索参数的部分。- 这主要用于在服务器为 Active Directory 时，在搜索过滤器中进行后续角色映射。生成的用户 DN 将用于在允许的位置替换
{user_dn}子串。默认情况下，用户 DN 与 bind DN 相同，但一旦执行搜索，它将被更新为实际检测到的用户 DN 值。base_dn— 用于构造 LDAP 搜索基础 DN 的模板。- 最终的 DN 将在 LDAP 搜索期间，通过将模板中所有
{user_name}和{bind_dn}子串替换为实际用户名和 bind DN 来构造。
- 最终的 DN 将在 LDAP 搜索期间，通过将模板中所有
scope— LDAP 搜索的作用域。- 可接受的值为：
base、one_level、children、subtree（默认）。
- 可接受的值为：
search_filter— 用于构造 LDAP 搜索过滤器的模板。- 最终的过滤器将在 LDAP 搜索期间，通过将模板中所有
{user_name}、{bind_dn}和{base_dn}子串替换为实际用户名、bind DN 和 base DN 来构造。 - 注意，必须在 XML 中正确转义特殊字符。
- 最终的过滤器将在 LDAP 搜索期间，通过将模板中所有
- 这主要用于在服务器为 Active Directory 时，在搜索过滤器中进行后续角色映射。生成的用户 DN 将用于在允许的位置替换
verification_cooldown— 成功绑定尝试之后的一段时间（以秒为单位），在此期间内，所有连续请求在不联系 LDAP 服务器的情况下，都会被视为用户已成功认证。- 指定
0（默认）以禁用缓存，并强制对每个认证请求都联系 LDAP 服务器。
- 指定
enable_tls— 用于启用与 LDAP 服务器安全连接的标志。- 指定
no使用明文ldap://协议（不推荐）。 - 指定
yes使用基于 SSL/TLS 的 LDAPldaps://协议（推荐，默认）。 - 指定
starttls使用传统的 StartTLS 协议（明文ldap://协议，升级为 TLS）。
- 指定
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 执行“绑定”操作，如果成功，则认为该用户已通过认证。这通常被称为“简单绑定（simple bind）”方法。
示例
请注意，用户 my_user 关联到 my_ldap_server。必须在主配置文件 config.xml 中按前文所述配置此 LDAP 服务器。
当启用基于 SQL 的访问控制和账户管理时，通过 LDAP 服务器进行身份验证的用户也可以使用 CREATE USER 语句创建。
查询：
LDAP 外部用户目录
除了本地定义的用户之外，还可以使用远程 LDAP 服务器作为用户定义的来源。为此，需要在 config.xml 文件的 users_directories 部分中的 ldap 部分里，指定之前定义好的 LDAP 服务器名称（参见 LDAP Server Definition）。
在每次登录尝试时，ClickHouse 会首先尝试在本地查找用户定义并按常规方式进行身份验证。如果未找到该用户，ClickHouse 将假定该用户已在外部 LDAP 目录中定义，并尝试使用提供的凭证在 LDAP 服务器上对指定的 DN 执行 bind 操作。如果成功，该用户将被视为存在并通过认证。用户会被分配在 roles 部分中指定列表里的角色。此外，还可以执行 LDAP search 操作，并将结果转换后视为角色名称；如果同时配置了 role_mapping 部分，则这些角色将被分配给该用户。所有这些都意味着必须启用由 SQL 驱动的访问控制与账户管理，并且需要通过 CREATE ROLE 语句来创建角色。
示例
写入 config.xml。
请注意，user_directories 部分中 ldap 小节引用的 my_ldap_server，必须是在 config.xml 中事先定义并完成配置的 LDAP 服务器（参见 LDAP Server Definition）。
参数
server— 在上面ldap_servers配置部分中定义的 LDAP 服务器名称之一。此参数为必填项，且不能为空。roles— 包含本地定义角色列表的部分，这些角色将被分配给每个从 LDAP 服务器检索到的用户。- 如果此处未指定任何角色，或者在下面的角色映射过程中未分配角色，用户在完成认证后将无法执行任何操作。
role_mapping— 包含 LDAP 搜索参数和映射规则的部分。- 当用户进行认证时，在仍然绑定到 LDAP 的情况下，将使用
search_filter和已登录用户的名称执行 LDAP 搜索。对在该搜索中找到的每个条目，将提取指定属性的值。对于每个具有指定前缀的属性值，将移除该前缀，其余部分的值将作为在 ClickHouse 中本地定义的角色名称，且这些角色应事先通过 CREATE ROLE 语句创建。 - 在同一个
ldap部分中可以定义多个role_mapping小节，且会全部生效。base_dn— 用于构造 LDAP 搜索基础 DN 的模板。- 最终 DN 将通过在每次 LDAP 搜索期间，用实际用户名、绑定 DN 和用户 DN 分别替换模板中的
{user_name}、{bind_dn}和{user_dn}子串来构造。
- 最终 DN 将通过在每次 LDAP 搜索期间，用实际用户名、绑定 DN 和用户 DN 分别替换模板中的
scope— LDAP 搜索的范围。- 可接受的取值为：
base、one_level、children、subtree（默认）。
- 可接受的取值为：
search_filter— 用于构造 LDAP 搜索过滤器的模板。- 最终过滤器将通过在每次 LDAP 搜索期间，用实际用户名、绑定 DN、用户 DN 和基础 DN 分别替换模板中的
{user_name}、{bind_dn}、{user_dn}和{base_dn}子串来构造。 - 注意，必须在 XML 中对特殊字符进行正确转义。
- 最终过滤器将通过在每次 LDAP 搜索期间，用实际用户名、绑定 DN、用户 DN 和基础 DN 分别替换模板中的
attribute— 其值将由 LDAP 搜索返回的属性名。默认为cn。prefix— 预期出现在 LDAP 搜索返回的原始字符串列表中每个字符串前面的前缀。该前缀会从原始字符串中移除，得到的字符串将被视为本地角色名称。默认为空。
- 当用户进行认证时，在仍然绑定到 LDAP 的情况下，将使用
