@@ -371,43 +371,57 @@ authorization confirmation after login.
 
 ### Studio roles and Runtime access
 
-`--admin` and `--developer` each accept a comma-separated list of local
-usernames or OAuth email addresses. Whitespace is ignored and matching is
-case-insensitive. If the same identity appears in both lists, `admin` takes
-precedence. For a local Studio:
-
-```bash
-veadk studio \
-  --admin "admin,admin@example.com" \
-  --developer "alice,alice@example.com,bob"
-```
-
-The equivalent environment variables are `VEADK_STUDIO_ADMINS` and
-`VEADK_STUDIO_DEVELOPERS`.
-
-Use the same options for a deployed Studio:
+The only deployment role option is `--super-admin`, which accepts an existing
+Identity user's email or UID:
 
 ```bash
 veadk studio deploy \
   --user-pool-id <pool-id> \
   --allowed-client-id <client-id> \
   --vefaas-app-name <app-name> \
-  --admin "admin@example.com" \
-  --developer "alice@example.com,bob@example.com"
+  --super-admin "owner@example.com"
 ```
 
-Omitting both options treats every signed-in user as an `admin`. Supplying
-either list enables role-based access control. An identity that does not match
-either list is a regular user.
-
-| Capability | admin | developer | Regular user |
-| :-- | :-- | :-- | :-- |
-| Add, debug, and deploy agents | Allowed | Allowed | Denied; add/manage items are hidden from the sidebar |
-| View and connect to Runtimes | All Runtimes | Own Runtimes only | Own Runtimes only |
-| Manage or delete Runtimes | All Studio-managed Runtimes | Own Runtimes only | Denied |
+On first deployment, omitting this option makes all signed-in users admins,
+including future users. Supplying it makes other users regular users by default.
+The default and individual roles are stored in Identity. Later deployments and
+updates preserve existing assignments
+
+Only super admins can see and use **User management** to list pool users and
+change roles. They inherit every admin capability. Studio protects the initial
+super admin from demotion. To assign the first super admin to an existing
+installation without changing other roles, run
+`veadk studio update --vefaas-app-name <app-name> --super-admin <email-or-uid>`
+
+| Capability | Super admin | Admin | Developer | Regular user |
+| :-- | :-- | :-- | :-- | :-- |
+| Manage users | Allowed | Denied | Denied | Denied |
+| Add, debug, and deploy agents | Allowed | Allowed | Allowed | Denied |
+| View and connect to Runtimes | All | All | Own only | Own only |
+| Manage or delete Runtimes | All Studio-managed | All Studio-managed | Own only | Denied |
+
+The backend reads current Identity group membership for each authenticated
+request. Refreshing the page reflects role changes in permissions and the
+account badge
+
+In-app updates match the old `VEADK_STUDIO_ADMINS` and
+`VEADK_STUDIO_DEVELOPERS` entries to Identity users and preserve their roles.
+Only after migration succeeds are the old role environment values cleared.
+Unmatched or ambiguous entries and insufficient permissions stop migration and
+retain the old configuration. Empty legacy lists preserve the all-admin default;
+with explicit lists, unlisted users remain regular users. Existing admins are
+never automatically promoted to super admin
+
+If the old updater predates migration, the new runtime migrates on first startup
+and clears the Function configuration. Published revisions may retain their old
+environment snapshots, but these lists never overwrite initialized Identity
+roles. Older deployments need Identity user/group read and membership write
+permissions before upgrading; alternatively, the new CLI update refreshes the
+managed Studio IAM policy. These rules apply to both Volcengine and BytePlus
+
+Local sessions without an Identity pool still support
+`veadk studio --admin ... --developer ...`; `deploy` no longer accepts these options
 
-The account footer shows the OAuth email below the display name. Purple,
-yellow, and green badges identify admins, developers, and regular users.
 The manage-agent view defaults to Beijing and can be switched to Shanghai.
 After the first message is sent, a new conversation opens immediately while the
 server session ID initializes in the background.
@@ -416,7 +430,7 @@ The server records Runtime ownership when it creates a Runtime; authorization
 does not trust an author field submitted by the browser. Existing Runtimes may
 still be claimed by the legacy-compatible `veadk:author` ownership tag. A
 historical Runtime with neither `veadk:owner` nor `veadk:author` is visible only
