企业官网建设流程全解析

StarRocks Group Provider 指南：对接 LDAP/AD/Ranger 实现用户组认证与授权

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

StarRocks 从 v3.5.0 起提供 Group Provider（组提供者）机制，用于从 LDAP、Apache Ranger 等外部认证与授权系统中采集用户组信息，实现批量化的用户组管理。本文以官方文档为主体，结合 GroupProvider.java 等前端源码，系统讲解 Group Provider 的概念、三种类型（LDAP/Unix/File）、CREATE GROUP PROVIDER完整语法与参数语义、与 Security Integration 的联动、向用户组授权（GRANT ... TO EXTERNAL GROUP）以及对接 Apache Ranger 的完整流程，读完即可在企业环境中落地 LDAP/AD 场景的用户组集成。

概述：Group Provider 是什么

为了深化与外部用户认证和授权系统（如 LDAP 与 Apache Ranger）的集成，StarRocks 支持采集外部系统中的用户组信息，用于集体化的用户管理体验。

Group Provider 本质上是一个用户与组的映射关系（mapping）。任何需要组信息的流程都可以按需查询这一映射，例如登录认证时的用户组记录、授权过程中的组判定等。组信息独立存在，可以与认证、授权或其他流程灵活集成，而不与任何特定工作流强耦合。

从源码看，这一设计落地为抽象基类 GroupProvider.java，其核心抽象方法为Set<String> getGroup(UserIdentity userIdentity, String distinguishedName)，即给定用户身份与认证时记录的 DN，返回该用户所属的组集合。具体实现由工厂 GroupProviderFactory.java 按type属性分发创建。

支持的三种类型

StarRocks 支持三种 Group Provider（详见 unix_file_intro.mdx）：

• LDAP group provider：在 LDAP 服务中搜索并匹配用户与组；
• Unix group provider：在操作系统层面搜索并匹配用户与组；
• File group provider：根据一个文件中定义的用户组进行搜索与匹配。

工作流程

以下流程图以 LDAP 和 Apache Ranger 为例，说明 Group Provider 的整体工作流程：

创建 Group Provider

语法总览

CREATE GROUP PROVIDER用于创建组提供者，三种类型共用一个 DDL，区别仅在于type属性：

-- LDAP group provider CREATE GROUP PROVIDER <group_provider_name> PROPERTIES ( "type" = "ldap", ldap_info, ldap_search_group_arg, ldap_search_attr, [ldap_cache_attr] ) ldap_info ::= "ldap_conn_url" = "", "ldap_bind_root_dn" = "", "ldap_bind_root_pwd" = "", "ldap_bind_base_dn" = "", ["ldap_conn_timeout" = "",] ["ldap_conn_read_timeout" = ""] ["ldap_ssl_conn_allow_insecure" = ""] ["ldap_ssl_conn_trust_store_path" = ""] ["ldap_ssl_conn_trust_store_pwd" = ""] ldap_search_group_arg ::= { "ldap_group_dn" = "" | "ldap_group_filter" = "" }, "ldap_group_identifier_attr" = "" ldap_search_user_arg ::= "ldap_group_member_attr" = "", "ldap_user_search_attr" = "" ldap_cache_arg ::= "ldap_cache_refresh_interval" = ""

-- Unix group provider CREATE GROUP PROVIDER <group_provider_name> PROPERTIES ( "type" = "unix" )

-- File group provider CREATE GROUP PROVIDER <group_provider_name> PROPERTIES ( "type" = "file", "group_file_url" = "" )

参数说明

type

要创建的组提供者类型。取值（与 GroupProviderFactory.java 中SUPPORT_GROUP_PROVIDER集合一一对应）：

• ldap：创建 LDAP 组提供者，需指定ldap_info、ldap_search_group_arg、ldap_search_user_arg，可选ldap_cache_arg；
• unix：创建 Unix 组提供者；
• file：创建文件组提供者，需指定group_file_url。

group_file_url

定义用户组的文件 URL 或相对路径（位于fe/conf下）。

:::note

组文件包含一组组及其成员的列表，每行定义一个组，组名与成员之间用冒号分隔，多个用户之间用逗号分隔。示例：group_name:user_1,user_2,user_3。

:::

ldap_info参数组

用于连接 LDAP 服务的连接信息。结合 LDAPGroupProvider.java 中声明的属性常量，各参数如下：

ldap_conn_url

LDAP 服务器的 URL，格式：ldap://<ldap_server_host>:<ldap_server_port>。源码中对应常量LDAP_LDAP_CONN_URL，属于必填项（REQUIRED_PROPERTIES之一）。

ldap_bind_root_dn

