跳到主要内容
版本：Latest-4.1

LDAP 认证

除了原生的基于密码的认证，StarRocks 还支持 LDAP 认证。

本主题描述了如何在 StarRocks 中使用 LDAP 手动创建和认证用户。有关如何使用安全集成将 StarRocks 与您的 LDAP 服务集成的说明，请参见Authenticate with Security Integration。有关如何在 LDAP 服务中认证用户组的更多信息，请参见Authenticate User Groups。

启用 LDAP 认证​

要使用 LDAP 认证，您需要首先将 LDAP 服务添加到 FE 节点配置中。

# 添加 LDAP 服务的 IP 地址。
authentication_ldap_simple_server_host =
# 添加 LDAP 服务的端口，默认值为 389。
authentication_ldap_simple_server_port =
# 是否允许使用非加密方式连接到 LDAP 服务器。默认值：`true`。将此值设置为 `false` 表示访问 LDAP 需要使用 SSL 加密。
authentication_ldap_simple_ssl_conn_allow_insecure = 
# 存储 LDAP 服务器的 SSL CA 证书的本地路径。支持 pem 和 jks 格式。如果证书是由受信机构颁发的，则无需配置。
authentication_ldap_simple_ssl_conn_trust_store_path = 
# 访问本地存储的 LDAP 服务器的 SSL CA 证书所用的密码。pem 格式证书不需要密码，只有 jsk 格式证书需要。
authentication_ldap_simple_ssl_conn_trust_store_pwd =

如果希望通过 StarRocks 直接在 LDAP 系统中检索用户进行认证（搜索绑定模式），您需要添加以下额外的配置项。

# 添加用户的 Base DN，指定用户的检索范围。
authentication_ldap_simple_bind_base_dn =
# 添加承载登录名的属性名。默认：uid（OpenLDAP 的惯例）。
# Active Directory 上请用 sAMAccountName。
authentication_ldap_simple_user_search_attr =
# 添加用于检索用户的 Admin DN。
authentication_ldap_simple_bind_root_dn =
# 添加用于检索用户的 Admin 密码。
authentication_ldap_simple_bind_root_pwd =

如果希望使用直接绑定模式（跳过搜索步骤，直接使用构造的 DN 进行绑定），可以配置 DN 模式（pattern）。当用户 DN 结构可预测时，此模式非常有用。

# 直接绑定认证的 DN 模式。
# 使用 ${USER} 作为用户名的占位符。
# 多个模式之间用分号 ';' 分隔。
authentication_ldap_simple_bind_dn_pattern =

例如：uid=${USER},ou=People,dc=example,dc=com

如果用户分布在多个 OU 中，可以指定多个模式，用分号分隔：

uid=${USER},ou=Engineering,dc=example,dc=com;uid=${USER},ou=Marketing,dc=example,dc=com

系统将按顺序尝试每个模式，并返回第一个成功绑定的结果。

备注

模式必须生成合法的 LDAP Distinguished Name（DN），不支持 UPN 格式的模式（如 ${USER}@corp.example.com），因为其结果不是 DN，会导致下游组查找失败。如果 DN 中的属性值包含 @（如 uid=${USER}@corp.example.com,ou=People,dc=example,dc=com），这是合法的。

DN 匹配机制​

自 v3.5.0 起，StarRocks 支持在 LDAP 认证过程中记录和传递用户的 Distinguished Name (DN) 信息，以提供更准确的组解析功能。

工作原理​

  1. 认证阶段：LDAPAuthProvider 在用户认证成功后会同时记录：

    • 登录用户名（用于传统组匹配）
    • 用户的完整 DN（用于基于 DN 的组匹配）

  2. 组解析阶段：LDAPGroupProvider 根据 ldap_user_search_attr 参数的配置决定匹配策略：

    • 如配置了 ldap_user_search_attr，则使用用户名作为组匹配的 Key。
    • 如未配置 ldap_user_search_attr，则使用 DN 作为组匹配的 Key。

适用场景​

  • 传统 LDAP 环境：组成员使用简单用户名（如 cn 属性）。管理员需配置 ldap_user_search_attr 参数。
  • Microsoft AD 环境：组成员可能缺少用户名属性，无法配置 ldap_user_search_attr 参数，则直接使用 DN 匹配。
  • 混合环境：支持两种匹配方式的灵活切换。

认证优先级​

当用户使用 LDAP 认证登录时，StarRocks 按以下优先级确定用户的 DN：

  1. 用户指定 DN：如果创建用户时指定了明确的 DN（CREATE USER ... AS 'dn'），则直接使用该 DN。
  2. 通过 DN 模式直接绑定：如果配置了 authentication_ldap_simple_bind_dn_pattern，系统将根据模式构造 DN 并尝试直接绑定。多个模式按顺序尝试。
  3. 搜索绑定：如果以上两种均不适用，系统将使用管理员账户在 LDAP 中搜索用户，然后使用找到的 DN 进行绑定。

从用户条目解析用户组（memberOf）​

自 v4.2 起，LDAP 用户的用户组可以从用户自身条目上的组成员属性读取，不再需要在配置里声明要看哪些用户组。此时目录中新建的用户组会在用户下次登录时生效，无需改动任何配置。

由两个 FE 配置项控制，均可动态修改：

# 用户组从哪里来：group_provider（默认）| memberof | both
authentication_ldap_simple_group_source = group_provider
# 用户条目上承载组成员关系的属性名
authentication_ldap_simple_memberof_attr = memberOf
  • group_provider（默认）与低版本行为一致：只使用 Group Provider。
  • memberof 只使用用户自身条目上的该属性。已配置的 Group Provider 被忽略，但配置保留。
  • both 返回两者的并集。

