Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(admin): allow role demotion and case-insensitive role input (#6714)

MaojiaSheng7192600efab4
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 33158f8fb..fd6fb3922 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -2242,7 +2242,7 @@ enum AdminCommands {
#[arg(value_name = "user-id")]
user_id: String,
},
- /// Change a user's role (ROOT only)
+ /// Change a user's role for identity management (ROOT or own-account ADMIN)
SetRole {
/// Account ID
#[arg(value_name = "account-id")]
@@ -2250,7 +2250,7 @@ enum AdminCommands {
/// User ID
#[arg(value_name = "user-id")]
user_id: String,
- /// New role: admin or user
+ /// New role: admin or user (case-insensitive)
#[arg(value_name = "role")]
role: String,
},
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index 5d1f9e383..33c58491b 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -523,7 +523,7 @@ This catalog follows the routes actually mounted by the server. Each group headi
| GET | `/api/v1/admin/accounts/{account_id}/users/{user_id}/settings` | Get a user's memory policy |
| PATCH | `/api/v1/admin/accounts/{account_id}/users/{user_id}/settings` | Update a user's memory policy |
| DELETE | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | Remove a user |
-| PUT | `/api/v1/admin/accounts/{account_id}/users/{user_id}/role` | Promote a user to ADMIN |
+| PUT | `/api/v1/admin/accounts/{account_id}/users/{user_id}/role` | Change a user's role between USER and ADMIN |
| POST | `/api/v1/admin/accounts/{account_id}/users/{user_id}/key` | Regenerate a user key |
| POST | `/api/v1/admin/accounts/{account_id}/groups` | Create a group |
| GET | `/api/v1/admin/accounts/{account_id}/groups` | List groups |
diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.md
index 354fc1c0e..f22a80a6a 100644
--- a/docs/en/api/08-admin.md
+++ b/docs/en/api/08-admin.md
@@ -25,7 +25,7 @@ For `/api/v1/admin/*`, `trusted` mode permits requests with no explicit identity
| Manage groups and membership | Y | Y (own account) | N |
| List agents (deprecated, returns empty list) | Y | Y (own account) | N |
| Regenerate user key (API Key mode only) | Y | Y (own account) | Y (own key) |
-| Promote user to ADMIN | Y | Y (own account) | N |
+| Change user role between USER and ADMIN | Y | Y (own account) | N |
## CLI `--sudo` Option
@@ -1821,7 +1821,7 @@ ov --sudo admin remove-user acme bob
#### 1. API Implementation Overview
-Promote an account user to ADMIN. ROOT may operate on any account; ADMIN is limited to its own account.
+Change an account user's role between USER and ADMIN, including promotion and demotion. This endpoint is only for identity management operations. ROOT may operate on any account; ADMIN is limited to its own account.
**Processing Flow:**
1. Verify the requester has ROOT or ADMIN privileges and keep ADMIN within its own account
@@ -1841,11 +1841,12 @@ Promote an account user to ADMIN. ROOT may operate on any account; ADMIN is limi
|-----------|------|----------|---------|-------------|
| account_id | str | Yes | - | Workspace ID |
| user_id | str | Yes | - | User ID |
-| role | str | Yes | - | Must be "admin" |
+| role | str | Yes | - | New role: "admin" or "user" (case-insensitive) |
**Notes:**
-- ROOT and ADMIN can promote users to ADMIN; ADMIN is limited to its own account
-- This endpoint cannot set "user" or "root"; ROOT comes only from `server.root_api_key`
+- ROOT and ADMIN can promote users to ADMIN or demote them to USER; ADMIN is limited to its own account
+- This endpoint only accepts "user" and "admin"; ROOT comes only from `server.root_api_key`
+- Role input is case-insensitive: `user`/`User`/`USER` and `admin`/`Admin`/`ADMIN` are equivalent. Stored roles and response values are always lowercase.
#### 3. Usage Examples
@@ -1895,6 +1896,9 @@ fmt.Println(result["role"])
```bash
# ROOT example; an acme ADMIN can use `ov admin set-role` without --sudo
ov --sudo admin set-role acme bob admin
+
+# Demote bob to USER
+ov --sudo admin set-role acme bob user
```
**Response Example**
diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.md
index 6c90d3c04..f51bfe357 100644
--- a/docs/en/guides/04-authentication.md
+++ b/docs/en/guides/04-authentication.md
@@ -647,7 +647,7 @@ curl http://localhost:1933/health
| POST | `/api/v1/admin/accounts/{id}/users` | ROOT, ADMIN | Register user |
| GET | `/api/v1/admin/accounts/{id}/users` | ROOT, ADMIN, USER | List users; ADMIN/USER are limited to their own account |
| DELETE | `/api/v1/admin/accounts/{id}/users/{uid}` | ROOT, ADMIN | Remove user |
-| PUT | `/api/v1/admin/accounts/{id}/users/{uid}/role` | ROOT, ADMIN | Promote a user to ADMIN; ADMIN is limited to its own account |
+| PUT | `/api/v1/admin/accounts/{id}/users/{uid}/role` | ROOT, ADMIN | Change USER/ADMIN roles for identity management; ADMIN is limited to its own account |
| POST | `/api/v1/admin/accounts/{id}/users/{uid}/key` | ROOT, ADMIN, USER | Regenerate user key; USER may rotate only its own key using personal API key authentication |
## Custom Authentication Plugins
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index 14e4ff08d..1ad5011d3 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -518,7 +518,7 @@ JSON 输出 - 错误:
| GET | `/api/v1/admin/accounts/{account_id}/users/{user_id}/settings` | 获取用户记忆策略 |
| PATCH | `/api/v1/admin/accounts/{account_id}/users/{user_id}/settings` | 更新用户记忆策略 |
| DELETE | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | 移除用户 |
-| PUT | `/api/v1/admin/accounts/{account_id}/users/{user_id}/role` | 将用户提升为 ADMIN |
+| PUT | `/api/v1/admin/accounts/{account_id}/users/{user_id}/role` | 在 USER 与 ADMIN 之间变更用户角色 |
| POST | `/api/v1/admin/accounts/{account_id}/users/{user_id}/key` | 重新生成用户 Key |
| POST | `/api/v1/admin/accounts/{account_id}/groups` | 创建用户组 |
| GET | `/api/v1/admin/accounts/{account_id}/groups` | 列出用户组 |
diff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.md
index a51491bd1..66ef4db79 100644
--- a/docs/zh/api/08-admin.md
+++ b/docs/zh/api/08-admin.md
@@ -25,7 +25,7 @@ Admin API 用于多租户环境下的账户、用户和用户组管理。包括
| 管理用户组和成员 | Y | Y(本 account) | N |
| 列出 agents(已废弃,返回空列表) | Y | Y(本 account) | N |
| 重新生成 User Key(仅 API Key 模式) | Y | Y(本 account) | Y(自身密钥) |
-| 将用户提升为 ADMIN | Y | Y(本 account) | N |
+| 在 USER 与 ADMIN 之间变更用户角色 | Y | Y(本 account) | N |
## CLI `--sudo` 选项
@@ -1676,7 +1676,7 @@ ov --sudo admin remove-user acme bob
#### 1. API 实现介绍
-将账户用户提升为 ADMIN。ROOT 可以操作任意账户;ADMIN 只能操作自己的账户。
+在 USER 与 ADMIN 之间变更账户用户角色,支持提升和降级。该接口仅用于身份管理变更操作。ROOT 可以操作任意账户;ADMIN 只能操作自己的账户。
**处理流程:**
1. 验证请求者具有 ROOT 或 ADMIN 权限,并限制 ADMIN 只能操作自己的账户
@@ -1696,11 +1696,12 @@ ov --sudo admin remove-user acme bob
|------|------|------|--------|------|
| account_id | str | 是 | - | 工作区 ID |
| user_id | str | 是 | - | 用户 ID |
-| role | str | 是 | - | 固定为 "admin" |
+| role | str | 是 | - | 新角色:"admin" 或 "user",不区分大小写 |
**说明:**
-- ROOT 和 ADMIN 可以将用户提升为 ADMIN;ADMIN 只能操作自己的账户
-- 该接口不支持设置 "user" 或 "root";ROOT 身份只来自 `server.root_api_key`
+- ROOT 和 ADMIN 可以将用户提升为 ADMIN 或降级为 USER;ADMIN 只能操作自己的账户
+- 该接口仅接受 "user" 和 "admin";ROOT 身份只来自 `server.root_api_key`
+- 角色输入不区分大小写:`user`/`User`/`USER` 等价,`admin`/`Admin`/`ADMIN` 等价;存储值和响应值统一为小写。
#### 3. 使用示例
@@ -1750,6 +1751,9 @@ fmt.Println(result["role"])
```bash
# ROOT 调用示例;acme 的 ADMIN 可用 ov admin set-role,无需 --sudo
ov --sudo admin set-role acme bob admin
+
+# 将 bob 降级为 USER
+ov --sudo admin set-role acme bob user
```
**响应示例**
diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.md
index 07eb8e8c8..1d440868e 100644
--- a/docs/zh/guides/04-authentication.md
+++ b/docs/zh/guides/04-authentication.md
@@ -479,7 +479,7 @@ ACL 用户组是例外:组和成员通过 [Admin API](../api/08-admin.md#用
- 携带受信部署自身的 `root_api_key`。对于 `/api/v1/admin/*`,服务端校验该 key 后会将请求视为 ROOT。
- 如果 Admin 路由指向具体 account/user,也可以同时携带 `X-OpenViking-Account` + `X-OpenViking-User`。这些 header 必须与目标 URL 匹配,并会保留为请求身份;授权仍来自受信 `root_api_key`。
-角色更新 API 只支持将用户提升为 ADMIN。Trusted Admin API 的管理权限来自已校验的部署 root key,无需也不支持创建 ROOT 用户。
+角色更新 API 仅用于身份管理变更操作,支持在 USER 与 ADMIN 之间切换,包括提升和降级。ROOT 可操作任意账户,ADMIN 仅限本账户。Trusted Admin API 的管理权限来自已校验的部署 root key,无需也不支持创建 ROOT 用户。
配置了 root key 的 Trusted 部署可直接调用上面的 Admin API,无需先切换到 API Key 模式或注册网关管理员。
@@ -734,5 +734,5 @@ ov config validate
| POST | `/api/v1/admin/accounts/{id}/users` | ROOT, ADMIN | 注册用户 |
| GET | `/api/v1/admin/accounts/{id}/users` | ROOT, ADMIN, USER | 列出用户;ADMIN/USER 仅限本账户 |
| DELETE | `/api/v1/admin/accounts/{id}/users/{uid}` | ROOT, ADMIN | 移除用户 |
-| PUT | `/api/v1/admin/accounts/{id}/users/{uid}/role` | ROOT, ADMIN | 将用户提升为 ADMIN;ADMIN 仅限本账户 |
+| PUT | `/api/v1/admin/accounts/{id}/users/{uid}/role` | ROOT, ADMIN | 身份管理变更:切换 USER/ADMIN;ADMIN 仅限本账户 |
| POST | `/api/v1/admin/accounts/{id}/users/{uid}/key` | ROOT, ADMIN, USER | 重新生成 user key;USER 仅能使用个人 API Key 认证轮换自身密钥 |
diff --git a/openviking/server/routers/admin.py b/openviking/server/routers/admin.py
index 412072692..be44f44fd 100644
--- a/openviking/server/routers/admin.py
+++ b/openviking/server/routers/admin.py
@@ -1179,17 +1179,23 @@ async def set_user_role(
user_id: str = Path(..., description="User ID"),
ctx: RequestContext = Depends(get_request_context),
):
- """Promote an account user to ADMIN."""
+ """Change an account user's role for identity management operations only.
+
+ ROOT may manage any account; ADMIN may manage only its own account.
+ Supports USER <-> ADMIN changes, including promotion and demotion.
+ Role input is case-insensitive; stored and returned roles are lowercase.
+ """
_check_account_access(ctx, account_id)
- if body.role != Role.ADMIN:
- raise InvalidArgumentError("set_user_role only supports promotion to admin.")
- await _get_api_key_manager(request).set_role(account_id, user_id, Role.ADMIN)
+ role = body.role.lower()
+ if role not in (Role.USER, Role.ADMIN):
+ raise InvalidArgumentError("set_user_role only supports user and admin roles.")
+ await _get_api_key_manager(request).set_role(account_id, user_id, role)
return Response(
status="ok",
result={
"account_id": account_id,
"user_id": user_id,
- "role": Role.ADMIN,
+ "role": role,
},
)
diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.py
index 7ff59e17f..e063585f3 100644
--- a/tests/server/test_admin_api.py
+++ b/tests/server/test_admin_api.py
@@ -3254,10 +3254,27 @@ async def test_remove_user(
# ---- Role management ----
-async def test_admin_can_set_user_role_in_own_account(
[email protected]("actor_role", [Role.ROOT, Role.ADMIN])
+ ("initial_role", "requested_role", "new_role"),
+ [
+ (Role.USER, "admin", Role.ADMIN),
+ (Role.USER, "Admin", Role.ADMIN),
+ (Role.USER, "ADMIN", Role.ADMIN),
+ (Role.ADMIN, "user", Role.USER),
+ (Role.ADMIN, "User", Role.USER),
+ (Role.ADMIN, "USER", Role.USER),
+ ],
+)
+async def test_root_or_admin_can_set_user_role(
lightweight_admin_client: httpx.AsyncClient,
+ lightweight_admin_app,
+ actor_role: str,
+ initial_role: str,
+ requested_role: str,
+ new_role: str,
):
- """ADMIN can promote a user in its own account to ADMIN."""
+ """ROOT and ADMIN can promote and demote account users without rotating keys."""
acct = _uid()
create_account = await lightweight_admin_client.post(
"/api/v1/admin/accounts",
@@ -3267,31 +3284,108 @@ async def test_admin_can_set_user_role_in_own_account(
alice_key = create_account.json()["result"]["user_key"]
create_user = await lightweight_admin_client.post(
f"/api/v1/admin/accounts/{acct}/users",
- json={"user_id": "bob", "role": "user"},
+ json={"user_id": "bob", "role": initial_role},
headers=root_headers(),
)
bob_key = create_user.json()["result"]["user_key"]
resp = await lightweight_admin_client.put(
f"/api/v1/admin/accounts/{acct}/users/bob/role",
- json={"role": "admin"},
- headers={"X-API-Key": alice_key},
+ json={"role": requested_role},
+ headers=root_headers() if actor_role == Role.ROOT else {"X-API-Key": alice_key},
)
assert resp.status_code == 200
- assert resp.json()["result"]["role"] == "admin"
+ assert resp.json()["result"] == {
+ "account_id": acct,
+ "user_id": "bob",
+ "role": new_role,
+ }
+ manager = lightweight_admin_app.state.api_key_manager
+ assert (await manager.get_user(acct, "bob"))["role"] == new_role
+ assert (await manager.resolve_identity(bob_key)).role == new_role
- list_users = await lightweight_admin_client.get(
+ register_user = await lightweight_admin_client.post(
f"/api/v1/admin/accounts/{acct}/users",
+ json={"user_id": "charlie", "role": "user"},
headers={"X-API-Key": bob_key},
)
- assert list_users.status_code == 200
+ assert register_user.status_code == (200 if new_role == Role.ADMIN else 403)
- invalid_role = await lightweight_admin_client.put(
+
[email protected]("actor_role", [Role.ROOT, Role.ADMIN])
[email protected]("new_role", [Role.ROOT, "ROOT", "global", "Global", "invalid"])
+async def test_set_user_role_rejects_unsupported_roles(
+ lightweight_admin_client: httpx.AsyncClient,
+ lightweight_admin_app,
+ actor_role: str,
+ new_role: str,
+):
+ manager = lightweight_admin_app.state.api_key_manager
+ acct = _uid()
+ alice_key = await manager.create_account(acct, "alice")
+ bob_key = await manager.register_user(acct, "bob", Role.ADMIN)
+
+ resp = await lightweight_admin_client.put(
f"/api/v1/admin/accounts/{acct}/users/bob/role",
- json={"role": "root"},
+ json={"role": new_role},
+ headers=root_headers() if actor_role == Role.ROOT else {"X-API-Key": alice_key},
+ )
+ assert resp.status_code == 400
+ assert resp.json()["error"]["code"] == "INVALID_ARGUMENT"
+ assert (await manager.resolve_identity(bob_key)).role == Role.ADMIN
+
+
[email protected]("actor_role", [Role.USER, Role.ADMIN])
[email protected]("new_role", [Role.USER, Role.ADMIN])
+async def test_set_user_role_rejects_unauthorized_callers(
+ lightweight_admin_client: httpx.AsyncClient,
+ lightweight_admin_app,
+ actor_role: str,
+ new_role: str,
+):
+ """USER cannot change roles; ADMIN cannot change another account's roles."""
+ manager = lightweight_admin_app.state.api_key_manager
+ acct = _uid()
+ await manager.create_account(acct, "alice")
+ initial_role = Role.ADMIN if new_role == Role.USER else Role.USER
+ bob_key = await manager.register_user(acct, "bob", initial_role)
+ if actor_role == Role.ADMIN:
+ actor_key = await manager.create_account(_uid(), "other-admin")
+ else:
+ actor_key = await manager.register_user(acct, "charlie", Role.USER)
+
+ resp = await lightweight_admin_client.put(
+ f"/api/v1/admin/accounts/{acct}/users/bob/role",
+ json={"role": new_role},
+ headers={"X-API-Key": actor_key},
+ )
+ assert resp.status_code == 403
+ assert (await manager.resolve_identity(bob_key)).role == initial_role
+
+
+async def test_admin_can_demote_self_and_loses_role_management_access(
+ lightweight_admin_client: httpx.AsyncClient,
+ lightweight_admin_app,
+):
+ manager = lightweight_admin_app.state.api_key_manager
+ acct = _uid()
+ alice_key = await manager.create_account(acct, "alice")
+ await manager.register_user(acct, "bob", Role.ADMIN)
+
+ resp = await lightweight_admin_client.put(
+ f"/api/v1/admin/accounts/{acct}/users/alice/role",
+ json={"role": "user"},
+ headers={"X-API-Key": alice_key},
+ )
+ assert resp.status_code == 200
+ assert (await manager.resolve_identity(alice_key)).role == Role.USER
+
+ restore_role = await lightweight_admin_client.put(
+ f"/api/v1/admin/accounts/{acct}/users/alice/role",
+ json={"role": "admin"},
headers={"X-API-Key": alice_key},
)
- assert invalid_role.status_code == 400
+ assert restore_role.status_code == 403
async def test_regenerate_key(admin_client: httpx.AsyncClient):