This is an automated email from the ASF dual-hosted git repository.
CalvinKirs 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 75e8b9f5d0c [docs](auth) Document dual password rotation since 4.2.1
(#4611)
75e8b9f5d0c is described below
commit 75e8b9f5d0c83565c04f53be523c4279c88ea02e
Author: Calvin Kirs <[email protected]>
AuthorDate: Thu Nov 19 10:00:18 2026 +0800
[docs](auth) Document dual password rotation since 4.2.1 (#4611)
Document dual password rotation supported since **4.2.1** in Built-in
Authentication, ALTER USER, SET PASSWORD, and SHOW GRANTS. Update
English and Chinese docs for both dev and 4.x, including permissions,
credential lifetime, rotation examples, metrics, domain-account
behavior, and upgrade/downgrade limits.
**Related implementation PR:**
[apache/doris#66115](https://github.com/apache/doris/pull/66115)
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
3.x and archived versions are excluded because this feature is supported
from 4.2.1.
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [x] Checked by AI
- [ ] Test Cases Built
- [x] Updated required version and language counterparts, or explained
why not
- [x] If only one language changed, confirmed whether source/translation
counterparts need sync (both languages updated)
## Validation
- Reviewed with the doris-docs reference skill, the website AGENTS.md
checklist, and implementation source at apache/doris@51430482b0b.
- Repository documentation governance and SEO checks: no new findings;
12 existing description-length warnings resolved. Existing
title-duplicate and 3.x sync-candidate notices are unchanged.
- Checked links, anchors, JSON frontmatter, version markers, all eight
current/4.x mirror pairs, English/Chinese RETAIN/DISCARD SQL examples,
and git diff --check.
- Documentation only; no new test cases. Full Docusaurus build and SQL
examples on a live cluster were not run.
---
docs/admin-manual/auth/authentication/internal.md | 63 +++++++++++++++++++++-
.../account-management/ALTER-USER.md | 42 +++++++++++++--
.../account-management/SET-PASSWORD.md | 44 +++++++++++++--
.../account-management/SHOW-GRANTS.md | 4 +-
.../admin-manual/auth/authentication/internal.md | 63 +++++++++++++++++++++-
.../account-management/ALTER-USER.md | 41 ++++++++++++--
.../account-management/SET-PASSWORD.md | 42 +++++++++++++--
.../account-management/SHOW-GRANTS.md | 4 +-
.../admin-manual/auth/authentication/internal.md | 63 +++++++++++++++++++++-
.../account-management/ALTER-USER.md | 41 ++++++++++++--
.../account-management/SET-PASSWORD.md | 42 +++++++++++++--
.../account-management/SHOW-GRANTS.md | 4 +-
.../admin-manual/auth/authentication/internal.md | 63 +++++++++++++++++++++-
.../account-management/ALTER-USER.md | 42 +++++++++++++--
.../account-management/SET-PASSWORD.md | 44 +++++++++++++--
.../account-management/SHOW-GRANTS.md | 4 +-
16 files changed, 560 insertions(+), 46 deletions(-)
diff --git a/docs/admin-manual/auth/authentication/internal.md
b/docs/admin-manual/auth/authentication/internal.md
index d12c1a092b6..7997092142d 100644
--- a/docs/admin-manual/auth/authentication/internal.md
+++ b/docs/admin-manual/auth/authentication/internal.md
@@ -2,7 +2,7 @@
{
"title": "Built-in Authentication",
"language": "en",
- "description": "Detailed guide to the Apache Doris built-in authentication
mechanism: composition of the user_identity, password policies (history,
expiration, login-failure lockout, strength validation), IP matching priority,
simulating a blacklist with a whitelist, and common troubleshooting."
+ "description": "Manage Doris users, password policies, dual-password
rotation, identity matching, and authentication troubleshooting."
}
---
@@ -17,6 +17,7 @@ Apache Doris provides a built-in user authentication
mechanism. Administrators c
| --- | --- |
| Create an account, drop an account, reset a password | [Core
Concepts](#core-concepts), [Common Operational
Commands](#common-operational-commands) |
| Configure enterprise-grade password policies (expiration / history /
strength / lockout) | [Password Policies](#password-policies) |
+| Rotate an application password while clients migrate | [Dual
Passwords](#dual-passwords) |
| The same user name matches multiple `user_identity` values and login is
rejected | [User Identity Matching Priority](#user-identity-matching-priority) |
| Block a specific IP from logging in (simulate a blacklist) | [Simulating a
Blacklist with a Whitelist](#simulating-a-blacklist-with-a-whitelist) |
| Forgot the root password, or `current_user()` does not match `user()` |
[FAQ](#faq) |
@@ -125,6 +126,66 @@ SHOW PROC "/auth/'root'@'%'";
SHOW PROC "/auth/'user1'@'127.0.0.1'";
```
+## Dual Passwords
+
+<!-- Knowledge type: Operational procedure + Rules -->
+<!-- Applicable scenarios: Application credential rotation -->
+
+**Supported since 4.2.1.** Built-in password authentication can keep one
primary password and one retained secondary password for the same account. Use
this overlap to migrate clients to a new password without rejecting clients
that still use the previous one. A secondary password is absent by default and
is created only with `RETAIN CURRENT PASSWORD`. These changes affect subsequent
authentications and do not disconnect existing sessions.
+
+### Prerequisites
+
+- Upgrade every FE to 4.2.1 or later before using these clauses.
+- Execute the rotation as an administrator with global `GRANT_PRIV` or
`ADMIN_PRIV`. RETAIN requires this privilege even on your own account; an
ordinary self-service SET PASSWORD without RETAIN does not.
+- Use an account with a built-in, nonempty primary password. LDAP and
authentication integrations manage their own credentials.
+
+### Rotate a Password
+
+1. Create an example account, then set a new password while retaining its
current one. For an existing account, run only the ALTER USER statement.
+
+ ```sql
+ CREATE USER 'app_user'@'%' IDENTIFIED BY 'OldPwd_2026!';
+ ALTER USER 'app_user'@'%' IDENTIFIED BY 'NewPwd_2026!' RETAIN CURRENT
PASSWORD;
+ ```
+
+ Both `OldPwd_2026!` and `NewPwd_2026!` can authenticate. An equivalent
retaining change is `SET PASSWORD FOR 'app_user'@'%' = PASSWORD('NewPwd_2026!')
RETAIN CURRENT PASSWORD`; use it instead of the ALTER statement, not after it.
+
+2. Update every client to use `NewPwd_2026!`. Check the account's
retained-password state:
+
+ ```sql
+ SHOW GRANTS FOR 'app_user'@'%';
+ ```
+
+ The `Password` column shows `Yes (dual)`. `SHOW ALL GRANTS` and `SHOW PROC
'/auth'` expose the same marker. Each FE's
`doris_fe_secondary_password_auth_total` metric counts successful
authentications using the secondary password, across all accounts, after
account-policy checks; observe its increments rather than waiting for this
cumulative counter to return to zero.
+
+3. After all clients have migrated, revoke the secondary password:
+
+ ```sql
+ ALTER USER 'app_user'@'%' DISCARD OLD PASSWORD;
+ ```
+
+ Only `NewPwd_2026!` can authenticate, and the `Password` column returns to
`Yes`. Repeating DISCARD when no secondary exists has no effect.
+
+### Password Lifetime and Policy Rules
+
+| Operation | Result |
+| --- | --- |
+| Nonempty new password with RETAIN | Previous primary becomes the only
secondary; any earlier secondary is replaced. |
+| Nonempty change without RETAIN | Existing secondary remains valid. Replacing
the primary alone does not revoke it. |
+| Empty new password | Both slots are cleared, even with RETAIN. |
+| RETAIN with an empty current primary | Rejected. |
+| DISCARD OLD PASSWORD | Only the secondary is removed. Password history and
the password expiration clock are unchanged. |
+
+Both passwords are subject to the account's lock and expiration policies. A
retaining change is still a password change and follows password
strength/history rules and updates the expiration clock. Binding, unbinding, or
changing an authentication integration clears any retained secondary; RETAIN is
rejected across these transitions. DISCARD is a standalone ALTER USER operation
and cannot be combined with a password change, policy change, or comment.
+
+### Domain Accounts and Version Changes
+
+For a domain account, DISCARD clears the persistent domain account first.
Resolved-IP entries stop accepting their retained copy at the next
domain-resolver refresh. The normal interval is 10 seconds, but this is not a
strict revocation-time bound.
+
+During a rolling upgrade, an older FE authenticates against the primary only
and cannot parse the new clauses. Wait until every FE has been upgraded before
starting dual-password rotation. Downgrading after using the feature loses the
retained secondary; only the primary survives, and upgrading again does not
restore the old secondary.
+
+For the full statement reference, see [ALTER
USER](../../../sql-manual/sql-statements/account-management/ALTER-USER) and
[SET
PASSWORD](../../../sql-manual/sql-statements/account-management/SET-PASSWORD).
+
## User Identity Matching Priority
<!-- Knowledge type: Rule description -->
diff --git a/docs/sql-manual/sql-statements/account-management/ALTER-USER.md
b/docs/sql-manual/sql-statements/account-management/ALTER-USER.md
index f6be0eb66a3..6633c747d4f 100644
--- a/docs/sql-manual/sql-statements/account-management/ALTER-USER.md
+++ b/docs/sql-manual/sql-statements/account-management/ALTER-USER.md
@@ -2,7 +2,7 @@
{
"title": "ALTER USER",
"language": "en",
- "description": "The ALTER USER statement is used to modify a user's
account attributes, including passwords, and password policies, etc."
+ "description": "The ALTER USER statement modifies account passwords and
policies, including dual-password rotation."
}
---
@@ -10,10 +10,13 @@
The `ALTER USER` statement is used to modify a user's account attributes,
including passwords, and password policies, etc.
+Since 4.2.1, Doris supports dual passwords for built-in password
authentication with `RETAIN CURRENT PASSWORD` and `DISCARD OLD PASSWORD`.
+
## Syntax
```sql
-ALTER USER [IF EXISTS] <user_identity> [IDENTIFIED BY <password>]
+ALTER USER [IF EXISTS] <user_identity>
+ [IDENTIFIED BY <password> [RETAIN CURRENT PASSWORD] | DISCARD OLD PASSWORD]
[<password_policy>]
[<comment>]
@@ -67,13 +70,21 @@ password_policy:
>Specify the user comment.
+**4. `RETAIN CURRENT PASSWORD` (since 4.2.1)**
+
+> Use with `IDENTIFIED BY` to make the previous primary password the retained
secondary password. The new password becomes the primary; either password can
authenticate. Any earlier secondary password is replaced.
+
+**5. `DISCARD OLD PASSWORD` (since 4.2.1)**
+
+> Remove the retained secondary password, leaving the primary unchanged. This
is a standalone operation: do not combine it with a password change, password
policy, comment, or other account operation. If no secondary password exists,
it has no effect.
+
## Access Control Requirements
The user executing this SQL command must have at least the following
privileges:
| Privilege | Object | Notes |
|:--------------|:----------|:------|
-| ADMIN_PRIV | USER or ROLE | This operation can only be performed by
users or roles with ADMIN_PRIV permissions |
+| GRANT_PRIV or ADMIN_PRIV | Global | Required for ALTER USER, including
RETAIN CURRENT PASSWORD and DISCARD OLD PASSWORD. |
## Usage Notes
@@ -82,12 +93,21 @@ Since 4.1.5, only `'root'@'%'` is the special root
identity. An identity such as
1. Starting from version 2.0, this command no longer supports modifying user
roles. Please use [GRANT](./GRANT-TO.md) and [REVOKE](./REVOKE-FROM.md) for
related operations.
2. In an ALTER USER command, only one of the following account attributes can
be modified at the same time:
-- Change password
+- Change password, optionally with RETAIN CURRENT PASSWORD
+- Discard the retained secondary password
- Modify `PASSWORD_HISTORY`
- Modify `PASSWORD_EXPIRE`
- Modify `FAILED_LOGIN_ATTEMPTS` and `PASSWORD_LOCK_TIME`
- Unlock users
+### Dual Passwords (Since 4.2.1)
+
+- `RETAIN CURRENT PASSWORD` requires a nonempty current primary password and a
password change. An empty new password clears both password slots, even with
RETAIN.
+- An ordinary nonempty password change without RETAIN preserves an existing
secondary password; it does not revoke that credential.
+- Account lock and password expiration checks apply to both passwords. DISCARD
does not change password history or restart the password expiration clock.
+
+See [Dual
Passwords](../../../admin-manual/auth/authentication/internal#dual-passwords)
for the rotation procedure, observability, domain-account behavior, and upgrade
restrictions. These clauses manage built-in passwords, not credentials held by
LDAP or an external authentication integration.
+
## Example
Setup — create user `jack` so the examples below have a target user:
@@ -119,3 +139,17 @@ ALTER USER jack@'%' ACCOUNT_UNLOCK
```sql
ALTER USER jack@'%' COMMENT "this is my first user"
```
+
+- Rotate the password while keeping the previous password usable (since 4.2.1)
+
+```sql
+ALTER USER jack@'%' IDENTIFIED BY 'NewPwd_2026!' RETAIN CURRENT PASSWORD;
+```
+
+Both the previous password and `NewPwd_2026!` can authenticate. After all
clients have switched to the new password, discard the retained one:
+
+```sql
+ALTER USER jack@'%' DISCARD OLD PASSWORD;
+```
+
+Only `NewPwd_2026!` can authenticate afterward.
diff --git a/docs/sql-manual/sql-statements/account-management/SET-PASSWORD.md
b/docs/sql-manual/sql-statements/account-management/SET-PASSWORD.md
index 6c099258e6e..7f0a3a29588 100644
--- a/docs/sql-manual/sql-statements/account-management/SET-PASSWORD.md
+++ b/docs/sql-manual/sql-statements/account-management/SET-PASSWORD.md
@@ -2,7 +2,7 @@
{
"title": "SET PASSWORD",
"language": "en",
- "description": "The SET PASSWORD statement is used to modify a user's
login password."
+ "description": "Change a Doris login password and optionally retain the
current password during rotation."
}
---
@@ -10,11 +10,14 @@
The `SET PASSWORD` statement is used to modify a user's login password.
+Since 4.2.1, Doris supports dual passwords for built-in password
authentication with `RETAIN CURRENT PASSWORD` and `DISCARD OLD PASSWORD`.
+
## Syntax
```sql
SET PASSWORD [FOR <user_identity>] =
- [PASSWORD(<plain_password>)]|[<hashed_password>]
+ { PASSWORD(<plain_password>) | <hashed_password> }
+ [RETAIN CURRENT PASSWORD]
```
## Required Parameters
@@ -31,7 +34,11 @@ SET PASSWORD [FOR <user_identity>] =
**1. `<user_identity>`**
-> The user_identity here must exactly match the user_identity specified when
creating a user with CREATE USER, otherwise an error will be reported that the
user does not exist. If user_identity is not specified, the current user is
'username'@'ip', which may not match any user_identity. Current users can be
viewed through SHOW GRANTS.
+> With `FOR`, specify exactly the account identity created by `CREATE USER`,
including its host part. Without `FOR`, Doris uses the authenticated account
returned by `CURRENT_USER()`, not the client IP identity returned by `USER()`.
View the current account with `SHOW GRANTS`.
+
+**2. `RETAIN CURRENT PASSWORD` (since 4.2.1)**
+
+> Retain the previous primary password as the secondary and install the
specified new primary password. Either password can authenticate; any earlier
secondary is replaced. Requires global `GRANT_PRIV` or `ADMIN_PRIV`, including
when changing your own password.
## Access Control Requirements
@@ -39,7 +46,8 @@ The user executing this SQL command must have at least the
following privileges:
| Privilege | Object | Notes |
|:--------------|:----------|:------|
-| ADMIN_PRIV | USER or ROLE | User or Role has the ADMIN_PRIV privilege
to modify all user's password, otherwise only the current user's password can
be modified. |
+| None | Current user | An ordinary change of your own password without RETAIN
requires no additional privilege. |
+| GRANT_PRIV or ADMIN_PRIV | Global | Required to change another user's
password or use RETAIN CURRENT PASSWORD, including on your own account. |
## Usage Notes
@@ -47,6 +55,15 @@ Since 4.1.5, only `'root'@'%'` is the special root identity.
An identity such as
- If the `FOR user_identity` field does not exist, then change the current
user's password.
+### Dual Passwords (Since 4.2.1)
+
+- Without RETAIN, an ordinary nonempty password change preserves any existing
secondary password.
+- RETAIN fails if the current primary password is empty. An empty new password
clears both slots, including when RETAIN is specified.
+- For plaintext, use `PASSWORD('<new_password>')`; a bare string must contain
an already hashed password.
+- To revoke the secondary, use `ALTER USER ... DISCARD OLD PASSWORD`. SET
PASSWORD has no DISCARD clause.
+
+See [Dual
Passwords](../../../admin-manual/auth/authentication/internal#dual-passwords)
for the complete workflow and upgrade restrictions. These clauses apply to
built-in passwords.
+
## Example
- Modify the current user's password
@@ -61,4 +78,21 @@ SET PASSWORD = '*6BB4837EB74329105EE4568DDA7DC67ED2CA2AD9'
```sql
SET PASSWORD FOR 'jack'@'192.%' = PASSWORD('123456')
SET PASSWORD FOR 'jack'@['domain'] =
'*6BB4837EB74329105EE4568DDA7DC67ED2CA2AD9'
-```
\ No newline at end of file
+```
+
+- Rotate an account with an overlap period (since 4.2.1)
+
+Run as an administrator with global `GRANT_PRIV` or `ADMIN_PRIV`:
+
+```sql
+CREATE USER 'rotation_user'@'%' IDENTIFIED BY 'OldPwd_2026!';
+SET PASSWORD FOR 'rotation_user'@'%' = PASSWORD('NewPwd_2026!') RETAIN CURRENT
PASSWORD;
+```
+
+Both `OldPwd_2026!` and `NewPwd_2026!` authenticate. After migrating clients,
remove the old credential:
+
+```sql
+ALTER USER 'rotation_user'@'%' DISCARD OLD PASSWORD;
+```
+
+Only `NewPwd_2026!` authenticates afterward.
diff --git a/docs/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
b/docs/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
index 911c675b55e..67bfe7553d7 100644
--- a/docs/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
+++ b/docs/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
@@ -2,7 +2,7 @@
{
"title": "SHOW GRANTS",
"language": "en",
- "description": "This statement is used to view user permissions."
+ "description": "View Apache Doris user privileges and identify accounts
with retained secondary passwords using the SHOW GRANTS output."
}
---
@@ -32,7 +32,7 @@ Whether to view the permissions of all users.
| -- | -- |
| UserIdentity | User identity |
| Comment | Comment |
- | Password | Whether the password is set |
+ | Password | `No` if no local password is available; `Yes` for a primary
password only; `Yes (dual)` when a retained secondary also exists (since
4.2.1). |
| Roles | Roles |
| GlobalPrivs | Global privileges |
| CatalogPrivs | Catalog privileges |
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/authentication/internal.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/authentication/internal.md
index eaae4b9df44..53b4c2f4a02 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/authentication/internal.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/auth/authentication/internal.md
@@ -2,7 +2,7 @@
{
"title": "内置认证",
"language": "zh-CN",
- "description": "Apache Doris 内置认证机制详解:用户标识 user_identity
组成、密码策略(历史密码、过期、登录失败锁定、强度校验)、IP 匹配优先级、黑白名单模拟与常见问题排查。"
+ "description": "介绍 Apache Doris 内置认证、用户身份匹配和密码策略,提供自 4.2.1
起支持的双密码轮换步骤、权限要求、次密码监控与撤销方法,并说明域名账号刷新、滚动升级和降级的使用限制。"
}
---
@@ -17,6 +17,7 @@ Apache Doris 提供内置的用户认证机制,管理员通过 SQL 命令创
| --- | --- |
| 新建账号、删除账号、重置密码 | [核心概念](#核心概念)、[常用运维命令](#常用运维命令) |
| 配置企业级密码策略(过期 / 历史 / 强度 / 锁定) | [密码策略](#密码策略) |
+| 应用切换新密码期间保留旧密码登录能力 | [双密码](#双密码) |
| 同一用户名匹配多个 `user_identity`,登录被拒 | [用户身份匹配优先级](#用户身份匹配优先级) |
| 限制特定 IP 不能登录(模拟黑名单) | [使用白名单模拟黑名单](#使用白名单模拟黑名单) |
| 忘记 root 密码、`current_user()` 与 `user()` 不一致 | [常见问题](#常见问题) |
@@ -125,6 +126,66 @@ SHOW PROC "/auth/'root'@'%'";
SHOW PROC "/auth/'user1'@'127.0.0.1'";
```
+## 双密码
+
+<!-- 知识类型: 操作流程 + 规则说明 -->
+<!-- 适用场景: 应用凭据轮换 -->
+
+**自 4.2.1 起支持。**
内置密码认证允许同一账号同时拥有一个主密码和一个保留的次密码。利用这段重叠期,可以逐步将客户端切换到新密码,同时允许尚未迁移的客户端继续使用旧密码。默认不存在次密码,只有指定
`RETAIN CURRENT PASSWORD` 才会创建。这些操作影响后续认证,不会断开已建立的会话。
+
+### 前提条件
+
+- 使用这些子句前,所有 FE 均须升级到 4.2.1 或更高版本。
+- 由具有全局 `GRANT_PRIV` 或 `ADMIN_PRIV` 的管理员执行轮换。即使操作自己的账号,RETAIN 也需要此权限;不带 RETAIN
的普通自助 SET PASSWORD 不需要额外权限。
+- 目标账号使用内置密码认证,且当前主密码非空。LDAP 和认证集成自行管理其凭据。
+
+### 轮换密码
+
+1. 创建示例账号,然后设置新密码并保留当前密码。已有账号只需执行 ALTER USER 语句。
+
+ ```sql
+ CREATE USER 'app_user'@'%' IDENTIFIED BY 'OldPwd_2026!';
+ ALTER USER 'app_user'@'%' IDENTIFIED BY 'NewPwd_2026!' RETAIN CURRENT
PASSWORD;
+ ```
+
+ 此时 `OldPwd_2026!` 和 `NewPwd_2026!` 均可登录。也可以使用 `SET PASSWORD FOR
'app_user'@'%' = PASSWORD('NewPwd_2026!') RETAIN CURRENT PASSWORD` 替代上述 ALTER
语句,两者不要连续执行。
+
+2. 将所有客户端改为使用 `NewPwd_2026!`,并查看账号是否仍保留次密码:
+
+ ```sql
+ SHOW GRANTS FOR 'app_user'@'%';
+ ```
+
+ `Password` 列显示 `Yes (dual)`,`SHOW ALL GRANTS` 和 `SHOW PROC '/auth'`
也显示相同标记。每个 FE 的 `doris_fe_secondary_password_auth_total`
指标统计通过账号策略检查后、使用次密码认证成功的次数;这是 FE 级、跨账号的累计计数,应观察增量,而不是等待归零。
+
+3. 所有客户端迁移完成后,撤销次密码:
+
+ ```sql
+ ALTER USER 'app_user'@'%' DISCARD OLD PASSWORD;
+ ```
+
+ 此后只有 `NewPwd_2026!` 可以登录,`Password` 列恢复为 `Yes`。没有次密码时,重复执行 DISCARD 不会产生变化。
+
+### 密码生命周期与策略
+
+| 操作 | 结果 |
+| --- | --- |
+| 设置非空新密码并指定 RETAIN | 原主密码成为唯一的次密码,更早的次密码被替换。 |
+| 设置非空新密码,不指定 RETAIN | 已有次密码继续有效,仅替换主密码不会撤销它。 |
+| 新密码为空 | 两份密码均被清除,即使指定了 RETAIN。 |
+| 当前主密码为空时指定 RETAIN | 拒绝执行。 |
+| DISCARD OLD PASSWORD | 仅删除次密码,不改变密码历史或密码过期时间。 |
+
+两份密码均受账号锁定和密码过期策略约束。指定 RETAIN
仍属于修改密码,需要满足密码强度和历史策略,并更新密码过期计时。绑定、解绑或切换认证集成会清除保留的次密码,不允许跨这些转换使用 RETAIN。DISCARD
是独立的 ALTER USER 操作,不能与修改密码、策略或注释组合使用。
+
+### 域名账号与版本变更
+
+对域名账号执行 DISCARD 时,先清除持久化域名账号中的次密码,已解析的 IP 记录要等下一次域名解析刷新后才会停止接受其保留副本。正常刷新间隔为 10
秒,但不是严格的撤销时延上限。
+
+滚动升级期间,旧 FE 只接受主密码,也无法解析新增子句。开始双密码轮换前,应完成所有 FE
的升级。使用此功能后降级会丢失保留的次密码,仅主密码得以保留;重新升级不会恢复原来的次密码。
+
+完整语句参考见 [ALTER
USER](../../../sql-manual/sql-statements/account-management/ALTER-USER) 和 [SET
PASSWORD](../../../sql-manual/sql-statements/account-management/SET-PASSWORD)。
+
## 用户身份匹配优先级
<!-- 知识类型: 规则说明 -->
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/ALTER-USER.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/ALTER-USER.md
index 0b4252cc30e..f320212c294 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/ALTER-USER.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/ALTER-USER.md
@@ -2,7 +2,7 @@
{
"title": "ALTER USER",
"language": "zh-CN",
- "description": "ALTER USER 语句用于修改一个用户的账户属性,包括密码、和密码策略等"
+ "description": "介绍 Apache Doris ALTER USER 的语法、权限和密码策略,以及自 4.2.1 起通过
RETAIN CURRENT PASSWORD 保留旧密码和 DISCARD OLD PASSWORD 撤销次密码的轮换流程。"
}
---
@@ -10,10 +10,13 @@
ALTER USER 语句用于修改一个用户的账户属性,包括密码、和密码策略等
+自 4.2.1 起,Doris 内置密码认证支持通过 `RETAIN CURRENT PASSWORD` 和 `DISCARD OLD PASSWORD`
管理双密码。
+
## 语法
```sql
-ALTER USER [IF EXISTS] <user_identity> [IDENTIFIED BY <password>]
+ALTER USER [IF EXISTS] <user_identity>
+ [IDENTIFIED BY <password> [RETAIN CURRENT PASSWORD] | DISCARD OLD PASSWORD]
[<password_policy>]
[<comment>]
@@ -68,13 +71,21 @@ password_policy:
> 指定用户注释
+**4. `RETAIN CURRENT PASSWORD`(自 4.2.1 起支持)**
+
+> 与 `IDENTIFIED BY` 一起使用,将原主密码保留为次密码,新密码成为主密码。主密码和次密码均可用于登录;更早保留的次密码会被替换。
+
+**5. `DISCARD OLD PASSWORD`(自 4.2.1 起支持)**
+
+> 删除保留的次密码,主密码保持不变。这是独立操作,不能与修改密码、密码策略、注释或其他账号操作组合使用。不存在次密码时,执行后没有变化。
+
## 权限控制
执行此 SQL 命令的用户必须至少具有以下权限:
| 权限 | 对象 | 说明 |
|:------------|:------------|:--------------|
-| ADMIN_PRIV | 用户(User)或 角色(Role) | 用户或者角色拥有 ADMIN_PRIV 权限才能进行此操作 |
+| GRANT_PRIV 或 ADMIN_PRIV | 全局 | 执行 ALTER USER,包括 RETAIN CURRENT PASSWORD 和
DISCARD OLD PASSWORD,均需要此权限。 |
## 注意事项
@@ -83,12 +94,21 @@ password_policy:
1. 从 2.0
版本开始,此命令不再支持修改用户角色,相关操作请使用[GRANT](./GRANT-TO.md)和[REVOKE](./REVOKE-FROM.md)。
2. 在一个 ALTER USER 命令中,只能同时对以下账户属性中的一项进行修改:
-- 修改密码
+- 修改密码,可附带 RETAIN CURRENT PASSWORD
+- 删除保留的次密码
- 修改 PASSWORD_HISTORY
- 修改 PASSWORD_EXPIRE
- 修改 FAILED_LOGIN_ATTEMPTS 和 PASSWORD_LOCK_TIME
- 解锁用户
+### 双密码(自 4.2.1 起支持)
+
+- `RETAIN CURRENT PASSWORD` 必须伴随修改密码,且当前主密码非空。新密码为空时,两份密码都会被清除,即使指定了 RETAIN。
+- 普通的非空改密语句如果不带 RETAIN,已有次密码仍然有效,不会因此被撤销。
+- 主密码和次密码均受账号锁定和密码过期策略约束。DISCARD 不改变密码历史,也不重新计算密码过期时间。
+
+完整轮换步骤、可观测性、域名账号行为和升级限制见[双密码](../../../admin-manual/auth/authentication/internal#双密码)。这些子句管理内置密码,不管理
LDAP 或外部认证集成持有的凭据。
+
## 示例
准备:先创建用户 `jack`,作为下面示例的目标用户:
@@ -121,3 +141,16 @@ ALTER USER jack@'%' ACCOUNT_UNLOCK
ALTER USER jack@'%' COMMENT "this is my first user"
```
+- 修改密码并保留旧密码(自 4.2.1 起支持)
+
+```sql
+ALTER USER jack@'%' IDENTIFIED BY 'NewPwd_2026!' RETAIN CURRENT PASSWORD;
+```
+
+原密码和 `NewPwd_2026!` 均可登录。所有客户端切换到新密码后,删除保留的旧密码:
+
+```sql
+ALTER USER jack@'%' DISCARD OLD PASSWORD;
+```
+
+此后只有 `NewPwd_2026!` 可以登录。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/SET-PASSWORD.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/SET-PASSWORD.md
index 5e0df28bdd7..3ef61097d0e 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/SET-PASSWORD.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/SET-PASSWORD.md
@@ -2,7 +2,7 @@
{
"title": "SET PASSWORD",
"language": "zh-CN",
- "description": "SET PASSWORD 语句用于修改一个用户的登录密码。"
+ "description": "介绍 Apache Doris SET PASSWORD 的语法、明文与哈希密码用法及权限要求,以及自 4.2.1
起通过 RETAIN CURRENT PASSWORD 保留旧密码的双密码轮换流程。"
}
---
@@ -10,11 +10,14 @@
SET PASSWORD 语句用于修改一个用户的登录密码。
+自 4.2.1 起,Doris 内置密码认证支持通过 `RETAIN CURRENT PASSWORD` 和 `DISCARD OLD PASSWORD`
管理双密码。
+
## 语法
```sql
SET PASSWORD [FOR <user_identity>] =
- [ PASSWORD(<plain_password>)] | [<hashed_password> ]
+ { PASSWORD(<plain_password>) | <hashed_password> }
+ [RETAIN CURRENT PASSWORD]
```
## 必选参数
@@ -31,7 +34,11 @@ SET PASSWORD [FOR <user_identity>] =
**1. `<user_identity>`**
-> 必须完全匹配在使用 CREATE USER 创建用户时指定的 user_identity,否则会报错用户不存在。如果不指定
user_identity,则当前用户为 'username'@'ip',这个当前用户,可能无法匹配任何 user_identity。可以通过 SHOW
GRANTS 查看当前用户。
+> 显式指定 `FOR` 时,必须与 `CREATE USER` 创建的账号身份完全匹配,包括 host 部分。省略 `FOR` 时,Doris 使用
`CURRENT_USER()` 返回的当前认证账号,而不是 `USER()` 返回的客户端 IP 身份。可通过 `SHOW GRANTS` 查看当前账号。
+
+**2. `RETAIN CURRENT PASSWORD`(自 4.2.1 起支持)**
+
+> 将原主密码保留为次密码,并将指定的新密码设为主密码,两者均可登录;更早保留的次密码会被替换。需要全局 `GRANT_PRIV` 或
`ADMIN_PRIV`,即使修改的是自己的密码。
## 权限控制
@@ -39,7 +46,8 @@ SET PASSWORD [FOR <user_identity>] =
| 权限 | 对象 | 说明 |
|:------------|:------------|:--------------|
-| ADMIN_PRIV | 用户(User)或 角色(Role) | 用户或者角色拥有 ADMIN_PRIV
权限才能修改所有用户的密码,否则只能修改当前用户的密码 |
+| 无额外权限 | 当前用户 | 不带 RETAIN 的普通自助改密不需要额外权限。 |
+| GRANT_PRIV 或 ADMIN_PRIV | 全局 | 修改其他用户的密码,或使用 RETAIN CURRENT
PASSWORD(包括自己的账号),均需要此权限。 |
## 注意事项
@@ -47,6 +55,15 @@ SET PASSWORD [FOR <user_identity>] =
- 如果 `FOR user_identity` 字段不存在,那么修改当前用户的密码。
+### 双密码(自 4.2.1 起支持)
+
+- 普通的非空改密语句如果不带 RETAIN,已有次密码保持不变。
+- 当前主密码为空时,RETAIN 会失败。新密码为空时,即使指定 RETAIN,也会清除两份密码。
+- 设置明文密码时使用 `PASSWORD('<new_password>')`;直接填写字符串时必须使用已经计算好的密码哈希。
+- 撤销次密码需要使用 `ALTER USER ... DISCARD OLD PASSWORD`,SET PASSWORD 没有 DISCARD 子句。
+
+完整流程和升级限制见[双密码](../../../admin-manual/auth/authentication/internal#双密码)。这些子句适用于内置密码认证。
+
## 示例
- 修改当前用户的密码
@@ -61,3 +78,20 @@ SET PASSWORD = '*6BB4837EB74329105EE4568DDA7DC67ED2CA2AD9'
SET PASSWORD FOR 'jack'@'192.%' = PASSWORD('123456')
SET PASSWORD FOR 'jack'@['domain'] =
'*6BB4837EB74329105EE4568DDA7DC67ED2CA2AD9'
```
+
+- 在轮换期间同时保留新旧密码(自 4.2.1 起支持)
+
+由具有全局 `GRANT_PRIV` 或 `ADMIN_PRIV` 的管理员执行:
+
+```sql
+CREATE USER 'rotation_user'@'%' IDENTIFIED BY 'OldPwd_2026!';
+SET PASSWORD FOR 'rotation_user'@'%' = PASSWORD('NewPwd_2026!') RETAIN CURRENT
PASSWORD;
+```
+
+`OldPwd_2026!` 和 `NewPwd_2026!` 均可登录。客户端迁移完成后,撤销旧凭据:
+
+```sql
+ALTER USER 'rotation_user'@'%' DISCARD OLD PASSWORD;
+```
+
+此后只有 `NewPwd_2026!` 可以登录。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
index ae338c293d3..d066737eaf3 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
@@ -2,7 +2,7 @@
{
"title": "SHOW GRANTS",
"language": "zh-CN",
- "description": "该语句用于查看用户权限。"
+ "description": "介绍 Apache Doris SHOW GRANTS 查看用户权限的语法、返回列和权限要求,以及自 4.2.1
起通过 Password 列的 Yes (dual) 标记识别保留次密码的账号。"
}
---
@@ -32,7 +32,7 @@ SHOW [ALL] GRANTS [FOR <user_identity>];
| -- | -- |
| UserIdentity | 用户标识 |
| Comment | 注释 |
- | Password | 是否设置密码 |
+ | Password | `No` 表示没有可用的本地密码;`Yes` 表示仅有主密码;`Yes (dual)` 表示同时保留次密码(自 4.2.1
起支持)。 |
| Roles | 拥有的角色 |
| GlobalPrivs | 拥有的全局权限 |
| CatalogPrivs | 拥有的 catalog 权限 |
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/auth/authentication/internal.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/auth/authentication/internal.md
index eaae4b9df44..53b4c2f4a02 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/auth/authentication/internal.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/auth/authentication/internal.md
@@ -2,7 +2,7 @@
{
"title": "内置认证",
"language": "zh-CN",
- "description": "Apache Doris 内置认证机制详解:用户标识 user_identity
组成、密码策略(历史密码、过期、登录失败锁定、强度校验)、IP 匹配优先级、黑白名单模拟与常见问题排查。"
+ "description": "介绍 Apache Doris 内置认证、用户身份匹配和密码策略,提供自 4.2.1
起支持的双密码轮换步骤、权限要求、次密码监控与撤销方法,并说明域名账号刷新、滚动升级和降级的使用限制。"
}
---
@@ -17,6 +17,7 @@ Apache Doris 提供内置的用户认证机制,管理员通过 SQL 命令创
| --- | --- |
| 新建账号、删除账号、重置密码 | [核心概念](#核心概念)、[常用运维命令](#常用运维命令) |
| 配置企业级密码策略(过期 / 历史 / 强度 / 锁定) | [密码策略](#密码策略) |
+| 应用切换新密码期间保留旧密码登录能力 | [双密码](#双密码) |
| 同一用户名匹配多个 `user_identity`,登录被拒 | [用户身份匹配优先级](#用户身份匹配优先级) |
| 限制特定 IP 不能登录(模拟黑名单) | [使用白名单模拟黑名单](#使用白名单模拟黑名单) |
| 忘记 root 密码、`current_user()` 与 `user()` 不一致 | [常见问题](#常见问题) |
@@ -125,6 +126,66 @@ SHOW PROC "/auth/'root'@'%'";
SHOW PROC "/auth/'user1'@'127.0.0.1'";
```
+## 双密码
+
+<!-- 知识类型: 操作流程 + 规则说明 -->
+<!-- 适用场景: 应用凭据轮换 -->
+
+**自 4.2.1 起支持。**
内置密码认证允许同一账号同时拥有一个主密码和一个保留的次密码。利用这段重叠期,可以逐步将客户端切换到新密码,同时允许尚未迁移的客户端继续使用旧密码。默认不存在次密码,只有指定
`RETAIN CURRENT PASSWORD` 才会创建。这些操作影响后续认证,不会断开已建立的会话。
+
+### 前提条件
+
+- 使用这些子句前,所有 FE 均须升级到 4.2.1 或更高版本。
+- 由具有全局 `GRANT_PRIV` 或 `ADMIN_PRIV` 的管理员执行轮换。即使操作自己的账号,RETAIN 也需要此权限;不带 RETAIN
的普通自助 SET PASSWORD 不需要额外权限。
+- 目标账号使用内置密码认证,且当前主密码非空。LDAP 和认证集成自行管理其凭据。
+
+### 轮换密码
+
+1. 创建示例账号,然后设置新密码并保留当前密码。已有账号只需执行 ALTER USER 语句。
+
+ ```sql
+ CREATE USER 'app_user'@'%' IDENTIFIED BY 'OldPwd_2026!';
+ ALTER USER 'app_user'@'%' IDENTIFIED BY 'NewPwd_2026!' RETAIN CURRENT
PASSWORD;
+ ```
+
+ 此时 `OldPwd_2026!` 和 `NewPwd_2026!` 均可登录。也可以使用 `SET PASSWORD FOR
'app_user'@'%' = PASSWORD('NewPwd_2026!') RETAIN CURRENT PASSWORD` 替代上述 ALTER
语句,两者不要连续执行。
+
+2. 将所有客户端改为使用 `NewPwd_2026!`,并查看账号是否仍保留次密码:
+
+ ```sql
+ SHOW GRANTS FOR 'app_user'@'%';
+ ```
+
+ `Password` 列显示 `Yes (dual)`,`SHOW ALL GRANTS` 和 `SHOW PROC '/auth'`
也显示相同标记。每个 FE 的 `doris_fe_secondary_password_auth_total`
指标统计通过账号策略检查后、使用次密码认证成功的次数;这是 FE 级、跨账号的累计计数,应观察增量,而不是等待归零。
+
+3. 所有客户端迁移完成后,撤销次密码:
+
+ ```sql
+ ALTER USER 'app_user'@'%' DISCARD OLD PASSWORD;
+ ```
+
+ 此后只有 `NewPwd_2026!` 可以登录,`Password` 列恢复为 `Yes`。没有次密码时,重复执行 DISCARD 不会产生变化。
+
+### 密码生命周期与策略
+
+| 操作 | 结果 |
+| --- | --- |
+| 设置非空新密码并指定 RETAIN | 原主密码成为唯一的次密码,更早的次密码被替换。 |
+| 设置非空新密码,不指定 RETAIN | 已有次密码继续有效,仅替换主密码不会撤销它。 |
+| 新密码为空 | 两份密码均被清除,即使指定了 RETAIN。 |
+| 当前主密码为空时指定 RETAIN | 拒绝执行。 |
+| DISCARD OLD PASSWORD | 仅删除次密码,不改变密码历史或密码过期时间。 |
+
+两份密码均受账号锁定和密码过期策略约束。指定 RETAIN
仍属于修改密码,需要满足密码强度和历史策略,并更新密码过期计时。绑定、解绑或切换认证集成会清除保留的次密码,不允许跨这些转换使用 RETAIN。DISCARD
是独立的 ALTER USER 操作,不能与修改密码、策略或注释组合使用。
+
+### 域名账号与版本变更
+
+对域名账号执行 DISCARD 时,先清除持久化域名账号中的次密码,已解析的 IP 记录要等下一次域名解析刷新后才会停止接受其保留副本。正常刷新间隔为 10
秒,但不是严格的撤销时延上限。
+
+滚动升级期间,旧 FE 只接受主密码,也无法解析新增子句。开始双密码轮换前,应完成所有 FE
的升级。使用此功能后降级会丢失保留的次密码,仅主密码得以保留;重新升级不会恢复原来的次密码。
+
+完整语句参考见 [ALTER
USER](../../../sql-manual/sql-statements/account-management/ALTER-USER) 和 [SET
PASSWORD](../../../sql-manual/sql-statements/account-management/SET-PASSWORD)。
+
## 用户身份匹配优先级
<!-- 知识类型: 规则说明 -->
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/ALTER-USER.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/ALTER-USER.md
index 0b4252cc30e..f320212c294 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/ALTER-USER.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/ALTER-USER.md
@@ -2,7 +2,7 @@
{
"title": "ALTER USER",
"language": "zh-CN",
- "description": "ALTER USER 语句用于修改一个用户的账户属性,包括密码、和密码策略等"
+ "description": "介绍 Apache Doris ALTER USER 的语法、权限和密码策略,以及自 4.2.1 起通过
RETAIN CURRENT PASSWORD 保留旧密码和 DISCARD OLD PASSWORD 撤销次密码的轮换流程。"
}
---
@@ -10,10 +10,13 @@
ALTER USER 语句用于修改一个用户的账户属性,包括密码、和密码策略等
+自 4.2.1 起,Doris 内置密码认证支持通过 `RETAIN CURRENT PASSWORD` 和 `DISCARD OLD PASSWORD`
管理双密码。
+
## 语法
```sql
-ALTER USER [IF EXISTS] <user_identity> [IDENTIFIED BY <password>]
+ALTER USER [IF EXISTS] <user_identity>
+ [IDENTIFIED BY <password> [RETAIN CURRENT PASSWORD] | DISCARD OLD PASSWORD]
[<password_policy>]
[<comment>]
@@ -68,13 +71,21 @@ password_policy:
> 指定用户注释
+**4. `RETAIN CURRENT PASSWORD`(自 4.2.1 起支持)**
+
+> 与 `IDENTIFIED BY` 一起使用,将原主密码保留为次密码,新密码成为主密码。主密码和次密码均可用于登录;更早保留的次密码会被替换。
+
+**5. `DISCARD OLD PASSWORD`(自 4.2.1 起支持)**
+
+> 删除保留的次密码,主密码保持不变。这是独立操作,不能与修改密码、密码策略、注释或其他账号操作组合使用。不存在次密码时,执行后没有变化。
+
## 权限控制
执行此 SQL 命令的用户必须至少具有以下权限:
| 权限 | 对象 | 说明 |
|:------------|:------------|:--------------|
-| ADMIN_PRIV | 用户(User)或 角色(Role) | 用户或者角色拥有 ADMIN_PRIV 权限才能进行此操作 |
+| GRANT_PRIV 或 ADMIN_PRIV | 全局 | 执行 ALTER USER,包括 RETAIN CURRENT PASSWORD 和
DISCARD OLD PASSWORD,均需要此权限。 |
## 注意事项
@@ -83,12 +94,21 @@ password_policy:
1. 从 2.0
版本开始,此命令不再支持修改用户角色,相关操作请使用[GRANT](./GRANT-TO.md)和[REVOKE](./REVOKE-FROM.md)。
2. 在一个 ALTER USER 命令中,只能同时对以下账户属性中的一项进行修改:
-- 修改密码
+- 修改密码,可附带 RETAIN CURRENT PASSWORD
+- 删除保留的次密码
- 修改 PASSWORD_HISTORY
- 修改 PASSWORD_EXPIRE
- 修改 FAILED_LOGIN_ATTEMPTS 和 PASSWORD_LOCK_TIME
- 解锁用户
+### 双密码(自 4.2.1 起支持)
+
+- `RETAIN CURRENT PASSWORD` 必须伴随修改密码,且当前主密码非空。新密码为空时,两份密码都会被清除,即使指定了 RETAIN。
+- 普通的非空改密语句如果不带 RETAIN,已有次密码仍然有效,不会因此被撤销。
+- 主密码和次密码均受账号锁定和密码过期策略约束。DISCARD 不改变密码历史,也不重新计算密码过期时间。
+
+完整轮换步骤、可观测性、域名账号行为和升级限制见[双密码](../../../admin-manual/auth/authentication/internal#双密码)。这些子句管理内置密码,不管理
LDAP 或外部认证集成持有的凭据。
+
## 示例
准备:先创建用户 `jack`,作为下面示例的目标用户:
@@ -121,3 +141,16 @@ ALTER USER jack@'%' ACCOUNT_UNLOCK
ALTER USER jack@'%' COMMENT "this is my first user"
```
+- 修改密码并保留旧密码(自 4.2.1 起支持)
+
+```sql
+ALTER USER jack@'%' IDENTIFIED BY 'NewPwd_2026!' RETAIN CURRENT PASSWORD;
+```
+
+原密码和 `NewPwd_2026!` 均可登录。所有客户端切换到新密码后,删除保留的旧密码:
+
+```sql
+ALTER USER jack@'%' DISCARD OLD PASSWORD;
+```
+
+此后只有 `NewPwd_2026!` 可以登录。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/SET-PASSWORD.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/SET-PASSWORD.md
index 5e0df28bdd7..3ef61097d0e 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/SET-PASSWORD.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/SET-PASSWORD.md
@@ -2,7 +2,7 @@
{
"title": "SET PASSWORD",
"language": "zh-CN",
- "description": "SET PASSWORD 语句用于修改一个用户的登录密码。"
+ "description": "介绍 Apache Doris SET PASSWORD 的语法、明文与哈希密码用法及权限要求,以及自 4.2.1
起通过 RETAIN CURRENT PASSWORD 保留旧密码的双密码轮换流程。"
}
---
@@ -10,11 +10,14 @@
SET PASSWORD 语句用于修改一个用户的登录密码。
+自 4.2.1 起,Doris 内置密码认证支持通过 `RETAIN CURRENT PASSWORD` 和 `DISCARD OLD PASSWORD`
管理双密码。
+
## 语法
```sql
SET PASSWORD [FOR <user_identity>] =
- [ PASSWORD(<plain_password>)] | [<hashed_password> ]
+ { PASSWORD(<plain_password>) | <hashed_password> }
+ [RETAIN CURRENT PASSWORD]
```
## 必选参数
@@ -31,7 +34,11 @@ SET PASSWORD [FOR <user_identity>] =
**1. `<user_identity>`**
-> 必须完全匹配在使用 CREATE USER 创建用户时指定的 user_identity,否则会报错用户不存在。如果不指定
user_identity,则当前用户为 'username'@'ip',这个当前用户,可能无法匹配任何 user_identity。可以通过 SHOW
GRANTS 查看当前用户。
+> 显式指定 `FOR` 时,必须与 `CREATE USER` 创建的账号身份完全匹配,包括 host 部分。省略 `FOR` 时,Doris 使用
`CURRENT_USER()` 返回的当前认证账号,而不是 `USER()` 返回的客户端 IP 身份。可通过 `SHOW GRANTS` 查看当前账号。
+
+**2. `RETAIN CURRENT PASSWORD`(自 4.2.1 起支持)**
+
+> 将原主密码保留为次密码,并将指定的新密码设为主密码,两者均可登录;更早保留的次密码会被替换。需要全局 `GRANT_PRIV` 或
`ADMIN_PRIV`,即使修改的是自己的密码。
## 权限控制
@@ -39,7 +46,8 @@ SET PASSWORD [FOR <user_identity>] =
| 权限 | 对象 | 说明 |
|:------------|:------------|:--------------|
-| ADMIN_PRIV | 用户(User)或 角色(Role) | 用户或者角色拥有 ADMIN_PRIV
权限才能修改所有用户的密码,否则只能修改当前用户的密码 |
+| 无额外权限 | 当前用户 | 不带 RETAIN 的普通自助改密不需要额外权限。 |
+| GRANT_PRIV 或 ADMIN_PRIV | 全局 | 修改其他用户的密码,或使用 RETAIN CURRENT
PASSWORD(包括自己的账号),均需要此权限。 |
## 注意事项
@@ -47,6 +55,15 @@ SET PASSWORD [FOR <user_identity>] =
- 如果 `FOR user_identity` 字段不存在,那么修改当前用户的密码。
+### 双密码(自 4.2.1 起支持)
+
+- 普通的非空改密语句如果不带 RETAIN,已有次密码保持不变。
+- 当前主密码为空时,RETAIN 会失败。新密码为空时,即使指定 RETAIN,也会清除两份密码。
+- 设置明文密码时使用 `PASSWORD('<new_password>')`;直接填写字符串时必须使用已经计算好的密码哈希。
+- 撤销次密码需要使用 `ALTER USER ... DISCARD OLD PASSWORD`,SET PASSWORD 没有 DISCARD 子句。
+
+完整流程和升级限制见[双密码](../../../admin-manual/auth/authentication/internal#双密码)。这些子句适用于内置密码认证。
+
## 示例
- 修改当前用户的密码
@@ -61,3 +78,20 @@ SET PASSWORD = '*6BB4837EB74329105EE4568DDA7DC67ED2CA2AD9'
SET PASSWORD FOR 'jack'@'192.%' = PASSWORD('123456')
SET PASSWORD FOR 'jack'@['domain'] =
'*6BB4837EB74329105EE4568DDA7DC67ED2CA2AD9'
```
+
+- 在轮换期间同时保留新旧密码(自 4.2.1 起支持)
+
+由具有全局 `GRANT_PRIV` 或 `ADMIN_PRIV` 的管理员执行:
+
+```sql
+CREATE USER 'rotation_user'@'%' IDENTIFIED BY 'OldPwd_2026!';
+SET PASSWORD FOR 'rotation_user'@'%' = PASSWORD('NewPwd_2026!') RETAIN CURRENT
PASSWORD;
+```
+
+`OldPwd_2026!` 和 `NewPwd_2026!` 均可登录。客户端迁移完成后,撤销旧凭据:
+
+```sql
+ALTER USER 'rotation_user'@'%' DISCARD OLD PASSWORD;
+```
+
+此后只有 `NewPwd_2026!` 可以登录。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
index ae338c293d3..d066737eaf3 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
@@ -2,7 +2,7 @@
{
"title": "SHOW GRANTS",
"language": "zh-CN",
- "description": "该语句用于查看用户权限。"
+ "description": "介绍 Apache Doris SHOW GRANTS 查看用户权限的语法、返回列和权限要求,以及自 4.2.1
起通过 Password 列的 Yes (dual) 标记识别保留次密码的账号。"
}
---
@@ -32,7 +32,7 @@ SHOW [ALL] GRANTS [FOR <user_identity>];
| -- | -- |
| UserIdentity | 用户标识 |
| Comment | 注释 |
- | Password | 是否设置密码 |
+ | Password | `No` 表示没有可用的本地密码;`Yes` 表示仅有主密码;`Yes (dual)` 表示同时保留次密码(自 4.2.1
起支持)。 |
| Roles | 拥有的角色 |
| GlobalPrivs | 拥有的全局权限 |
| CatalogPrivs | 拥有的 catalog 权限 |
diff --git
a/versioned_docs/version-4.x/admin-manual/auth/authentication/internal.md
b/versioned_docs/version-4.x/admin-manual/auth/authentication/internal.md
index d12c1a092b6..7997092142d 100644
--- a/versioned_docs/version-4.x/admin-manual/auth/authentication/internal.md
+++ b/versioned_docs/version-4.x/admin-manual/auth/authentication/internal.md
@@ -2,7 +2,7 @@
{
"title": "Built-in Authentication",
"language": "en",
- "description": "Detailed guide to the Apache Doris built-in authentication
mechanism: composition of the user_identity, password policies (history,
expiration, login-failure lockout, strength validation), IP matching priority,
simulating a blacklist with a whitelist, and common troubleshooting."
+ "description": "Manage Doris users, password policies, dual-password
rotation, identity matching, and authentication troubleshooting."
}
---
@@ -17,6 +17,7 @@ Apache Doris provides a built-in user authentication
mechanism. Administrators c
| --- | --- |
| Create an account, drop an account, reset a password | [Core
Concepts](#core-concepts), [Common Operational
Commands](#common-operational-commands) |
| Configure enterprise-grade password policies (expiration / history /
strength / lockout) | [Password Policies](#password-policies) |
+| Rotate an application password while clients migrate | [Dual
Passwords](#dual-passwords) |
| The same user name matches multiple `user_identity` values and login is
rejected | [User Identity Matching Priority](#user-identity-matching-priority) |
| Block a specific IP from logging in (simulate a blacklist) | [Simulating a
Blacklist with a Whitelist](#simulating-a-blacklist-with-a-whitelist) |
| Forgot the root password, or `current_user()` does not match `user()` |
[FAQ](#faq) |
@@ -125,6 +126,66 @@ SHOW PROC "/auth/'root'@'%'";
SHOW PROC "/auth/'user1'@'127.0.0.1'";
```
+## Dual Passwords
+
+<!-- Knowledge type: Operational procedure + Rules -->
+<!-- Applicable scenarios: Application credential rotation -->
+
+**Supported since 4.2.1.** Built-in password authentication can keep one
primary password and one retained secondary password for the same account. Use
this overlap to migrate clients to a new password without rejecting clients
that still use the previous one. A secondary password is absent by default and
is created only with `RETAIN CURRENT PASSWORD`. These changes affect subsequent
authentications and do not disconnect existing sessions.
+
+### Prerequisites
+
+- Upgrade every FE to 4.2.1 or later before using these clauses.
+- Execute the rotation as an administrator with global `GRANT_PRIV` or
`ADMIN_PRIV`. RETAIN requires this privilege even on your own account; an
ordinary self-service SET PASSWORD without RETAIN does not.
+- Use an account with a built-in, nonempty primary password. LDAP and
authentication integrations manage their own credentials.
+
+### Rotate a Password
+
+1. Create an example account, then set a new password while retaining its
current one. For an existing account, run only the ALTER USER statement.
+
+ ```sql
+ CREATE USER 'app_user'@'%' IDENTIFIED BY 'OldPwd_2026!';
+ ALTER USER 'app_user'@'%' IDENTIFIED BY 'NewPwd_2026!' RETAIN CURRENT
PASSWORD;
+ ```
+
+ Both `OldPwd_2026!` and `NewPwd_2026!` can authenticate. An equivalent
retaining change is `SET PASSWORD FOR 'app_user'@'%' = PASSWORD('NewPwd_2026!')
RETAIN CURRENT PASSWORD`; use it instead of the ALTER statement, not after it.
+
+2. Update every client to use `NewPwd_2026!`. Check the account's
retained-password state:
+
+ ```sql
+ SHOW GRANTS FOR 'app_user'@'%';
+ ```
+
+ The `Password` column shows `Yes (dual)`. `SHOW ALL GRANTS` and `SHOW PROC
'/auth'` expose the same marker. Each FE's
`doris_fe_secondary_password_auth_total` metric counts successful
authentications using the secondary password, across all accounts, after
account-policy checks; observe its increments rather than waiting for this
cumulative counter to return to zero.
+
+3. After all clients have migrated, revoke the secondary password:
+
+ ```sql
+ ALTER USER 'app_user'@'%' DISCARD OLD PASSWORD;
+ ```
+
+ Only `NewPwd_2026!` can authenticate, and the `Password` column returns to
`Yes`. Repeating DISCARD when no secondary exists has no effect.
+
+### Password Lifetime and Policy Rules
+
+| Operation | Result |
+| --- | --- |
+| Nonempty new password with RETAIN | Previous primary becomes the only
secondary; any earlier secondary is replaced. |
+| Nonempty change without RETAIN | Existing secondary remains valid. Replacing
the primary alone does not revoke it. |
+| Empty new password | Both slots are cleared, even with RETAIN. |
+| RETAIN with an empty current primary | Rejected. |
+| DISCARD OLD PASSWORD | Only the secondary is removed. Password history and
the password expiration clock are unchanged. |
+
+Both passwords are subject to the account's lock and expiration policies. A
retaining change is still a password change and follows password
strength/history rules and updates the expiration clock. Binding, unbinding, or
changing an authentication integration clears any retained secondary; RETAIN is
rejected across these transitions. DISCARD is a standalone ALTER USER operation
and cannot be combined with a password change, policy change, or comment.
+
+### Domain Accounts and Version Changes
+
+For a domain account, DISCARD clears the persistent domain account first.
Resolved-IP entries stop accepting their retained copy at the next
domain-resolver refresh. The normal interval is 10 seconds, but this is not a
strict revocation-time bound.
+
+During a rolling upgrade, an older FE authenticates against the primary only
and cannot parse the new clauses. Wait until every FE has been upgraded before
starting dual-password rotation. Downgrading after using the feature loses the
retained secondary; only the primary survives, and upgrading again does not
restore the old secondary.
+
+For the full statement reference, see [ALTER
USER](../../../sql-manual/sql-statements/account-management/ALTER-USER) and
[SET
PASSWORD](../../../sql-manual/sql-statements/account-management/SET-PASSWORD).
+
## User Identity Matching Priority
<!-- Knowledge type: Rule description -->
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/ALTER-USER.md
b/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/ALTER-USER.md
index f6be0eb66a3..6633c747d4f 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/ALTER-USER.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/ALTER-USER.md
@@ -2,7 +2,7 @@
{
"title": "ALTER USER",
"language": "en",
- "description": "The ALTER USER statement is used to modify a user's
account attributes, including passwords, and password policies, etc."
+ "description": "The ALTER USER statement modifies account passwords and
policies, including dual-password rotation."
}
---
@@ -10,10 +10,13 @@
The `ALTER USER` statement is used to modify a user's account attributes,
including passwords, and password policies, etc.
+Since 4.2.1, Doris supports dual passwords for built-in password
authentication with `RETAIN CURRENT PASSWORD` and `DISCARD OLD PASSWORD`.
+
## Syntax
```sql
-ALTER USER [IF EXISTS] <user_identity> [IDENTIFIED BY <password>]
+ALTER USER [IF EXISTS] <user_identity>
+ [IDENTIFIED BY <password> [RETAIN CURRENT PASSWORD] | DISCARD OLD PASSWORD]
[<password_policy>]
[<comment>]
@@ -67,13 +70,21 @@ password_policy:
>Specify the user comment.
+**4. `RETAIN CURRENT PASSWORD` (since 4.2.1)**
+
+> Use with `IDENTIFIED BY` to make the previous primary password the retained
secondary password. The new password becomes the primary; either password can
authenticate. Any earlier secondary password is replaced.
+
+**5. `DISCARD OLD PASSWORD` (since 4.2.1)**
+
+> Remove the retained secondary password, leaving the primary unchanged. This
is a standalone operation: do not combine it with a password change, password
policy, comment, or other account operation. If no secondary password exists,
it has no effect.
+
## Access Control Requirements
The user executing this SQL command must have at least the following
privileges:
| Privilege | Object | Notes |
|:--------------|:----------|:------|
-| ADMIN_PRIV | USER or ROLE | This operation can only be performed by
users or roles with ADMIN_PRIV permissions |
+| GRANT_PRIV or ADMIN_PRIV | Global | Required for ALTER USER, including
RETAIN CURRENT PASSWORD and DISCARD OLD PASSWORD. |
## Usage Notes
@@ -82,12 +93,21 @@ Since 4.1.5, only `'root'@'%'` is the special root
identity. An identity such as
1. Starting from version 2.0, this command no longer supports modifying user
roles. Please use [GRANT](./GRANT-TO.md) and [REVOKE](./REVOKE-FROM.md) for
related operations.
2. In an ALTER USER command, only one of the following account attributes can
be modified at the same time:
-- Change password
+- Change password, optionally with RETAIN CURRENT PASSWORD
+- Discard the retained secondary password
- Modify `PASSWORD_HISTORY`
- Modify `PASSWORD_EXPIRE`
- Modify `FAILED_LOGIN_ATTEMPTS` and `PASSWORD_LOCK_TIME`
- Unlock users
+### Dual Passwords (Since 4.2.1)
+
+- `RETAIN CURRENT PASSWORD` requires a nonempty current primary password and a
password change. An empty new password clears both password slots, even with
RETAIN.
+- An ordinary nonempty password change without RETAIN preserves an existing
secondary password; it does not revoke that credential.
+- Account lock and password expiration checks apply to both passwords. DISCARD
does not change password history or restart the password expiration clock.
+
+See [Dual
Passwords](../../../admin-manual/auth/authentication/internal#dual-passwords)
for the rotation procedure, observability, domain-account behavior, and upgrade
restrictions. These clauses manage built-in passwords, not credentials held by
LDAP or an external authentication integration.
+
## Example
Setup — create user `jack` so the examples below have a target user:
@@ -119,3 +139,17 @@ ALTER USER jack@'%' ACCOUNT_UNLOCK
```sql
ALTER USER jack@'%' COMMENT "this is my first user"
```
+
+- Rotate the password while keeping the previous password usable (since 4.2.1)
+
+```sql
+ALTER USER jack@'%' IDENTIFIED BY 'NewPwd_2026!' RETAIN CURRENT PASSWORD;
+```
+
+Both the previous password and `NewPwd_2026!` can authenticate. After all
clients have switched to the new password, discard the retained one:
+
+```sql
+ALTER USER jack@'%' DISCARD OLD PASSWORD;
+```
+
+Only `NewPwd_2026!` can authenticate afterward.
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/SET-PASSWORD.md
b/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/SET-PASSWORD.md
index 6c099258e6e..7f0a3a29588 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/SET-PASSWORD.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/SET-PASSWORD.md
@@ -2,7 +2,7 @@
{
"title": "SET PASSWORD",
"language": "en",
- "description": "The SET PASSWORD statement is used to modify a user's
login password."
+ "description": "Change a Doris login password and optionally retain the
current password during rotation."
}
---
@@ -10,11 +10,14 @@
The `SET PASSWORD` statement is used to modify a user's login password.
+Since 4.2.1, Doris supports dual passwords for built-in password
authentication with `RETAIN CURRENT PASSWORD` and `DISCARD OLD PASSWORD`.
+
## Syntax
```sql
SET PASSWORD [FOR <user_identity>] =
- [PASSWORD(<plain_password>)]|[<hashed_password>]
+ { PASSWORD(<plain_password>) | <hashed_password> }
+ [RETAIN CURRENT PASSWORD]
```
## Required Parameters
@@ -31,7 +34,11 @@ SET PASSWORD [FOR <user_identity>] =
**1. `<user_identity>`**
-> The user_identity here must exactly match the user_identity specified when
creating a user with CREATE USER, otherwise an error will be reported that the
user does not exist. If user_identity is not specified, the current user is
'username'@'ip', which may not match any user_identity. Current users can be
viewed through SHOW GRANTS.
+> With `FOR`, specify exactly the account identity created by `CREATE USER`,
including its host part. Without `FOR`, Doris uses the authenticated account
returned by `CURRENT_USER()`, not the client IP identity returned by `USER()`.
View the current account with `SHOW GRANTS`.
+
+**2. `RETAIN CURRENT PASSWORD` (since 4.2.1)**
+
+> Retain the previous primary password as the secondary and install the
specified new primary password. Either password can authenticate; any earlier
secondary is replaced. Requires global `GRANT_PRIV` or `ADMIN_PRIV`, including
when changing your own password.
## Access Control Requirements
@@ -39,7 +46,8 @@ The user executing this SQL command must have at least the
following privileges:
| Privilege | Object | Notes |
|:--------------|:----------|:------|
-| ADMIN_PRIV | USER or ROLE | User or Role has the ADMIN_PRIV privilege
to modify all user's password, otherwise only the current user's password can
be modified. |
+| None | Current user | An ordinary change of your own password without RETAIN
requires no additional privilege. |
+| GRANT_PRIV or ADMIN_PRIV | Global | Required to change another user's
password or use RETAIN CURRENT PASSWORD, including on your own account. |
## Usage Notes
@@ -47,6 +55,15 @@ Since 4.1.5, only `'root'@'%'` is the special root identity.
An identity such as
- If the `FOR user_identity` field does not exist, then change the current
user's password.
+### Dual Passwords (Since 4.2.1)
+
+- Without RETAIN, an ordinary nonempty password change preserves any existing
secondary password.
+- RETAIN fails if the current primary password is empty. An empty new password
clears both slots, including when RETAIN is specified.
+- For plaintext, use `PASSWORD('<new_password>')`; a bare string must contain
an already hashed password.
+- To revoke the secondary, use `ALTER USER ... DISCARD OLD PASSWORD`. SET
PASSWORD has no DISCARD clause.
+
+See [Dual
Passwords](../../../admin-manual/auth/authentication/internal#dual-passwords)
for the complete workflow and upgrade restrictions. These clauses apply to
built-in passwords.
+
## Example
- Modify the current user's password
@@ -61,4 +78,21 @@ SET PASSWORD = '*6BB4837EB74329105EE4568DDA7DC67ED2CA2AD9'
```sql
SET PASSWORD FOR 'jack'@'192.%' = PASSWORD('123456')
SET PASSWORD FOR 'jack'@['domain'] =
'*6BB4837EB74329105EE4568DDA7DC67ED2CA2AD9'
-```
\ No newline at end of file
+```
+
+- Rotate an account with an overlap period (since 4.2.1)
+
+Run as an administrator with global `GRANT_PRIV` or `ADMIN_PRIV`:
+
+```sql
+CREATE USER 'rotation_user'@'%' IDENTIFIED BY 'OldPwd_2026!';
+SET PASSWORD FOR 'rotation_user'@'%' = PASSWORD('NewPwd_2026!') RETAIN CURRENT
PASSWORD;
+```
+
+Both `OldPwd_2026!` and `NewPwd_2026!` authenticate. After migrating clients,
remove the old credential:
+
+```sql
+ALTER USER 'rotation_user'@'%' DISCARD OLD PASSWORD;
+```
+
+Only `NewPwd_2026!` authenticates afterward.
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
b/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
index 911c675b55e..67bfe7553d7 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-statements/account-management/SHOW-GRANTS.md
@@ -2,7 +2,7 @@
{
"title": "SHOW GRANTS",
"language": "en",
- "description": "This statement is used to view user permissions."
+ "description": "View Apache Doris user privileges and identify accounts
with retained secondary passwords using the SHOW GRANTS output."
}
---
@@ -32,7 +32,7 @@ Whether to view the permissions of all users.
| -- | -- |
| UserIdentity | User identity |
| Comment | Comment |
- | Password | Whether the password is set |
+ | Password | `No` if no local password is available; `Yes` for a primary
password only; `Yes (dual)` when a retained secondary also exists (since
4.2.1). |
| Roles | Roles |
| GlobalPrivs | Global privileges |
| CatalogPrivs | Catalog privileges |
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]