memberOf 适用于 Active Directory 以及安装了 memberof overlay 的 OpenLDAP。Oracle Directory Server 与 389 Directory Server 使用 isMemberOf。

以上是集群级默认值。Security Integration 可以用同名属性覆盖这两项，也是按 LDAP 服务分别配置的推荐方式——完整行为（包括两种认证模式各自如何读取该属性，以及哪些情况不覆盖：嵌套组、Active Directory 的 primary group、跨域用户组）见 Security Integration。

备注

使用显式 DN 创建的用户（CREATE USER ... IDENTIFIED WITH authentication_ldap_simple AS '<dn>'）不支持该功能：那种写法是待废弃的单用户老机制，其组解析行为保持不变。请在创建用户时省略 AS '<dn>'，或改用 Security Integration。

大小写敏感性​

LDAP 这一族配置没有统一答案——有的值由 FE 比较，有的由目录比较，所以下表逐项说明。

项在哪里比较是否区分大小写
属性名：authentication_ldap_simple_user_search_attr、authentication_ldap_simple_memberof_attr目录，以及 FE 读回结果时不区分。 LDAP 属性名（attribute description）本身就是不区分大小写的，memberof 和 memberOf 是同一个属性。
authentication_ldap_simple_group_sourceFE不区分，两端空白也会忽略。取值无法识别时：CREATE / ALTER SECURITY INTEGRATION 直接报错；如果是从 FE 配置项传进来的，则回落到 group_provider 并打印 ERROR 日志。
DN 类取值：authentication_ldap_simple_bind_root_dn、..._bind_base_dn、..._bind_dn_pattern目录由目录决定。 DN 里的属性类型（cn=、ou=、dc=）一律不区分大小写；属性值是否区分取决于该属性的匹配规则，常用的 cn / ou / dc 都是不区分的。
登录名FE，在发给目录之前不区分。 拼进搜索过滤器、或代入 bind DN 模板之前会先转成小写，与 Active Directory 对账号名的处理一致。
用户组名FE匹配时不区分，显示时保留原样。 GRANT ... TO EXTERNAL GROUP 与 permitted_groups 都按忽略大小写匹配，但组名字符串本身绝不改写：current_group() 和交给 Apache Ranger 的组集合保持目录返回的原始大小写。Ranger 匹配组名是区分大小写的，所以它的策略必须按目录里的写法来写。

使用 LDAP 创建用户​

创建用户时，通过 IDENTIFIED WITH authentication_ldap_simple AS 'xxx' 指定认证方式为 LDAP 认证。xxx 是用户在 LDAP 中的 DN（Distinguished Name）。

示例 1：创建用户并指定明确的 DN。

CREATE USER tom IDENTIFIED WITH authentication_ldap_simple AS 'uid=tom,ou=company,dc=example,dc=com'

示例 2：创建用户但不指定 DN。系统将根据配置在登录时通过 DN 模式（直接绑定）或搜索绑定来解析 DN。

CREATE USER tom IDENTIFIED WITH authentication_ldap_simple

如果使用搜索绑定模式，需要在 FE 中添加以下额外配置：

  • authentication_ldap_simple_bind_base_dn: 用户的 Base DN，指定用户的检索范围。
  • authentication_ldap_simple_user_search_attr: 在 LDAP 对象中标识用户的属性名称，默认为 uid。
  • authentication_ldap_simple_bind_root_dn: 用于检索用户信息的管理员账户的 DN。
  • authentication_ldap_simple_bind_root_pwd: 用于检索用户信息的管理员账户的密码。

如果使用直接绑定模式，只需配置 authentication_ldap_simple_bind_dn_pattern，无需管理员账户。

认证用户​

LDAP 认证要求客户端将明文密码传递给 StarRocks。有三种方式传递明文密码：

从 MySQL 客户端连接 LDAP​

执行时添加 --default-auth mysql_clear_password --enable-cleartext-plugin：

mysql -utom -P9030 -h127.0.0.1 -p --default-auth mysql_clear_password --enable-cleartext-plugin

从 JDBC/ODBC 客户端连接 LDAP​

  • JDBC

注意：使用JDBC链接时，Server 端必须要启用 SSL。SSL 配置请参考 SSL 认证。

JDBC 5：

Properties properties = new Properties();
properties.put("authenticationPlugins", "com.mysql.jdbc.authentication.MysqlClearPasswordPlugin");
properties.put("defaultAuthenticationPlugin", "com.mysql.jdbc.authentication.MysqlClearPasswordPlugin");
properties.put("disabledAuthenticationPlugins", "com.mysql.jdbc.authentication.MysqlNativePasswordPlugin");

JDBC 8：

Properties properties = new Properties();
properties.put("authenticationPlugins", "com.mysql.cj.protocol.a.authentication.MysqlClearPasswordPlugin");
properties.put("defaultAuthenticationPlugin", "com.mysql.cj.protocol.a.authentication.MysqlClearPasswordPlugin");
properties.put("disabledAuthenticationPlugins", "com.mysql.cj.protocol.a.authentication.MysqlNativePasswordPlugin");
  • ODBC

在 ODBC 的 DSN 中添加 default\_auth=mysql_clear_password 和 ENABLE_CLEARTEXT\_PLUGIN=1，以及用户名和密码。

Rocky the happy otterStarRocks Assistant

AI generated answers are based on docs and other sources. Please test answers in non-production environments.