LDAP 服务的管理员 Distinguished Name（DN），必填。

ldap_bind_root_pwd

LDAP 服务的管理员密码，必填。

ldap_bind_base_dn

集群搜索用户的 LDAP 基础 DN（base DN），必填。

ldap_conn_timeout

可选。连接 LDAP 服务的超时时间。

ldap_conn_read_timeout

可选。连接中 LDAP 服务读操作的超时时间。

ldap_ssl_conn_allow_insecure

可选。是否允许与 LDAP 服务器建立非加密连接。默认值：true。设为false表示访问 LDAP 必须使用 SSL 加密。

ldap_ssl_conn_trust_store_path

可选。存储 LDAP 服务器 SSL CA 证书的本地路径，支持 pem 与 jks 格式。若证书由受信任机构签发，则无需设置。

ldap_ssl_conn_trust_store_pwd

可选。访问本地存储的 LDAP 服务器 SSL CA 证书的密码。pem 格式证书无需密码，仅 jks 格式证书需要。

ldap_search_group_arg参数组

控制 StarRocks 如何搜索组的参数。

:::noteldap_group_dn与ldap_group_filter只能二选一，同时指定二者不受支持（源码注释同样明确了这一约束，见 LDAPGroupProvider.java）。 :::

ldap_group_dn

待搜索组的 DN。将直接使用该 DN 查询组。示例："cn=ldapgroup1,ou=Group,dc=starrocks,dc=com;cn=ldapgroup2,ou=Group,dc=starrocks,dc=com"（多个组用分号分隔）。

ldap_group_filter

可被 LDAP 服务器识别的自定义组过滤器，将直接发送给 LDAP 服务器用于搜索组。示例：(&(objectClass=groupOfNames)(cn=testgroup))。

ldap_group_identifier_attr

用作组名称标识符的属性。

ldap_search_user_arg参数组

控制 StarRocks 如何识别组内用户的参数。

ldap_group_member_attr

表示组成员的属性。有效值：member和memberUid。

ldap_user_search_attr

指定如何从成员属性值中提取用户标识符。可以显式定义一个属性（如cn或uid），也可以使用正则表达式。

:::note

DN 匹配机制

• 配置了ldap_user_search_attr时：系统从组成员 DN 中提取指定值作为用户名，并在组搜索时以登录用户名为 key；
• 未配置ldap_user_search_attr时：系统直接用完整 DN 作为用户标识符，并在组搜索时以认证时记录的 DN 作为 key。

该设计使 LDAP Group Provider 能够适配不同 LDAP 环境，尤其是 Microsoft AD 这类复杂环境。

:::

:::tip

与authentication_ldap_simple_bind_dn_pattern的交互

当使用 DN 模式认证（例如uid=${USER}@abc.com,ou=People,dc=example,dc=com），${USER}替换被嵌入在更大的属性值中时：

• 推荐做法：不配置ldap_user_search_attr，系统将使用完整 DN 进行组匹配，避免提取错误。
• 如果必须配置：使用只提取用户名的正则。例如 DN 模式为uid=${USER}@abc.com,ou=People,dc=example,dc=com时，将ldap_user_search_attr设为uid=([^,@]+)@abc.com只提取${USER}部分。简单的uid或uid=([^,]+)会错误地提取出alice@abc.com而非alice。

:::

ldap_cache_arg参数组

定义 LDAP 组信息缓存行为的参数。

ldap_cache_refresh_interval

可选。StarRocks 自动刷新已缓存 LDAP 组信息的间隔。单位：秒。默认：900（15 分钟）。

从源码实现看，所有 LDAP Group Provider 共享同一个调度线程池（ScheduledExecutorService，线程数由Config.group_provider_refresh_thread_num控制，见 LDAPGroupProvider.java），缓存以“用户 → 组集合”的形式保存在userToGroupCache（ConcurrentHashMap）中，并通过调度任务周期性刷新；组提供者被销毁时会取消对应的周期调度任务。

示例一：LDAP 环境

假设 LDAP 服务器中包含如下组与成员信息：

-- Group information # testgroup, Group, starrocks.com dn: cn=testgroup,ou=Group,dc=starrocks,dc=com objectClass: groupOfNames cn: testgroup member: uid=test,ou=people,dc=starrocks,dc=com member: uid=tom,ou=people,dc=starrocks,dc=com -- User information # test, People, starrocks.com dn: cn=test,ou=People,dc=starrocks,dc=com objectClass: inetOrgPerson cn: test uid: test sn: FTE userPassword::

为testgroup的成员创建组提供者ldap_group_provider：

