tool
/
starrocks
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Doc] Add DN matching mechanism for LDAP Group Provider and update documentation (backport #63115) (#63158) 

Signed-off-by: 絵空事スピリット <wanglichen@starrocks.com>
Co-authored-by: Harbor Liu <460660596@qq.com>
Co-authored-by: 絵空事スピリット <wanglichen@starrocks.com>
This commit is contained in:
mergify[bot] 2025-09-16 09:54:54 +08:00 committed by GitHub
parent a8c769ab8c
commit 5670387325
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 269 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/en/administration/user_privs/authentication/ldap_authentication.md
View File

@ -33,12 +33,32 @@ If you wish to authenticate users by means of StarRocks retrieving them directly
authentication_ldap_simple_bind_base_dn =
# Add the name of the attribute that identifies the user in the LDAP object. Default: uid.
authentication_ldap_simple_user_search_attr =
# Add the DN of the administrator account to be used when retrieving users.
# Add the admin DN for retrieving users.
authentication_ldap_simple_bind_root_dn =
# Add the password of theAdministrator account to be used when retrieving users.
# Add the admin password for retrieving users.
authentication_ldap_simple_bind_root_pwd =
```
## DN Matching Mechanism
Starting from v3.5.0, StarRocks supports recording and passing user Distinguished Name (DN) information during LDAP authentication to provide more accurate group resolution.
### How it Works
1. **Authentication Phase**: LDAPAuthProvider records both pieces of information after successful user authentication:
- Login username (for traditional group matching)
- User's complete DN (for DN-based group matching)
2. **Group Resolution Phase**: LDAPGroupProvider determines the matching strategy based on the `ldap_user_search_attr` parameter configuration:
- **When `ldap_user_search_attr` is configured**, it uses username as the key for group matching.
- **When `ldap_user_search_attr` is not configured**, it uses DN as the key for group matching.
### Use Cases
- **Traditional LDAP Environment**: Group members use simple usernames (such as `cn` attribute). Administrators need to configure `ldap_user_search_attr`.
- **Microsoft AD Environment**: Group members may lack username attributes. `ldap_user_search_attr` cannot be configured. The system will use DN directly for matching.
- **Mixed Environment**: Flexible switching between both matching methods is supported.
## Create a user with LDAP
When creating a user, specify the authentication method as LDAP authentication by `IDENTIFIED WITH authentication_ldap_simple AS 'xxx'`. xxx is the DN (Distinguished Name) of the user in LDAP.

13
docs/en/administration/user_privs/authentication/security_integration.md
View File

@ -79,6 +79,19 @@ PROPERTIES (
- Required: Yes
- Description: The user's attribute used to log in to the LDAP service, for example, `uid`.
:::note
**DN Passing Mechanism**: LDAP security integration supports DN passing functionality.
- After successful authentication, the system records both the user's login name and complete DN.
- When combined with Group Provider, DN information is automatically passed to the Group Provider.
- If `ldap_user_search_attr` is not configured for the Group Provider, DN will be used for group matching.
- This mechanism is particularly suitable for complex LDAP environments like Microsoft AD.
For more details, see the DN matching mechanism in [Authenticate User Groups](../group_provider.md).
:::
##### authentication_ldap_simple_bind_root_dn
- Required: Yes

55
docs/en/administration/user_privs/group_provider.md
View File

@ -161,6 +161,17 @@ The attribute that represents group members. Valid values: `member` and `memberU
Specifies how to extract the user identifier from the member attribute value. You can explicitly define an attribute (for example, `cn` or `uid`) or use a regular expression.
:::note
**DN Matching Mechanism**
- **When `ldap_user_search_attr` is configured**, the system extracts the specified value from group member DNs and uses it as usernames, and uses login username as key during group search.
- **When `ldap_user_search_attr` is not configured**, the system uses the complete DN directly as user identifier, and uses the DN recorded during authentication as key during group search.
This design enables LDAP Group Provider to adapt to different LDAP environments, especially complex environments like Microsoft AD.
:::
#### `ldap_cache_arg` parameter group
The argument used to define the cache behavior for the LDAP group information.
@ -221,6 +232,50 @@ PROPERTIES(
The above example uses `ldap_group_filter` to search for a group with the `groupOfNames` objectClass and a `cn` of `testgroup`. Therefore, `cn` is specified in `ldap_group_identifier_attr` to identify the group. `ldap_group_member_attr` is set to `member` so that the `member` attribute is used in the `groupOfNames` objectClass to identify members. `ldap_user_search_attr` is set to an expression `uid=([^,]+)`, which is used to identify users in the `member` attribute.
### Microsoft AD Environment Example
Suppose a Microsoft AD server contains the following group and member information:
```Plain
-- 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
```
Create a Group Provider for Microsoft AD environment:
```SQL
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"
-- Note: Do not configure ldap_user_search_attr, system will use complete DN for matching
)
```
In this example, since `ldap_user_search_attr` is not configured, the system will:
1. During group cache construction, directly use the complete DN (for example, `CN=John Doe,OU=Users,DC=company,DC=com`) as user identifier.
2. During group search, use the DN recorded during authentication as key to search user's groups.
This approach is particularly suitable for Microsoft AD environments, as group members in AD may lack simple username attributes.
## Combine group provider with a security integration
After creating the group provider, you can combine it with a security integration to allow users specified by the group provider to log in to StarRocks. For more information on creating a security integration, see [Authenticate with Security Integration](./authentication/security_integration.md).

24
docs/ja/administration/user_privs/authentication/ldap_authentication.md
View File

@ -33,12 +33,32 @@ StarRocks が LDAP システム内でユーザーを直接取得する方法で
authentication_ldap_simple_bind_base_dn =
# LDAP オブジェクト内でユーザーを識別する属性の名前を追加します。デフォルトは uid です。
authentication_ldap_simple_user_search_attr =
# ユーザーを取得する際に使用する管理者アカウントの DN を追加します。
# ユーザーを取得するための管理者 DN を追加します。
authentication_ldap_simple_bind_root_dn =
# ユーザーを取得する際に使用する管理者アカウントのパスワードを追加します。
# ユーザーを取得するための管理者パスワードを追加します。
authentication_ldap_simple_bind_root_pwd =
```
## DN マッチングメカニズム
v3.5.0 以降、StarRocks は LDAP 認証時にユーザーの識別名 (DN) 情報を記録および渡す機能をサポートし、より正確なグループ解決を実現します。
### 動作原理
1. **認証フェーズ**: LDAPAuthProviderは、ユーザー認証成功後に以下の2つの情報を記録します：
- ログインユーザー名（従来のグループマッチング用）
- ユーザーの完全なDN（DNベースのグループマッチング用）
2. **グループ解決フェーズ**: LDAPGroupProvider は、`ldap_user_search_attr` パラメータの設定に基づいてマッチング戦略を決定します:
- **`ldap_user_search_attr` が設定されている場合**、グループマッチングのキーとしてユーザー名を使用します。
- **`ldap_user_search_attr` が設定されていない場合**、グループマッチングのキーとして DN を使用します。
### 使用例
- **従来の LDAP 環境**: グループメンバーは単純なユーザー名（`cn` 属性など）を使用します。管理者は `ldap_user_search_attr` を設定する必要があります。
- **Microsoft AD 環境**: グループメンバーにユーザー名属性が存在しない場合があります。`ldap_user_search_attr` は設定できません。システムは直接 DN を使用して照合を行います。
- **混合環境**: 両方の照合方法を柔軟に切り替えることがサポートされています。
## LDAP でユーザーを作成する
ユーザーを作成する際、認証方法を LDAP 認証として `IDENTIFIED WITH authentication_ldap_simple AS 'xxx'` と指定します。xxx は LDAP 内のユーザーの DN (Distinguished Name) です。

13
docs/ja/administration/user_privs/authentication/security_integration.md
View File

@ -79,6 +79,19 @@ PROPERTIES (
- 必須: はい
- 説明: LDAP サービスにログインするために使用されるユーザーの属性。例: `uid`。
:::note
**DN パス機構**: LDAP セキュリティインテグレーションは DN パス機能をサポートします。
- 認証成功後、システムはユーザーのログイン名と完全な DN の両方を記録します。
- Group Provider と組み合わせると、DN 情報が自動的にグループプロバイダに渡されます。
- Group Provider で `ldap_user_search_attr` が設定されていない場合、グループマッチングには DN が使用されます。
- このメカニズムは Microsoft AD のような複雑な LDAP 環境に特に適しています。
詳細は[ユーザーグループの認証](../group_provider.md)の DN マッチングメカニズムを参照してください。
:::
##### authentication_ldap_simple_bind_root_dn
- 必須: はい

54
docs/ja/administration/user_privs/group_provider.md
View File

@ -162,6 +162,17 @@ StarRocks がグループ内のユーザーを識別する方法を制御する
メンバー属性値からユーザー識別子を抽出する方法を指定します。明示的に属性を定義することも（例: `cn` または `uid`）、正規表現を使用することもできます。
:::note
**DN マッチングメカニズム**
- **`ldap_user_search_attr` が設定されている場合**、システムはグループメンバーの DN から指定された値を抽出し、それをユーザー名として使用します。また、グループ検索時にはログインユーザー名をキーとして使用します。
- **`ldap_user_search_attr` が設定されていない場合**、システムは完全な DN を直接ユーザー識別子として使用し、グループ検索時には認証時に記録された DN をキーとして使用します。
この設計により、LDAP Group Provider は様々な LDAP 環境、特に Microsoft ADの ような複雑な環境に適応できます。
:::
#### `ldap_cache_arg` パラメーターグループ
LDAP グループ情報のキャッシュ動作を定義するために使用される引数。
@ -222,6 +233,49 @@ PROPERTIES(
上記の例では、`ldap_group_filter` を使用して `groupOfNames` objectClass と `cn` が `testgroup` のグループを検索します。したがって、`cn` はグループを識別するために `ldap_group_identifier_attr` に指定されます。`ldap_group_member_attr` は `member` に設定されており、`groupOfNames` objectClass でメンバーを識別するために `member` 属性が使用されます。`ldap_user_search_attr` は `uid=([^,]+)` という式に設定されており、`member` 属性内のユーザーを識別するために使用されます。
### Microsoft AD環境の例
Microsoft AD サーバーに以下のグループとメンバー情報が存在すると仮定します：
```Plain
-- グループ情報
# 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
-- ユーザー情報
# 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 を作成する:
```SQL
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"
-- Note: Do not configure ldap_user_search_attr, system will use complete DN for matching
)
```
この例では、`ldap_user_search_attr` が設定されていないため、システムは以下を行います：
1. グループキャッシュ構築時、完全な DN（例：`CN=John Doe,OU=Users,DC=company,DC=com`）をユーザー識別子として直接使用します。
2. グループ検索時、認証時に記録されたDNをキーとしてユーザーのグループを検索します。
このアプローチは、Microsoft AD 環境において特に適しています。AD のグループメンバーには単純なユーザー名属性が存在しない場合があるためです。
## Group Provider をセキュリティインテグレーションと組み合わせる
Group Provider を作成した後、セキュリティインテグレーションと組み合わせて、Group Provider で指定されたユーザーが StarRocks にログインできるようにすることができます。セキュリティインテグレーションの作成に関する詳細は、[Authenticate with Security Integration](./authentication/security_integration.md) を参照してください。

24
docs/zh/administration/user_privs/authentication/ldap_authentication.md
View File

@ -33,12 +33,32 @@ authentication_ldap_simple_ssl_conn_trust_store_pwd =
authentication_ldap_simple_bind_base_dn =
# 添加在 LDAP 对象中标识用户的属性名称。默认：uid。
authentication_ldap_simple_user_search_attr =
# 添加用于检索用户的管理员账户的 DN。
# 添加用于检索用户的 Admin DN。
authentication_ldap_simple_bind_root_dn =
# 添加用于检索用户的管理员账户的密码。
# 添加用于检索用户的 Admin 密码。
authentication_ldap_simple_bind_root_pwd =
```
## 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 创建用户
创建用户时，通过 `IDENTIFIED WITH authentication_ldap_simple AS 'xxx'` 指定认证方式为 LDAP 认证。xxx 是用户在 LDAP 中的 DN（Distinguished Name）。

13
docs/zh/administration/user_privs/authentication/security_integration.md
View File

@ -79,6 +79,19 @@ PROPERTIES (
- 必需：是
- 描述：用于登录 LDAP 服务的用户属性，例如 `uid`。
:::note
**DN 传递机制**：LDAP 安全集成支持 DN 传递功能。
- 认证成功后，系统会同时记录用户的登录名和完整 DN。
- 当与 Group Provider 结合使用时，DN 信息会自动传递给 Group Provider。
- 如果 Group Provider 未配置 `ldap_user_search_attr` 参数，将使用 DN 进行组匹配。
- 这种机制特别适用于 Microsoft AD 等复杂 LDAP 环境。
有关详细信息，请参见[认证用户组](../group_provider.md)中的 DN 匹配机制说明。
:::
##### authentication_ldap_simple_bind_root_dn
- 必需：是

55
docs/zh/administration/user_privs/group_provider.md
View File

@ -161,6 +161,17 @@ LDAP 服务器可以识别的自定义组过滤器。它将被直接发送到您
指定如何从成员属性值中提取用户标识符。您可以显式定义一个属性（例如，`cn` 或 `uid`）或使用正则表达式。
:::note
**DN 匹配机制**
- **如配置了 `ldap_user_search_attr`**，则从组成员 DN 中提取指定属性的值作为用户名，组查找时使用登录用户名作为 Key。
- **如未配置 `ldap_user_search_attr`**，则直接使用完整的 DN 作为用户标识，组查找时使用认证时记录的 DN 作为 Key。
这种设计使得 LDAP Group Provider 能够适应不同的 LDAP 环境，特别是 Microsoft AD 等复杂环境。
:::
#### `ldap_cache_arg` 参数组
用于定义 LDAP 组信息缓存行为的参数。
@ -221,6 +232,50 @@ PROPERTIES(
上述示例使用 `ldap_group_filter` 搜索具有 `groupOfNames` objectClass 和 `cn` 为 `testgroup` 的组。因此，在 `ldap_group_identifier_attr` 中指定 `cn` 以识别该组。`ldap_group_member_attr` 设置为 `member`，以便在 `groupOfNames` objectClass 中使用 `member` 属性识别成员。`ldap_user_search_attr` 设置为表达式 `uid=([^,]+)`，用于识别 `member` 属性中的用户。
### Microsoft AD 环境示例
假设一个 Microsoft AD 服务器包含以下组和成员信息：
```Plain
-- 组信息
# 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
-- 用户信息
# 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：
```SQL
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 与安全集成结合
创建 Group Provider 后，您可以将其与安全集成结合，以允许 Group Provider 指定的用户登录到 StarRocks。有关创建安全集成的更多信息，请参见[通过安全集成进行认证](./authentication/security_integration.md)。