-to admins.
+to admins and super admins.
 
 <Callout type="warning">
   A local username is stored in the browser and can be changed or impersonated.
 
@@ -314,48 +314,56 @@ frontend/service/studio_release_server/deploy.sh
 
 ### Studio 角色与 Runtime 权限
 
-`--admin` 和 `--developer` 分别接收逗号分隔的用户名或 OAuth 邮箱。空格会被
-忽略，身份匹配不区分大小写；同一身份同时出现在两个名单时，`admin` 优先。
-本地启动示例：
-
-```bash
-veadk studio \
-  --admin "admin,admin@example.com" \
-  --developer "alice,alice@example.com,bob"
-```
-
-也可以分别通过 `VEADK_STUDIO_ADMINS` 和 `VEADK_STUDIO_DEVELOPERS` 环境变量
-设置这两个名单。
-
-部署 Studio 时使用相同参数：
+部署时唯一的角色参数是 `--super-admin`，指定用户池内已有用户的邮箱或 UID：
 
 ```bash
 veadk studio deploy \
   --user-pool-id <pool-id> \
   --allowed-client-id <client-id> \
   --vefaas-app-name <app-name> \
-  --admin "admin@example.com" \
-  --developer "alice@example.com,bob@example.com"
+  --super-admin "owner@example.com"
 ```
 
-两项都不传时，所有登录用户都按管理员（`admin`）处理。只要传入任一名单就会启用
-角色权限；未命中名单的身份是普通用户。
+首次部署不指定超级管理员时，所有登录用户默认都是管理员，包括后续新增用户；指定后，
+其余用户默认是普通用户。默认角色和用户角色都存储在 Identity 中，后续部署和更新保留
+已保存的角色，不会重新套用初始化配置
+
+只有超级管理员可见并可使用“用户管理”，可查询当前用户池的用户、修改角色。
+超级管理员拥有管理员的全部权限，初始超级管理员不能在 Studio 内降级。
+已有部署没有超级管理员时，可运行
+`veadk studio update --vefaas-app-name <app-name> --super-admin <email-or-uid>`
+设置首位超级管理员，其他人的角色保持不变
+
+| 功能 | super admin | admin | developer | 普通用户 |
+| :-- | :-- | :-- | :-- | :-- |
+| 用户管理 | 允许 | 不允许 | 不允许 | 不允许 |
+| 添加、调试和部署 Agent | 允许 | 允许 | 允许 | 不允许 |
+| 查看和连接 Runtime | 全部 | 全部 | 仅自己创建的 | 仅自己创建的 |
+| 管理或删除 Runtime | 全部 Studio 管理的 | 全部 Studio 管理的 | 仅自己创建的 | 不允许 |
+
+新版 Studio 在每次已认证的后端请求中读取 Identity 用户组，角色修改后刷新页面即可
+看到变化。账号区域显示对应角色徽标
+
+云上页面更新会把旧环境变量 `VEADK_STUDIO_ADMINS`、`VEADK_STUDIO_DEVELOPERS`
+中的账号逐一匹配到 Identity，保留原角色，成功后清空旧角色变量。名单中的账号必须
+唯一匹配；匹配失败或权限不足时停止迁移并保留旧配置。旧名单为空时保留“全部为管理员”；
+有名单时，其余人仍是普通用户。不会自动将旧管理员升级成超级管理员
+
+旧更新器不包含迁移逻辑时，由新版首次启动完成迁移并清理 Function 配置。
+已发布 Revision 的环境快照可能仍保留原值，但 Identity 初始化完成后不会再次覆盖角色。
+旧部署需要 Identity 用户组读写权限；可先补齐权限，或使用新版 CLI 更新，由 CLI 更新
+Studio 托管的 IAM 策略。火山引擎和 BytePlus 遵循同样规则
 