CREATE GROUP PROVIDER ldap_group_provider PROPERTIES( "type"="ldap", "ldap_conn_url"="ldap://xxxx:xxx", "ldap_bind_root_dn"="cn=admin,dc=starrocks,dc=com", "ldap_bind_root_pwd"="123456", "ldap_bind_base_dn"="dc=starrocks,dc=com", "ldap_group_filter"="(&(objectClass=groupOfNames)(cn=testgroup))", "ldap_group_identifier_attr"="cn", "ldap_group_member_attr"="member", "ldap_user_search_attr"="uid=([^,]+)" )

上例使用ldap_group_filter搜索objectClass为groupOfNames且cn为testgroup的组，因此在ldap_group_identifier_attr中指定cn来标识组名；ldap_group_member_attr设为member，即使用groupOfNames对象类中的member属性标识成员；ldap_user_search_attr设为表达式uid=([^,]+)，用于从member属性值中识别用户。

示例二：Microsoft AD 环境

假设 Microsoft AD 服务器中包含如下组与成员信息：

-- Group information # ADGroup, Groups, company.com dn: CN=ADGroup,OU=Groups,DC=company,DC=com objectClass: group cn: ADGroup member: CN=John Doe,OU=Users,DC=company,DC=com member: CN=Jane Smith,OU=Users,DC=company,DC=com -- User information # John Doe, Users, company.com dn: CN=John Doe,OU=Users,DC=company,DC=com objectClass: user cn: John Doe sAMAccountName: johndoe

为 Microsoft AD 环境创建 Group Provider：

CREATE GROUP PROVIDER ad_group_provider PROPERTIES( "type"="ldap", "ldap_conn_url"="ldap://ad.company.com:389", "ldap_bind_root_dn"="CN=admin,OU=Users,DC=company,DC=com", "ldap_bind_root_pwd"="password", "ldap_bind_base_dn"="DC=company,DC=com", "ldap_group_filter"="(&(objectClass=group)(cn=ADGroup))", "ldap_group_identifier_attr"="cn", "ldap_group_member_attr"="member" -- 注意：不要配置 ldap_user_search_attr，系统将使用完整 DN 进行匹配 )

由于本示例未配置ldap_user_search_attr，系统将：

1. 在组缓存构建阶段，直接使用完整 DN（例如CN=John Doe,OU=Users,DC=company,DC=com）作为用户标识符；
2. 在组搜索阶段，使用认证时记录的 DN 作为 key 搜索用户所属的组。

这一方式特别适合 Microsoft AD 环境，因为 AD 中的组成员可能缺少简单的用户名属性。

将 Group Provider 与 Security Integration 结合

创建组提供者后，可将其与安全集成（Security Integration）结合，使组提供者指定的用户能够登录 StarRocks。关于创建安全集成的更多信息，参见 Authenticate with Security Integration。

语法

ALTER SECURITY INTEGRATION <security_integration_name> SET ( "group_provider" = "", "permitted_groups" = "" )

参数说明

group_provider

要与安全集成结合的组提供者名称，多个组提供者用逗号分隔。设置后，用户登录时 StarRocks 会在每个指定提供者下记录该用户的组信息。

permitted_groups

可选。允许登录 StarRocks 的组名，多个组用逗号分隔。请确保指定的组能被所结合的组提供者检索到。

示例

ALTER SECURITY INTEGRATION LDAP SET ( "group_provider"="ldap_group_provider", "permitted_groups"="testgroup" );

向用户组授予角色

可以通过 GRANT 向用户组授予角色。

以下示例将角色example_role授予用户组analysts：

GRANT example_role TO EXTERNAL GROUP analysts;

将 Group Provider 与外部授权系统（Apache Ranger）结合

一旦在安全集成中配置了关联的组提供者，StarRocks 会在用户登录时记录其组信息，这些组信息会自动包含在与 Ranger 的授权流程中，无需额外配置。

更多关于 StarRocks 集成 Ranger 的操作指引，参见 Manage permissions with Apache Ranger。

总结

Group Provider 是 StarRocks 面向企业级认证授权场景的关键扩展点：它以“用户 → 组”映射的抽象（见 GroupProvider.java）为核心，通过 LDAP、Unix、File 三种实现（由 GroupProviderFactory.java 统一创建）覆盖不同的组信息来源；再经由 Security Integration 的group_provider、permitted_groups属性接入登录认证与 Ranger 授权链路，配合GRANT ... TO EXTERNAL GROUP完成组级权限下发。生产环境中推荐重点关注 LDAP 场景下的 DN 匹配机制（ldap_user_search_attr配置与否）、缓存刷新间隔（默认 900 秒）以及 AD 环境下完整 DN 匹配的用法，从而构建稳定、可维护的外部用户组管理体系。

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks