This is an automated email from the ASF dual-hosted git repository.
morrySnow pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new e2a7a72c82e [doc] add LDAP default roles docs (#3697)
e2a7a72c82e is described below
commit e2a7a72c82e10a247305902b724fa00465f375fd
Author: Raiden <[email protected]>
AuthorDate: Tue Jun 2 11:52:23 2026 +0800
[doc] add LDAP default roles docs (#3697)
## Related PR
- Code PR: https://github.com/apache/doris/pull/63411
## Versions
- [x] dev
- [ ] 4.x
- [ ] 3.x
- [ ] 2.1
## Languages
- [x] Chinese
- [x] English
## Summary
Adds documentation for `ldap_default_roles`, which allows Doris to grant
configured default roles to every LDAP-authenticated user.
The update explains:
1. How `ldap_default_roles` differs from the built-in `ldapDefaultRole`.
2. How default LDAP roles are merged with LDAP group roles and existing
Doris user privileges.
3. That roles configured in `ldap_default_roles` must already exist in
Doris.
4. How to configure `ldap_default_roles` in `ldap.conf`.
5. How to update `ldap_default_roles` online with `ADMIN SET FRONTEND
CONFIG`.
6. That online updates of `ldap_default_roles` refresh the LDAP user
cache automatically.
## Files
- `docs/admin-manual/auth/authentication/ldap.md`
-
`i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/authentication/ldap.md`
---
docs/admin-manual/auth/authentication/ldap.md | 66 ++++++++++++++++++++--
.../admin-manual/auth/authentication/ldap.md | 66 ++++++++++++++++++++--
2 files changed, 122 insertions(+), 10 deletions(-)
diff --git a/docs/admin-manual/auth/authentication/ldap.md
b/docs/admin-manual/auth/authentication/ldap.md
index 398df338977..f0eb3535f88 100644
--- a/docs/admin-manual/auth/authentication/ldap.md
+++ b/docs/admin-manual/auth/authentication/ldap.md
@@ -10,6 +10,7 @@
"LDAP group authorization",
"unified authentication",
"ldap.conf configuration",
+ "ldap_default_roles",
"MysqlClearPasswordPlugin",
"ldap_admin_password",
"ldap_use_ssl",
@@ -25,6 +26,7 @@ Apache Doris supports integration with third-party LDAP
services, so the existin
- **Authentication login**: Use the LDAP password instead of the Doris
password for identity authentication.
- **Group authorization**: Map LDAP `group` to Doris `role` to achieve unified
privilege management.
+- **Default role authorization**: Grant configured Doris roles to every
LDAP-authenticated user without putting all users into one LDAP group.
<!-- Knowledge type: Architecture decision -->
<!-- Applicable scenario: Integrating enterprise unified identity /
centralized privilege management -->
@@ -35,6 +37,7 @@ Apache Doris supports integration with third-party LDAP
services, so the existin
| --- | --- |
| Enterprise unified identity authentication | An LDAP/AD account system
already exists, and you want Doris users to reuse it directly without creating
accounts again in Doris |
| Centralized privilege management | Manage role members through LDAP groups;
adjust LDAP group members to batch-adjust Doris privileges |
+| Baseline privileges for LDAP users | Grant the same Doris roles to all
LDAP-authenticated users through configuration, while still keeping LDAP group
authorization |
| Temporary access | Users that exist only in LDAP can log in to Doris as
temporary users based on LDAP group privileges |
| Encrypted channel | Encryption is required for the connection between Doris
FE and the LDAP server (LDAPS) |
@@ -87,6 +90,7 @@ In LDAP, data is organized in a tree structure. The following
is a typical LDAP
3. **Configure the client**: Enable the cleartext password plugin in the MySQL
Client or JDBC Client to send the LDAP password.
4. **(Optional) Enable LDAPS**: Encrypt the channel between FE and LDAP.
5. **(Optional) Configure group authorization**: Create `role` in Doris with
the same name as the LDAP groups and grant privileges.
+6. **(Optional) Configure default roles**: Grant baseline Doris roles to all
LDAP-authenticated users through `ldap_default_roles`.
## Step 1: Configure Doris FE
@@ -113,6 +117,7 @@ ldap_admin_name = uid=admin,o=emr
ldap_user_basedn = ou=people,o=emr
ldap_user_filter = (&(uid={login}))
ldap_group_basedn = ou=group,o=emr
+ldap_default_roles = ldap_readonly,ldap_query_user
```
The configuration items are explained below:
@@ -126,6 +131,7 @@ The configuration items are explained below:
| `ldap_user_basedn` | The base `dn` for user search |
| `ldap_user_filter` | User match filter. `{login}` is replaced with the login
user name |
| `ldap_group_basedn` | The base `dn` for group search, used for group
authorization |
+| `ldap_default_roles` | Optional. Comma-separated Doris roles granted to
every LDAP-authenticated user. These roles are added in addition to LDAP group
roles |
:::tip
To enable LDAPS (encrypted connection to the LDAP server), see the [LDAPS
(Encrypted Connection)](#ldaps-encrypted-connection) section below.
@@ -235,8 +241,8 @@ After LDAP is enabled, the login behavior under different
user states is as foll
- The temporary account is valid only for the current connection and is
automatically destroyed after the connection is closed.
- Doris does not create persistent user metadata for a temporary user.
-- The privileges of a temporary user are determined by LDAP group
authorization (see the "Group Authorization" section below).
-- If the temporary user has no corresponding group privileges, it has the
`select_priv` privilege on `information_schema` by default.
+- The privileges of a temporary user are determined by LDAP group
authorization and `ldap_default_roles` (see the "Group Authorization" and
"Default Roles for LDAP Users" sections below).
+- If the temporary user has no corresponding group privileges or configured
default roles, it has the `select_priv` privilege on `information_schema` by
default.
:::
@@ -265,7 +271,7 @@ mysql -hDoris_HOST -PDoris_PORT -ujack -p 123456
- LDAP user attributes: `uid: jack`, password: `abcdef`
-Log in with the LDAP password. Doris automatically creates the temporary user
`jack@'%'` and logs in. The temporary user has the basic privilege
`DatabasePrivs`: `Select_priv`, and is automatically destroyed after the
connection is closed:
+Log in with the LDAP password. Doris automatically creates the temporary user
`jack@'%'` and logs in. The temporary user receives LDAP group roles and
configured default roles if they are available. If no matching roles are
available, it has the basic privilege `DatabasePrivs`: `Select_priv`, and is
automatically destroyed after the connection is closed:
```sql
mysql -hDoris_HOST -PDoris_PORT -ujack -p abcdef
@@ -290,6 +296,7 @@ LDAP group authorization maps LDAP `group` to Doris `role`,
providing centralize
- If the `dn` of an LDAP user appears in the `member` attribute of an LDAP
group node, Doris considers the user to belong to that group.
- When the user logs in, Doris automatically grants the user the `role`
privileges corresponding to the LDAP groups it belongs to.
+- If `ldap_default_roles` is configured, Doris also grants those default roles
to the user.
- After the user logs out, Doris automatically revokes these `role` privileges.
:::caution Prerequisites
@@ -302,9 +309,9 @@ The final privileges of the logged-in user depend on its
state in LDAP and Doris
| LDAP user | Doris user | Final privileges |
| --------- | ---------- | ---------------- |
-| Exists | Exists | LDAP group privileges + Doris user privileges |
+| Exists | Exists | LDAP group privileges + configured default roles + Doris
user privileges |
| Does not exist | Exists | Doris user privileges |
-| Exists | Does not exist | LDAP group privileges |
+| Exists | Does not exist | LDAP group privileges + configured default roles |
### Group Name Mapping Rules
@@ -331,6 +338,50 @@ Suppose user jack belongs to the LDAP groups `doris_rd`,
`doris_qa`, and `doris_
:::
+## Default Roles for LDAP Users
+
+<!-- Knowledge type: Configuration parameters -->
+<!-- Applicable scenario: Granting baseline Doris privileges to all
LDAP-authenticated users -->
+
+`ldap_default_roles` is used to grant baseline Doris roles to every
LDAP-authenticated user. It is useful when all LDAP users should have the same
basic privileges, but maintaining a dedicated LDAP group that contains all LDAP
users is impractical.
+
+`ldap_default_roles` does not replace LDAP group authorization. When an LDAP
user logs in, Doris merges all of the following privileges:
+
+- Doris roles mapped from the user's LDAP groups.
+- Doris roles configured in `ldap_default_roles`.
+- Existing privileges of the Doris user, if the same account also exists in
Doris.
+- The built-in `ldapDefaultRole`, which provides `select_priv` on
`information_schema`.
+
+:::caution Prerequisites
+Roles listed in `ldap_default_roles` must already exist in Doris. If a
configured role does not exist, Doris ignores that role and logs a warning.
+:::
+
+### Configure Default Roles
+
+Create the roles and grant privileges to them:
+
+```sql
+CREATE ROLE ldap_readonly;
+CREATE ROLE ldap_query_user;
+
+GRANT SELECT_PRIV ON internal.example_db.* TO ROLE 'ldap_readonly';
+GRANT SELECT_PRIV ON internal.example_db.example_table TO ROLE
'ldap_query_user';
+```
+
+Configure the roles in `fe/conf/ldap.conf`:
+
+```text
+ldap_default_roles = ldap_readonly,ldap_query_user
+```
+
+You can also update the value online:
+
+```sql
+ADMIN SET FRONTEND CONFIG ("ldap_default_roles" =
"ldap_readonly,ldap_query_user");
+```
+
+After `ldap_default_roles` is updated online, Doris refreshes the LDAP user
cache automatically so later LDAP logins can use the new default roles.
+
## LDAPS (Encrypted Connection)
<!-- Knowledge type: Configuration parameters -->
@@ -395,6 +446,8 @@ In the following scenarios, you may need to manually
refresh the cache so that t
- User or group information in the LDAP service has been modified.
- The `Role` privileges corresponding to LDAP user groups in Doris have been
modified.
+Online updates to `ldap_default_roles` refresh the LDAP user cache
automatically. You do not need to run `refresh ldap` only for this
configuration change.
+
You can refresh the cache with the `refresh ldap` statement. For details, see
[REFRESH-LDAP](../../../sql-manual/sql-statements/account-management/REFRESH-LDAP).
## Known Limitations
@@ -411,6 +464,8 @@ You can refresh the cache with the `refresh ldap`
statement. For details, see [R
After logging in to Doris with an LDAP user, run `show grants;` to view all
roles of the current user. Among them, `ldapDefaultRole` is the default role
that every LDAP user has.
+`ldapDefaultRole` is a built-in temporary role that provides `select_priv` on
`information_schema`. It is different from roles configured in
`ldap_default_roles`.
+
### Q: An LDAP user has fewer roles in Doris than expected. How do I
troubleshoot?
Check the following items one by one:
@@ -419,6 +474,7 @@ Check the following items one by one:
2. Check whether the expected `group` is located under the organizational
structure corresponding to `ldap_group_basedn`.
3. Check whether the expected `group` contains the `member` attribute.
4. Check whether the `member` attribute of the expected `group` contains the
`dn` of the current user.
+5. If the missing role is configured in `ldap_default_roles`, check whether
the role name is spelled correctly and whether the role exists in Doris.
### Q: LDAPS connection fails. How do I troubleshoot?
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/authentication/ldap.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/authentication/ldap.md
index a2ffd9fd46d..3789c942b01 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/authentication/ldap.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/authentication/ldap.md
@@ -10,6 +10,7 @@
"LDAP 组授权",
"统一身份验证",
"ldap.conf 配置",
+ "ldap_default_roles",
"MysqlClearPasswordPlugin",
"ldap_admin_password",
"ldap_use_ssl",
@@ -25,6 +26,7 @@ Apache Doris 支持接入第三方 LDAP 服务，将企业内已有的账号体
- **验证登录**：使用 LDAP 密码替代 Doris 密码进行身份认证。
- **组授权**：将 LDAP 中的 `group` 映射为 Doris 中的 `role`，实现统一权限管理。
+- **默认角色授权**：为所有通过 LDAP 认证的用户授予配置好的 Doris 角色，无需将所有用户维护到同一个 LDAP 组中。
<!-- 知识类型: 架构选型决策 -->
<!-- 适用场景: 接入企业统一身份 / 集中权限管理 -->
@@ -35,6 +37,7 @@ Apache Doris 支持接入第三方 LDAP 服务，将企业内已有的账号体
| --- | --- |
| 企业统一身份认证 | 已有 LDAP/AD 账号体系，希望 Doris 用户直接复用，无需在 Doris 中重复创建账号 |
| 集中化权限管理 | 通过 LDAP 组管理角色成员，调整 LDAP 组成员即可批量调整 Doris 权限 |
+| LDAP 用户基础权限 | 通过配置为所有 LDAP 认证用户授予相同的 Doris 角色，同时保留 LDAP 组授权 |
| 临时访问 | 仅在 LDAP 中存在的用户，可基于 LDAP 组权限以临时用户身份登录 Doris |
| 加密链路 | 需要 Doris FE 与 LDAP 服务器之间的连接加密（LDAPS） |
@@ -87,6 +90,7 @@ Apache Doris 支持接入第三方 LDAP 服务，将企业内已有的账号体
3. **配置客户端**：MySQL Client 或 JDBC Client 启用明文密码插件，以便发送 LDAP 密码。
4. **（可选）启用 LDAPS**：加密 FE 与 LDAP 之间的链路。
5. **（可选）配置组授权**：在 Doris 中创建与 LDAP 组同名的 `role` 并授权。
+6. **（可选）配置默认角色**：通过 `ldap_default_roles` 为所有 LDAP 认证用户授予基础 Doris 角色。
## 第一步：配置 Doris FE
@@ -113,6 +117,7 @@ ldap_admin_name = uid=admin,o=emr
ldap_user_basedn = ou=people,o=emr
ldap_user_filter = (&(uid={login}))
ldap_group_basedn = ou=group,o=emr
+ldap_default_roles = ldap_readonly,ldap_query_user
```
各配置项含义如下：
@@ -126,6 +131,7 @@ ldap_group_basedn = ou=group,o=emr
| `ldap_user_basedn` | 用户搜索的基准 `dn` |
| `ldap_user_filter` | 用户匹配过滤器，`{login}` 会被替换为登录用户名 |
| `ldap_group_basedn` | 组搜索的基准 `dn`，用于组授权 |
+| `ldap_default_roles` | 可选。为所有 LDAP 认证用户授予的 Doris 角色，多个角色用逗号分隔。这些角色会在 LDAP
组角色之外额外授予 |
:::tip
如需启用 LDAPS（加密连接至 LDAP 服务器），请参阅下文 [LDAPS（加密连接）](#ldaps加密连接) 章节。
@@ -235,8 +241,8 @@ LDAP 验证登录是指通过 LDAP 服务进行密码验证，以补充 Doris
- 临时账户仅对当前连接有效，连接断开后自动销毁。
- Doris 不会为临时用户创建持久化的用户元数据。
-- 临时用户的权限由 LDAP 组授权决定（详见下文"组授权"章节）。
-- 如果临时用户没有对应的组权限，则默认拥有 `information_schema` 的 `select_priv` 权限。
+- 临时用户的权限由 LDAP 组授权和 `ldap_default_roles` 决定（详见下文"组授权"和"LDAP 用户默认角色"章节）。
+- 如果临时用户没有对应的组权限，也没有配置的默认角色，则默认拥有 `information_schema` 的 `select_priv` 权限。
:::
@@ -265,7 +271,7 @@ mysql -hDoris_HOST -PDoris_PORT -ujack -p 123456
- LDAP 用户属性：`uid: jack`，密码：`abcdef`
-使用 LDAP 密码登录，Doris 自动创建临时用户 `jack@'%'` 并登录。临时用户具有基本权限
`DatabasePrivs`：`Select_priv`，断开连接后自动销毁：
+使用 LDAP 密码登录，Doris 自动创建临时用户 `jack@'%'` 并登录。如果存在可用角色，临时用户会获得 LDAP
组角色和配置的默认角色。如果没有匹配角色，则具有基本权限 `DatabasePrivs`：`Select_priv`，断开连接后自动销毁：
```sql
mysql -hDoris_HOST -PDoris_PORT -ujack -p abcdef
@@ -290,6 +296,7 @@ LDAP 组授权是将 LDAP 中的 `group` 映射到 Doris 中的 `role`，从而
- 如果 LDAP 用户的 `dn` 出现在某个 LDAP 组节点的 `member` 属性中，则 Doris 认为该用户属于该组。
- 用户登录时，Doris 自动授予其所属 LDAP 组对应的 `role` 权限。
+- 如果配置了 `ldap_default_roles`，Doris 也会为该用户授予这些默认角色。
- 用户退出登录后，Doris 自动撤销这些 `role` 权限。
:::caution 前提条件
@@ -302,9 +309,9 @@ LDAP 组授权是将 LDAP 中的 `group` 映射到 Doris 中的 `role`，从而
| LDAP 用户 | Doris 用户 | 最终权限 |
| --------- | ---------- | ------------------------------ |
-| 存在 | 存在 | LDAP 组权限 + Doris 用户权限 |
+| 存在 | 存在 | LDAP 组权限 + 配置的默认角色 + Doris 用户权限 |
| 不存在 | 存在 | Doris 用户权限 |
-| 存在 | 不存在 | LDAP 组权限 |
+| 存在 | 不存在 | LDAP 组权限 + 配置的默认角色 |
### 组名映射规则
@@ -331,6 +338,50 @@ member: uid=jack,ou=aidp,dc=domain,dc=com
:::
+## LDAP 用户默认角色
+
+<!-- 知识类型: 配置参数 -->
+<!-- 适用场景: 为所有 LDAP 认证用户授予基础 Doris 权限 -->
+
+`ldap_default_roles` 用于为所有通过 LDAP 认证的用户授予基础 Doris 角色。当所有 LDAP
用户都需要一组相同的基础权限，但不适合在 LDAP 中维护一个包含所有用户的专用组时，可以使用该配置。
+
+`ldap_default_roles` 不会替代 LDAP 组授权。LDAP 用户登录后，Doris 会合并以下权限：
+
+- 用户所属 LDAP 组映射得到的 Doris 角色。
+- `ldap_default_roles` 中配置的 Doris 角色。
+- 如果 Doris 中也存在同名账号，则保留该 Doris 用户已有的权限。
+- 内置的 `ldapDefaultRole`，用于提供 `information_schema` 上的 `select_priv` 权限。
+
+:::caution 前提条件
+`ldap_default_roles` 中列出的角色必须已经存在于 Doris 中。如果配置的角色不存在，Doris 会忽略该角色并记录 warning
日志。
+:::
+
+### 配置默认角色
+
+先创建角色并为角色授权：
+
+```sql
+CREATE ROLE ldap_readonly;
+CREATE ROLE ldap_query_user;
+
+GRANT SELECT_PRIV ON internal.example_db.* TO ROLE 'ldap_readonly';
+GRANT SELECT_PRIV ON internal.example_db.example_table TO ROLE
'ldap_query_user';
+```
+
+在 `fe/conf/ldap.conf` 中配置角色列表：
+
+```text
+ldap_default_roles = ldap_readonly,ldap_query_user
+```
+
+也可以在线修改该配置：
+
+```sql
+ADMIN SET FRONTEND CONFIG ("ldap_default_roles" =
"ldap_readonly,ldap_query_user");
+```
+
+在线修改 `ldap_default_roles` 后，Doris 会自动刷新 LDAP 用户缓存，后续 LDAP 登录即可使用新的默认角色。
+
## LDAPS（加密连接）
<!-- 知识类型: 配置参数 -->
@@ -395,6 +446,8 @@ JAVA_OPTS_FOR_JDK_17 =
"-Djavax.net.ssl.trustStore=/path/to/your/cacerts -Djavax
- 修改了 LDAP 服务中的用户或组信息。
- 修改了 Doris 中 LDAP 用户组对应的 `Role` 权限。
+在线修改 `ldap_default_roles` 时，Doris 会自动刷新 LDAP 用户缓存。仅修改该配置时，不需要额外执行 `refresh
ldap`。
+
可以通过 `refresh ldap` 语句刷新缓存，详细查看
[REFRESH-LDAP](../../../sql-manual/sql-statements/account-management/REFRESH-LDAP)。
## 已知限制
@@ -411,6 +464,8 @@ JAVA_OPTS_FOR_JDK_17 =
"-Djavax.net.ssl.trustStore=/path/to/your/cacerts -Djavax
使用 LDAP 用户登录 Doris 后，执行 `show grants;` 即可查看当前用户的所有角色。其中 `ldapDefaultRole` 是每个
LDAP 用户都拥有的默认角色。
+`ldapDefaultRole` 是 Doris 内置的临时角色，用于提供 `information_schema` 上的 `select_priv`
权限。它与 `ldap_default_roles` 中配置的角色不是同一个概念。
+
### Q: LDAP 用户在 Doris 中的角色比预期少，如何排查？
按以下步骤逐项检查：
@@ -419,6 +474,7 @@ JAVA_OPTS_FOR_JDK_17 =
"-Djavax.net.ssl.trustStore=/path/to/your/cacerts -Djavax
2. 检查预期的 `group` 是否位于 `ldap_group_basedn` 对应的组织结构下。
3. 检查预期的 `group` 是否包含 `member` 属性。
4. 检查预期 `group` 的 `member` 属性中是否包含当前用户的 `dn`。
+5. 如果缺少的是 `ldap_default_roles` 中配置的角色，检查角色名是否拼写正确，以及该角色是否已经在 Doris 中创建。
### Q: LDAPS 连接失败，如何排查？
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