-| 功能 | admin | developer | 普通用户 |
-| :-- | :-- | :-- | :-- |
-| 添加、调试和部署 Agent | 允许 | 允许 | 不允许；侧边栏隐藏添加/管理入口 |
-| 查看和连接 Runtime | 全部 Runtime | 仅自己创建的 Runtime | 仅自己创建的 Runtime |
-| 管理或删除 Runtime | 全部 Studio 管理的 Runtime | 仅自己创建的 Runtime | 不允许 |
+本地未配置 Identity 用户池时，仍兼容 `veadk studio --admin ... --developer ...`；
+`deploy` 已移除这两个参数
 
-侧边栏底部的账号区域会在用户名下显示 OAuth 邮箱，并在用户名右侧用紫色、黄色、
-绿色徽标分别标识管理员、开发者和普通用户。
 管理 Agent 页面默认展示北京区域的 Runtime，也可以切换到上海。
 新会话发送首条消息后会立即进入对话页面；服务端会话创建期间，会话 ID 显示为
 “初始化中”。
 
 Runtime 归属由服务端在创建时记录，不使用浏览器提交的作者字段做授权。升级前创建
 的 Runtime 会兼容 `veadk:author` 归属标签；同时缺少 `veadk:owner` 和
-`veadk:author` 归属标签的历史 Runtime 仅 admin 可见。
+`veadk:author` 归属标签的历史 Runtime 仅管理员和超级管理员可见。
 
 <Callout type="warning">
   本地用户名保存在浏览器中，可以被用户修改或冒充，只适合本地开发和功能验证。
 
@@ -47,6 +47,13 @@ See [deployment and operation](service/studio_release_notifier/README.md).
   and BytePlus; existing Runtime updates and Sidecar deployments keep their
   existing role behavior
 
+- **User management** stores Studio roles in Identity user groups
+  scoped to the configured user pool and client. A super administrator can search
+  all pool users, filter roles, and assign super administrator, administrator,
+  developer, or ordinary-user access. The next page refresh reads current roles;
+  protected backend requests also resolve live membership. Only immutable
+  subject-to-user-ID mappings are cached
+
 - **Sandbox updates** in System Information compare each Tool's current image
   with `ListToolTypes` for its cloud provider and actual region. Volcengine and
   BytePlus use their own credentials and API hosts; catalogs are cached for
@@ -555,6 +562,90 @@ Rebuild the UI from source after changing it:
 cd frontend && npm install && npm run build   # -> veadk/webui
 ```
 
+If an existing checkout reports missing `i18next` or `react-i18next` modules,
+run `npm ci` from `frontend/` to synchronize dependencies with the lockfile
+before rebuilding. Reusing another checkout's `node_modules` can retain older
+dependencies even when the current `package.json` already declares them
+
+### Identity-backed user management
+
+Deploy with `--super-admin <existing-user-email-or-uid>` to select the first
+super administrator. This is the only deployment role flag; `deploy --admin`
+and `deploy --developer` are no longer supported
+
+Without `--super-admin`, deployment first warns that user and permission
+management will be inconvenient without a super administrator and asks
+`是否继续? [y/N]`. Press Enter or enter `n` to cancel before cloud operations;
+enter `y` to continue. Setting `VEADK_STUDIO_SUPER_ADMIN` also satisfies this
+check. Read-only `--precheck-only` does not prompt
+
+```bash
+veadk studio deploy --user-pool-id <pool-uid> \
+  --allowed-client-id <client-uid> --vefaas-app-name <app-name> \
+  --super-admin <existing-user-email-or-uid>
+```
+
+On first deployment, omitting `--super-admin` stores an **admin** default in
+Identity, so existing and future signed-in users are administrators. Specifying
+it stores a **regular-user** default for other users. Existing Identity roles
+and the stored default are preserved on subsequent deployments and updates
+
+Only super administrators can see **User management** or call its APIs. They
+also inherit all administrator capabilities, including visibility into all
+agents and resources available to the Studio. The initial super administrator
+is protected from demotion. If an existing Studio has none, use
+`veadk studio update --vefaas-app-name <app-name> --super-admin <email-or-uid>`
+to assign the first one without resetting other users' roles
+
+Role changes validate the browser Origin against the public OAuth callback URL
+configured by deployment, so HTTPS gateways can forward to an internal HTTP
+server without blocking legitimate changes. Other origins remain blocked, and
+client-supplied forwarding headers cannot change the accepted origin. For a
+custom public domain, set `--oauth2-redirect-uri` to its OAuth callback URL
+
+For local use, pass `--oauth2-user-pool-uid`, `--oauth2-user-pool-client-uid`, and
+optionally `--super-admin` to `veadk studio`, with the selected provider's AK/SK
+available. `VEIDENTITY_REGION` selects the Identity region. Volcengine and
+BytePlus use their respective credentials and API hosts. Local sessions without
+an Identity pool retain the legacy `--admin` / `--developer` options
+
+Four `studio-<client-uid>-<role>` Identity groups store application roles; their
+metadata stores the default role and the protected user's immutable UID. These
+application roles do not assign cloud IAM roles. Each authenticated backend
+request reads current group membership. OIDC subjects map to Identity management
+UIDs; email cannot substitute for an authenticated subject. Refreshing the page
+shows a newly assigned role. Multiple role memberships fail closed to regular
+user access and can be repaired by assigning a role again
+
+Cloud frontend updates automatically migrate `VEADK_STUDIO_ADMINS` and
+`VEADK_STUDIO_DEVELOPERS` into Identity. Each UID, subject, email or username
+must match exactly one pool user before any assignments are written. Admin
+membership takes precedence over developer membership. With either legacy list,
+unlisted users remain regular users; with neither list and no initial super
+administrator, everyone retains admin access. Migration never promotes a legacy
+admin to super administrator automatically
+
+After successful migration, the update clears the old role environment values
+and enables Identity roles. Failures retain the old configuration. Updates and
+restarts preserve subsequent role edits in Identity. When the running updater
+predates this feature, the new runtime performs the migration before accepting
+requests and clears the Function configuration. Existing immutable revisions
+may still contain their original environment snapshot; the new runtime ignores
+those old lists once Identity initialization is complete
+
+Deploy and CLI update provision the required Identity permissions on the
+managed Studio IAM policy. In-app updates check permissions and do not change
+IAM policies. For an older updater that lacks this check, grant Identity
+user/group read and group create/update/add/remove-member permissions before
+upgrading, or use the new `veadk studio update` CLI. Missing permissions stop
+migration instead of falling back to static role lists
+
+Initialize a new pool/client on one instance before starting additional
+instances. Identity membership updates are not transactional across instances;
+conflicting edits are denied or reported for retry, and multiple memberships
+grant no additional privileges. Audit logs include the actor, target, old/new
+roles and operation ID
+
 Dev loop with hot reload (Vite proxies the API):
 
 ```bash
 
@@ -137,10 +137,35 @@ def reconcile_studio_update_resources(
     access_key: str,
     secret_key: str,
     session_token: str,
+    migrate_identity_roles: bool = True,
 ) -> dict[str, str]:
     """Return environment overrides for resources missing from an older Studio."""
     function, environment = _function_state(function_client, function_id)
     overrides: dict[str, str] = {}
+    if migrate_identity_roles and (
+        environment.get("OAUTH2_USER_POOL_ID")
+        or environment.get("VEADK_STUDIO_USER_POOL_ID")
+    ):
+        import click
+        from frontend.server.user_management.deployment import prepare_identity_roles
+        from veadk.cli.studio_release import StudioReleaseError
+
+        try:
+            overrides.update(
+                prepare_identity_roles(
+                    pool_uid=environment.get("OAUTH2_USER_POOL_ID")
+                    or environment.get("VEADK_STUDIO_USER_POOL_ID", ""),
+                    client_uid=environment.get("OAUTH2_USER_POOL_CLIENT_ID", ""),
+                    provider=provider,
+                    region=environment.get("VEIDENTITY_REGION") or region,
+                    access_key=access_key,
+                    secret_key=secret_key,
+                    session_token=session_token,
+                    legacy_environment=environment,
+                )
+            )
+        except click.ClickException as error:
+            raise StudioReleaseError(str(error)) from error
 
     from frontend.server.workspace_tool import workspace_update_environment
 
 
@@ -0,0 +1,15 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Studio user administration backed by Identity user groups."""