[Admin Feature] Introduce Oauth2 to Admin and Agent

[robocanic]

What would you like to be added:
oauth2 包括admin的接入和agent的用户身份标识

Why is this needed:

[nagisa-kunhah]

Hello, I am interested in this issue. Could you please assign it to me？

[nagisa-kunhah]

一、Admin的接入

大致流程：用户点击 SSO 后请求 GET /api/v1/auth/oidc/login，Dubbo Admin 生成授权 URL 并把浏览器重定向到外部 OIDC Provider，Provider 登录成功后会把浏览器重定向回 GET /api/v1/auth/oidc/callback?code=<authorization-code>&state=<state>，Dubbo Admin 再用这个 code 调 Provider 的 token endpoint 换token、校验用户身份、写入本地 session，前端随后通过 GET /api/v1/auth/userinfo 获取当前用户信息，后续业务接口继续靠 session 访问。

spec

    # 引入 OAuth2/OIDC 登录能力

    ## 变更概述

    为 Dubbo Admin 引入基于 OAuth2/OIDC 的登录能力，使 Admin 控制台可以接入企业统一身份系统，并为后续 Agent 用户身份识别、审计和权限控制打基础。

    第一阶段只聚焦 Admin Web 控制台登录：用户通过 OIDC Provider 完成认证，Dubbo Admin 后端解析用户身份后建立自己的 session。现有用户名密码登录继续保留，用于本地开发、兼容部署和紧急访问。

    ## 背景

    当前 Dubbo Admin 的认证方式是配置文件中的固定用户名密码。后端登录成功后将 `user` 写入 Gin session，后续接口通过 session 判断是否登录。

    这种方式实现简单，但在生产环境有明显限制：

    - 无法接入公司统一登录系统。
    - 只有一个静态账号，不能识别真实用户。
    - 不利于后续审计、权限控制和 Agent 代表用户访问。
    - 密码由 Dubbo Admin 自己维护，不符合企业 SSO 场景。

    Issue `apache/dubbo-admin#1503` 提到 OAuth2 覆盖 Admin 接入和 Agent 用户身份标识。由于 Dubbo Admin 需要知道“当前用户是谁”，本变更应以 OIDC 为主，OAuth2 作为底层授权协议。

    ## 目标

    - 支持 Admin Web 控制台通过 OIDC 登录。
    - 保留现有用户名密码登录方式。
    - 将认证后的用户身份归一化为统一 Principal 模型。
    - 后续业务接口继续使用 Dubbo Admin 自己的 session 校验登录态。
    - 前端不保存 `access_token`、`id_token`、`refresh_token`。
    - 提供 fake OIDC server，用于本地开发和 e2e 测试。
    - 为后续 Agent bearer token 校验、用户身份透传和 RBAC 留出扩展点。

    ## 非目标

    - 第一阶段不维护 refresh token。
    - 第一阶段不实现 Agent bearer token 认证。
    - 第一阶段不实现 RBAC 权限拦截。
    - 第一阶段不支持多个 OIDC Provider。
    - 第一阶段不支持手动配置 authorization、token、userinfo、jwks endpoint override。
    - 第一阶段不实现 Provider 级别的单点退出。
    - 第一阶段不要求接入某个具体公司的 SSO 系统。

    ## 当前实现位置

    当前认证相关代码主要在：

    - `pkg/config/console/auth/config.go`：认证配置结构。
    - `pkg/console/router/router.go`：`/api/v1/auth/login` 和 `/api/v1/auth/logout` 路由。
    - `pkg/console/handler/auth.go`：用户名密码登录和退出逻辑。
    - `pkg/console/component.go`：Gin session 初始化和登录态校验中间件。
    - `ui-vue3/src/Login.vue`：前端登录页。
    - `ui-vue3/src/api/service/login.ts`：前端登录 API 封装。
    - `ui-vue3/src/utils/AuthUtil.ts`：前端本地 `auth-state` 状态。

    当前后端中间件只跳过路径后缀为 `/login` 的请求，OIDC callback 接入后需要改为显式匿名路径白名单。

    ## 用户流程

    ### 用户名密码登录

    1. 用户打开 Admin UI。
    2. 前端提交用户名密码到 `POST /api/v1/auth/login`。
    3. 后端校验配置文件中的 `console.auth.user` 和 `console.auth.password`。
    4. 校验成功后写入 Principal session。
    5. 后续 API 请求通过 session cookie 识别登录态。

    ### OIDC 登录

    1. 用户打开 Admin UI。
    2. 登录页展示 SSO 登录入口。
    3. 用户点击 SSO 登录，浏览器访问 `GET /api/v1/auth/oidc/login`。
    4. 后端生成 `state`、`nonce` 和 PKCE 参数，并暂存到 session。
    5. 后端重定向浏览器到 OIDC Provider 的 authorization endpoint。
    6. 用户在 Provider 完成登录。
    7. Provider 回调 `GET /api/v1/auth/oidc/callback?code=<authorization-code>&state=<state>`。
    8. 后端校验 `state`，使用 `code` 换取 token。
    9. 后端校验 ID Token，或结合 UserInfo endpoint 获取用户信息。
    10. 后端创建统一 Principal 并写入 session。
    11. 后端重定向用户回 Admin UI。
    12. 前端调用 `GET /api/v1/auth/userinfo` 获取当前用户信息。

    ## 配置变更

    建议扩展 `console.auth`：

    ```yaml
    console:
    auth:
        methods:
        - password
        - oidc
        user: admin
        password: dubbo@2025
        expirationTime: 3600
        sessionSecret: ${DUBBO_ADMIN_SESSION_SECRET}
        oidc:
        issuer: http://localhost:9999
        clientId: dubbo-admin
        clientSecret: ${DUBBO_ADMIN_OIDC_CLIENT_SECRET}
        redirectUrl: http://localhost:8888/api/v1/auth/oidc/callback
        postLoginRedirectUrl: http://localhost:8881/admin/
        scopes:
            - openid
            - profile
            - email
        usernameClaim: preferred_username
        groupsClaim: groups
        rolesClaim: roles
    ```

    说明：

    - `methods` 控制启用的认证方式。
    - `password` 登录沿用现有 `user` 和 `password`。
    - `oidc.issuer` 用于 OIDC discovery；第一阶段只支持 discovery，不支持手动 endpoint override。
    - `redirectUrl` 是注册到 Provider 的回调地址。
    - `postLoginRedirectUrl` 是 callback 成功后回到前端的地址。
    - `sessionSecret` 替代当前硬编码的 `"secret"`。

    ## 协议库使用

    Dubbo Admin 不自行实现 OAuth2/OIDC 协议细节，只实现与自身登录体系对接的 HTTP 接口和 session 逻辑。

    OAuth2 授权码流程应使用 Go 官方维护的 `golang.org/x/oauth2`：

    - 使用 `oauth2.Config.AuthCodeURL` 生成 Provider 登录跳转地址。
    - 使用 `oauth2.Config.Exchange` 将 authorization code 换取 token。
    - 使用 `oauth2.Config` 管理 `clientId`、`clientSecret`、`redirectUrl` 和 `scopes`。

    OIDC 相关能力应使用成熟 OIDC 库，例如 `github.com/coreos/go-oidc/v3/oidc` 或等价库：

    - 通过 `issuer` 做 OIDC discovery。
    - 校验 ID Token 的签名、issuer、audience、expiration 和 nonce。
    - 解析 claims。
    - 必要时调用 UserInfo endpoint 获取用户信息。

    Dubbo Admin 自己负责：

    - 暴露 `/api/v1/auth/oidc/login` 和 `/api/v1/auth/oidc/callback`。
    - 生成、保存和校验 `state`、`nonce`、PKCE 参数。
    - 将 OIDC 用户信息映射为 Principal。
    - 创建和清理 Dubbo Admin 本地 session。
    - 将用户重定向回 Admin UI。

    ## 新增或调整的接口

    新增：

    - `GET /api/v1/auth/oidc/login`：发起 OIDC authorization code flow。
    - `GET /api/v1/auth/oidc/callback`：处理 Provider 回调并创建本地 session。
    - `GET /api/v1/auth/userinfo`：返回当前登录用户 Principal。

    保留：

    - `POST /api/v1/auth/login`：用户名密码登录。
    - `POST /api/v1/auth/logout`：清理 Dubbo Admin 本地 session。

    调整：

    - auth middleware 使用显式 allowlist。
    - 允许匿名访问登录入口、OIDC callback 和 health check。
    - `/api/v1` 下业务接口默认要求已登录 session。

    ## Principal 模型

    统一身份模型建议为：

    ```go
    type Principal struct {
        Subject  string
        Username string
        Email    string
        Groups   []string
        Roles    []string
        AuthType string
        Provider string
    }
    ```

    OIDC 登录时：

    - `Subject` 来自 `sub`。
    - `Username` 默认来自 `preferred_username`，不存在时回退到 `email` 或 `sub`。
    - `Groups` 和 `Roles` 只保存，不在第一阶段参与权限拦截。
    - `AuthType` 为 `oidc`。

    用户名密码登录时：

    - `Username` 来自表单中的用户名。
    - `AuthType` 为 `password`。

    ## Fake OIDC Server

    为了本地开发和 e2e 测试，需要提供轻量 fake OIDC server。它只模拟协议边界，不模拟完整公司 SSO。

    建议位置：

    - `test/fakeoidc/`：fake OIDC server 代码。
    - `app/dubbo-admin/dubbo-admin-oidc-local.yaml`：本地 OIDC 配置。

    最小 endpoint：

    - `GET /.well-known/openid-configuration`
    - `GET /oauth2/authorize`
    - `POST /oauth2/token`
    - `GET /userinfo`
    - `GET /jwks`

    测试用户示例：

    ```json
    {
    "sub": "user-123",
    "preferred_username": "zhangsan",
    "email": "zhangsan@example.com",
    "groups": ["dubbo-admins"]
    }
    ```

    fake server 至少支持：

    - 正常登录。
    - 无效 authorization code。
    - state 不匹配。
    - UserInfo 缺失或格式错误。

    ## 测试要求

    后端测试应覆盖：

    - 未登录访问业务接口返回 401。
    - 用户名密码登录仍然可用。
    - OIDC login 正确重定向到 Provider。
    - OIDC callback 拒绝错误 state。
    - OIDC callback 拒绝错误 code。
    - OIDC callback 成功后写入 Principal session。
    - 登录后访问业务接口成功。
    - logout 后 session 失效。

    e2e 测试应覆盖：

    - 用户从登录页点击 SSO 登录。
    - fake OIDC server 自动完成授权回调。
    - 前端显示 fake 用户身份。
    - 登录后业务 API 请求成功。
    - 退出后再次访问业务页面会回到登录页。

    ## 安全要求

    - 必须校验 `state`。
    - 必须使用并校验 `nonce`。
    - 推荐使用 authorization code flow + PKCE。
    - 必须校验 ID Token 的 issuer、audience、signature、expiration。
    - `clientSecret` 只能保存在后端配置中。
    - OAuth token 不得写入前端 localStorage 或普通 cookie。
    - session cookie 应设置 HttpOnly 和 SameSite，HTTPS 场景应设置 Secure。
    - OIDC 开启时，生产环境不得使用默认 session secret。

    ## 兼容性

    现有用户名密码登录继续可用，避免破坏已有部署。默认配置可以继续只启用 password。启用 OIDC 时，通过 `methods` 显式打开。第一阶段允许同时启用 password 和 oidc，生产环境是否禁用 password 由部署方通过配置决定。

    前端现有 `auth-state` 只应作为 UI 状态缓存，不能作为后端认证凭据。后续应逐步改为通过 `/api/v1/auth/userinfo` 同步当前真实登录态。

    ## 已确认决策

    - OIDC Provider 第一阶段只支持 issuer discovery，不支持手动 endpoint override。
    - 第一阶段保留用户名密码登录。
    - 第一阶段允许 password 和 oidc 同时启用。
    - OAuth2 授权码流程使用 `golang.org/x/oauth2`，不手写协议细节。
    - OIDC discovery、ID Token 校验和 claims 解析使用成熟 OIDC 库。

    ## 开放问题

    - `sessionSecret` 的默认值和生产环境校验策略如何定义。
    - fake OIDC server 是否需要签发真实 JWT 并提供 JWKS。
    - `/admin` 静态资源是否需要登录态保护，还是只保护 `/api/v1` 业务接口。

Agent token

大致流程：用户登录 Dubbo Admin 后在页面创建一个可过期、可撤销、有 scope 的 MCP Access Token，Dubbo Admin 只保存这个 token 的 hash 和归属用户信息，Agent 调 POST /api/v1/mcp 时通过Authorization: Bearer 带上它，后端查库校验 token 后把请求映射回该用户并执行 MCP tool。

spec

    # 引入 MCP Agent Token 身份标识

    ## 变更概述

    为 Dubbo Admin 的 MCP 接口引入 Agent Token 认证能力。用户登录 Admin 控制台后，可以在个人页面创建自己的 MCP Access Token，并将 token 配置到 MCP Client 或 Agent 中。Agent 调用 `/api/v1/mcp` 时通过 `Authorization: Bearer <token>` 携带该 token，Dubbo Admin 校验后将请求映射为该 token 所属用户。

    该方案的目标是解决 Agent 调用 MCP tools 时的用户身份标识和审计问题，而不是给所有普通 REST API 开放新的认证入口。

    ## 背景

    当前 MCP 文档中，`/api/v1/mcp` 使用和 Admin Console API 相同的 session auth。测试流程是先调用 `/api/v1/auth/login` 获取 session cookie，再带 cookie 调用 MCP endpoint。

    这种方式适合本地手动测试，但不适合真实 Agent 场景：

    - Agent 不应该长期保存用户密码。
    - Agent 不适合依赖浏览器 session cookie。
    - Dubbo Admin 需要知道 MCP 调用代表哪个真实用户。
    - 用户需要能撤销给 Agent 的访问能力。
    - 后续审计需要记录用户、Agent token、MCP method 和 tool name。

    因此需要一个面向 MCP endpoint 的用户级 token 机制。

    ## 目标

    - 支持用户在 Admin 控制台创建 MCP Access Token。
    - 支持 Agent 调用 `/api/v1/mcp` 时携带 bearer token。
    - 服务端根据 token 识别真实用户并构造统一 Principal。
    - token 支持过期、撤销、scope 和 last used 信息。
    - token 明文只在创建时展示一次。
    - 服务端只保存 token hash，不保存明文 token。
    - token 数据支持持久化存储，生产环境可使用 MySQL 或 PostgreSQL。
    - MCP endpoint 继续兼容现有 session cookie 认证，便于浏览器和本地测试。

    ## 非目标

    - 不为所有 `/api/v1` REST API 开放 Agent Token 认证。
    - 不让 Agent 使用用户名密码登录。
    - 不实现 OAuth2 Token Exchange 或 On-Behalf-Of flow。
    - 不实现 refresh token。
    - 不实现完整 RBAC，只做 MCP token scope 校验。
    - 不把 token 明文保存到数据库。

    ## 用户场景

    ### 创建 Token

    1. 用户通过 password 或 OIDC 登录 Dubbo Admin。
    2. 用户进入个人页面或安全设置页面。
    3. 用户点击“创建 MCP Token”。
    4. 用户填写 token 名称、有效期和权限范围。
    5. 后端生成随机 token 明文。
    6. 后端保存 token hash 和 metadata。
    7. 前端只展示一次 token 明文。
    8. 用户将 token 配置给 MCP Client 或 Agent。

    ### Agent 调用 MCP

    1. Agent 读取用户配置的 MCP Access Token。
    2. Agent 调用 `POST /api/v1/mcp`。
    3. 请求头携带 `Authorization: Bearer <mcp-token>`。
    4. Dubbo Admin 对 token 做 hash 后查询 token store。
    5. 后端校验 token 是否存在、未过期、未撤销、scope 满足 MCP 调用。
    6. 后端根据 token owner 构造 Principal。
    7. MCP server 执行对应 JSON-RPC method 或 tool call。
    8. 后端更新 token 的 last used 信息。
    9. 审计日志记录用户身份、token id、MCP method 和 tool name。

    示例请求：

    ```http
    POST /api/v1/mcp
    Authorization: Bearer dubbo_mcp_<random-secret>
    Content-Type: application/json
    Accept: application/json, text/event-stream
    ```

    ```json
    {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "dubbo_get_application_detail",
        "arguments": {
        "mesh": "mock",
        "appName": "demo-provider"
        }
    }
    }
    ```

    ## Token 数据模型

    建议新增 MCP token metadata：

    ```go
    type MCPAgentToken struct {
        ID           string
        TokenHash    string
        Name         string
        OwnerSubject string
        OwnerName    string
        Scopes       []string
        ExpiresAt    time.Time
        RevokedAt    *time.Time
        CreatedAt    time.Time
        LastUsedAt   *time.Time
        LastUsedIP   string
    }
    ```

    说明：

    - `ID` 用于展示、撤销和审计。
    - `TokenHash` 是 token 明文的 hash，不能存明文。
    - `OwnerSubject` 对应 Principal 的 `Subject`。
    - `OwnerName` 用于页面展示和审计辅助。
    - `Scopes` 控制该 token 可访问的 MCP 能力。
    - `RevokedAt` 非空时表示 token 已撤销。
    - `LastUsedAt` 和 `LastUsedIP` 用于用户识别异常使用。

    ## Token 格式

    token 明文建议带固定前缀：

    ```text
    dubbo_mcp_<random-secret>
    ```

    后端生成时要求：

    - 使用加密安全随机数。
    - 明文只返回给前端一次。
    - 后端保存 `sha256(token)` 或更强 hash 结果。
    - 日志中不得输出 token 明文。

    ## Scope 设计

    第一阶段建议只支持少量 scope：

    - `mcp:read`：允许调用只读 MCP tools。
    - `mcp:write`：预留给未来写操作 MCP tools。

    如果当前 MCP tools 都是查询类，创建 token 时默认只授予 `mcp:read`。

    MCP tool 注册或调用时应能标识所需 scope。第一阶段如果没有写操作 tool，可以先统一要求 `mcp:read`。

    ## 存储设计

    MCP Agent Token 需要服务端存储。原因是必须支持撤销、过期、owner 映射、scope 校验和 last used 记录。

    生产环境应支持持久化存储：

    - MySQL
    - PostgreSQL

    本地开发和测试可以支持 memory store：

    - 适合单进程本地调试。
    - 服务重启后 token 丢失。
    - 不适合生产。

    不建议把 token 强行建模为 mesh resource。MCP Agent Token 属于认证安全数据，不是服务发现或治理资源。建议新增独立 store 接口：

    ```go
    type MCPAgentTokenStore interface {
        Create(token *MCPAgentToken) error
        GetByHash(hash string) (*MCPAgentToken, error)
        ListByOwner(ownerSubject string) ([]*MCPAgentToken, error)
        Revoke(tokenID string, ownerSubject string) error
        UpdateLastUsed(tokenID string, usedAt time.Time, ip string) error
    }
    ```

    实现建议：

    - `memoryMCPAgentTokenStore`：用于测试和本地开发。
    - `dbMCPAgentTokenStore`：复用现有 MySQL/PostgreSQL 连接能力。

    ## Backend API 变更

    新增面向用户的 token 管理接口：

    - `POST /api/v1/auth/mcp-tokens`：创建 MCP token。
    - `GET /api/v1/auth/mcp-tokens`：列出当前用户的 token metadata。
    - `DELETE /api/v1/auth/mcp-tokens/:tokenID`：撤销当前用户的指定 token。

    创建接口返回 token 明文一次：

    ```json
    {
    "id": "token-123",
    "token": "dubbo_mcp_<random-secret>",
    "name": "local-agent",
    "scopes": ["mcp:read"],
    "expiresAt": "2026-08-25T00:00:00Z"
    }
    ```

    列表接口不得返回 token 明文，只返回 metadata。

    ## MCP 认证变更

    `/api/v1/mcp` 支持两种认证方式：

    - session cookie：保留现有浏览器和本地测试体验。
    - bearer token：供 Agent 和 MCP Client 使用。

    认证优先级建议：

    1. 如果请求带 `Authorization: Bearer`，优先按 MCP Agent Token 校验。
    2. 如果没有 bearer token，再回退到现有 session cookie。
    3. 两者都没有或都无效时返回 401。

    bearer token 校验成功后，构造 Principal：

    ```go
    type Principal struct {
        Subject  string
        Username string
        Email    string
        Groups   []string
        Roles    []string
        AuthType string
        Provider string
        Actor    string
        Scopes   []string
    }
    ```

    字段含义：

    - `Subject`：token owner 的用户 ID。
    - `Username`：token owner 的展示名。
    - `AuthType`：`mcp_token`。
    - `Provider`：`dubbo-admin`。
    - `Actor`：`mcp-token:<tokenID>`。
    - `Scopes`：token 持有的 scope。

    ## 前端变更

    新增一个用户级 token 管理入口，位置可以是：

    - 顶部用户菜单中的“Agent Tokens”。
    - 或个人设置页面中的“MCP Tokens”。

    页面能力：

    - 创建 token。
    - 选择有效期。
    - 选择 scope。
    - 创建成功后只展示一次 token 明文。
    - 列出现有 token metadata。
    - 显示 token 是否过期、是否撤销、上次使用时间。
    - 支持撤销 token。

    前端不得保存 token 明文。用户关闭创建结果弹窗后，无法再次查看明文，只能重新创建。

    ## 配置变更

    建议新增配置：

    ```yaml
    console:
    auth:
        mcpToken:
        enabled: true
        defaultExpirationDays: 30
        maxExpirationDays: 90
        allowedScopes:
            - mcp:read
            - mcp:write
    ```

    说明：

    - `enabled` 控制是否允许用户创建 MCP token。
    - `defaultExpirationDays` 是默认有效期。
    - `maxExpirationDays` 限制用户可选择的最长有效期。
    - `allowedScopes` 限制页面和后端可授予的 scope。

    ## 测试要求

    后端测试应覆盖：

    - 登录用户可以创建 MCP token。
    - 创建 token 后只返回一次明文。
    - token store 只保存 hash。
    - 未过期 token 可以访问 `/api/v1/mcp`。
    - 过期 token 访问 `/api/v1/mcp` 返回 401。
    - 撤销 token 后访问 `/api/v1/mcp` 返回 401。
    - 无所需 scope 的 token 访问对应 MCP tool 返回 403。
    - session cookie 访问 `/api/v1/mcp` 仍然可用。
    - token last used 信息会更新。

    e2e 测试应覆盖：

    - 用户登录 Admin。
    - 用户创建 MCP token。
    - 测试用 MCP client 带 token 调用 `tools/list`。
    - 测试用 MCP client 带 token 调用只读 tool。
    - 用户撤销 token。
    - 撤销后的 token 调 MCP 失败。

    ## 安全要求

    - token 明文只展示一次。
    - 服务端只保存 hash。
    - token 必须有过期时间。
    - token 必须可撤销。
    - token 不得写入日志。
    - token 管理接口必须要求用户已登录。
    - 用户只能查看和撤销自己的 token。
    - MCP bearer token 只对 `/api/v1/mcp` 生效，不默认扩展到所有 REST API。
    - 生产环境必须使用持久化 store，避免多副本和重启导致 token 状态不一致。

    ## 兼容性

    现有 `/api/v1/mcp` session cookie 认证继续保留。现有 MCP 手动测试流程不应被破坏。

    未启用 `console.auth.mcpToken.enabled` 时，Dubbo Admin 不展示 token 管理入口，也不接受 MCP Agent Token。

    ## 已确认决策

    - Agent 用户身份标识第一阶段面向 MCP endpoint，不面向所有 REST API。
    - 第一阶段采用用户创建 MCP Access Token 的方式。
    - Agent 调用 MCP 时使用 `Authorization: Bearer <token>`。
    - token 需要服务端存储。
    - 生产环境可使用现有 MySQL/PostgreSQL 存储能力。
    - 本地开发和测试可以使用 memory store。
    - token 明文只展示一次，服务端只保存 hash。

    ## 开放问题

    - MCP token metadata 是否应存入现有 dbcommon/gorm store，还是独立 auth 表。
    - 默认 token 有效期和最大有效期分别是多少。
    - 第一阶段是否只允许 `mcp:read`，还是同时开放 `mcp:write` 预留。
    - MCP tool 与 scope 的映射关系放在 tool 注册处，还是放在独立策略表。
    - token last used 更新是否同步写入，还是异步批量更新。

cc @robocanic

[robocanic]

第一点「Admin的接入」没啥问题。第二点的token授权对象有点问题，agent模块和admin模块现在是分离的，相当于两个独立的服务。而agent模块里面是有多租户的概念的，所以想实现的其实是admin侧使用oidc登录之后，前端如何将用户身份传递到agent模块，让agent模块能够认证这个用户身份 @nagisa-kunhah

[nagisa-kunhah]

引入通用 OAuth Provider 登录能力

变更概述

为 Dubbo Admin 引入可配置的通用 OAuth Provider 登录能力，使 Admin 控制台可以接入外部身份系统、识别真实用户，并为后续 Agent 用户身份识别、审计和权限控制打基础。GitHub OAuth App 和标准 OIDC 使用统一的 Provider 配置、登录接口与回调接口。

第一阶段聚焦 Admin Web 控制台登录和 AI 用户身份认证：部署方在 console.auth.providers 中以 Provider ID 配置 GitHub OAuth App 或标准 OIDC Provider，浏览器通过统一接口发起登录。后端根据路径中的 Provider ID 查找配置、选择对应 Provider 实现并解析外部用户身份，随后统一映射为 Principal 并建立 Admin session。GitHub Provider 使用 GitHub access token 调用 /user 获取身份；标准 OIDC Provider 使用 ID Token 验签和 claims/UserInfo 获取身份。Admin Web API 继续通过 session 识别登录态；浏览器需要调用独立 AI 服务时，Admin 基于当前 session 签发短期 Access JWT，供 AI 服务独立校验。现有用户名密码登录继续保留，用于本地开发、兼容部署和紧急访问。

首个 Provider 实现采用 GitHub OAuth App，其登录流程如下：

sequenceDiagram
    autonumber
    actor User as 用户浏览器
    participant Admin as Dubbo Admin
    participant GitHub as GitHub OAuth
    participant API as GitHub API
    participant AI as AI 服务

    User->>Admin: GET /api/v1/auth/providers/github/login
    Admin->>Admin: 根据 github 查找 Provider 配置
    Admin->>Admin: 生成 state 和 PKCE verifier<br/>写入 Admin session
    Admin-->>User: 302 重定向到 GitHub authorization endpoint
    User->>GitHub: 登录并授权
    GitHub-->>User: 回调 callback，携带 code 和 state
    User->>Admin: GET /api/v1/auth/providers/github/callback
    Admin->>Admin: 校验 state 与 Provider ID
    Admin->>GitHub: 使用 code 和 PKCE verifier 换取 token
    GitHub-->>Admin: 返回 GitHub access token
    Admin->>API: GET /user，必要时 GET /user/emails
    API-->>Admin: 返回 GitHub 用户信息
    Admin->>Admin: 映射 Principal 并写入 Admin session
    Admin-->>User: 设置 session cookie 并重定向回 Admin UI

    Note over User,Admin: 后续 Admin API 继续使用 session cookie
    User->>Admin: POST /api/v1/auth/token<br/>携带 session cookie
    Admin-->>User: 返回短期 AI Access JWT
    User->>AI: Authorization: Bearer Access JWT
    AI->>AI: 使用 Admin JWKS 校验 JWT

Loading

背景

当前 Dubbo Admin 的认证方式是配置文件中的固定用户名密码。后端登录成功后将 user 写入 Gin session，后续接口通过 session 判断是否登录。

这种方式实现简单，但在生产环境有明显限制：

• 无法接入公司统一登录系统。
• 只有一个静态账号，不能识别真实用户。
• 不利于后续审计、权限控制和 Agent 代表用户访问。
• 密码由 Dubbo Admin 自己维护，不符合企业 SSO 场景。

Issue apache/dubbo-admin#1503 提到 OAuth2 覆盖 Admin 接入和 Agent 用户身份标识。本变更建立 Provider 配置 -> OAuth Provider -> Principal -> Admin session 的统一登录链路，使 GitHub OAuth App 和标准 OIDC Provider 复用相同的 HTTP 接口、Principal、session 和 AI Access JWT 链路。

目标

• 建立配置驱动的通用 OAuth Provider 登录框架，并支持 Admin Web 控制台通过 GitHub OAuth App 或标准 OIDC Provider 登录。
• 使用统一的 Provider 登录和 callback 接口，根据路径中的 Provider ID 匹配 console.auth.providers 配置。
• 支持同时配置多个 Provider，新增标准 OIDC 身份源时不需要增加后端路由或修改前端登录逻辑。
• 保留现有用户名密码登录方式。
• 将认证后的用户身份归一化为统一 Principal 模型。
• 登录方式统一只创建 Principal 和 Admin session；Admin API 继续使用 session cookie 鉴权。
• 提供基于当前 Admin session 获取短期 Access JWT 的接口，AI 服务使用该 JWT 独立校验用户身份。
• 前端不保存 OAuth Provider 的 access_token、id_token 或 refresh_token；Admin 签发的 Access JWT 仅保存在前端运行时内存。
• 提供 fake GitHub OAuth server，用于本地开发和 e2e 测试。
• 为后续 RBAC、审计和更细粒度的 Agent 用户授权留出扩展点。

非目标

• 第一阶段不维护 refresh token。
• 第一阶段不将 Admin API 的既有 session 鉴权迁移为 Bearer JWT 鉴权。
• 第一阶段不实现 token introspection、黑名单或 JWT 即时撤销。
• 第一阶段不实现 RBAC 权限拦截。
• 第一阶段只支持 github 和标准 oidc 两种 Provider 类型，不支持任意 OAuth2 Provider 或 GitHub Enterprise Server。
• 第一阶段不支持手动配置 GitHub endpoint；标准 OIDC Provider 只通过 issuer discovery 获取协议 endpoint，不支持逐项 override。
• 第一阶段不实现外部 Provider 的单点退出或 token revoke。
• 第一阶段不实现多身份源账号关联；GitHub、OIDC 和用户名密码登录产生的身份分别作为独立 Principal 处理，不根据用户名或邮箱自动合并。

当前实现位置

当前认证相关代码主要在：

• pkg/config/console/auth/config.go：认证配置结构。
• pkg/console/router/router.go：/api/v1/auth/login 和 /api/v1/auth/logout 路由。
• pkg/console/handler/auth.go：用户名密码登录和退出逻辑。
• pkg/console/component.go：Gin session 初始化和登录态校验中间件。
• ui-vue3/src/Login.vue：前端登录页。
• ui-vue3/src/api/service/login.ts：前端登录 API 封装。
• ui-vue3/src/utils/AuthUtil.ts：前端本地 auth-state 状态。

当前后端中间件只跳过路径后缀为 /login 的请求，通用 Provider 列表、登录和 callback 接入后需要改为显式匿名路径白名单。

用户流程

用户名密码登录

1. 用户打开 Admin UI。
2. 前端提交用户名密码到 POST /api/v1/auth/login。
3. 后端校验配置文件中的 console.auth.user 和 console.auth.password。
4. 校验成功后写入 Principal session。
5. 后续 Admin API 请求继续通过 session cookie 识别登录态。

OAuth Provider 登录

1. 用户打开 Admin UI。
2. 前端调用 GET /api/v1/auth/providers 获取已配置的 Provider，并动态展示登录入口。
3. 用户选择 Provider，浏览器访问 GET /api/v1/auth/providers/<provider-id>/login。
4. 后端根据 Provider ID 查找配置；不存在时返回 404。
5. 后端生成 state 和 PKCE 参数；OIDC Provider 同时生成 nonce。这些参数与 Provider ID 一起暂存到 session。
6. 后端根据配置中的 Provider 类型重定向浏览器到对应 authorization endpoint。
7. 用户在 Provider 完成登录和授权。
8. Provider 回调 GET /api/v1/auth/providers/<provider-id>/callback?code=<authorization-code>&state=<state>。
9. 后端校验 callback 路径中的 Provider ID 与 session 中保存的 Provider ID 一致，并校验 state、PKCE 以及 OIDC nonce。GitHub Provider 使用 code 换取 access token 后调用 /user 和必要时的 /user/emails；OIDC Provider 根据配置的 issuer 完成 discovery、code exchange 和 ID Token 校验，并从 claims/UserInfo 获取身份。
10. 后端创建统一 Principal 并写入 session。
11. 后端重定向用户回 Admin UI。
12. 前端调用 GET /api/v1/auth/userinfo 获取当前用户信息；该请求继续使用 Admin session。

AI Access JWT 获取与使用

1. password 和 OAuth Provider 登录均只创建 Principal 和 Admin session，不直接返回 Access JWT。
2. 前端发起需要认证的 AI 请求前，检查运行时内存中的 Access JWT 的 exp。
3. JWT 不存在、已过期或接近过期时，前端使用当前 Admin session 调用 POST /api/v1/auth/token 获取新的 Access JWT。
4. 多个并发请求同时需要新 JWT 时，前端必须合并续签，只允许一个 /api/v1/auth/token 请求，其余请求等待同一结果。
5. 前端仅在运行时内存保存 JWT，并在调用 AI 服务时设置 Authorization: Bearer <access-token>；不使用 localStorage、sessionStorage、普通 Cookie 或定时刷新任务。
6. AI 服务返回表示 Access JWT 无效的 401 时，前端强制重新获取一次 JWT，并最多重试原请求一次；403 不触发续签，且禁止无限重试。
7. 页面刷新后内存 JWT 消失；下一次需要认证的 AI 请求仍可通过有效的 Admin session 按需获取 JWT。

配置变更

建议扩展 console.auth：

console:
  auth:
    methods:
      - password
    user: admin
    password: dubbo@2025
    expirationTime: 3600
    sessionSecret: ${DUBBO_ADMIN_SESSION_SECRET}
    accessToken:
      issuer: dubbo-admin
      keyId: admin-key-1
      privateKey: ${DUBBO_ADMIN_ACCESS_TOKEN_PRIVATE_KEY}
      ttl: 1800
      audiences:
        - dubbo-admin-ai
    providers:
      github:
        type: github
        displayName: GitHub
        clientId: ${DUBBO_ADMIN_GITHUB_CLIENT_ID}
        clientSecret: ${DUBBO_ADMIN_GITHUB_CLIENT_SECRET}
        redirectUrl: http://localhost:8888/api/v1/auth/providers/github/callback
        postLoginRedirectUrl: http://localhost:8881/admin/
        scopes:
          - read:user
          - user:email
      company-sso:
        type: oidc
        displayName: Company SSO
        issuer: https://sso.example.com/realms/company
        clientId: dubbo-admin
        clientSecret: ${DUBBO_ADMIN_OIDC_CLIENT_SECRET}
        redirectUrl: http://localhost:8888/api/v1/auth/providers/company-sso/callback
        postLoginRedirectUrl: http://localhost:8881/admin/
        scopes:
          - openid
          - profile
          - email

说明：

• methods 控制用户名密码等本地认证方式；providers 中存在的 Provider 配置即为已启用的外部登录方式。
• password 登录沿用现有 user 和 password。
• providers 是以 Provider ID 为 key 的配置集合；Provider ID 同时用于登录路径、callback 路径和 Principal 身份命名空间。
• type 决定内部 Provider 实现；第一阶段支持 github 和 oidc。
• type: github 使用 GitHub OAuth endpoint 和 REST API；type: oidc 使用配置的 issuer 执行 OIDC discovery。
• redirectUrl 必须与当前 Provider ID 的统一 callback 路径一致，并注册到对应的外部 Provider。
• postLoginRedirectUrl 是 callback 成功后回到前端的地址。
• sessionSecret 替代当前硬编码的 "secret"。
• accessToken 配置 Admin 基于 session 签发给 AI 服务的 Access JWT；ttl 默认 1800 秒，AI 校验 dubbo-admin-ai audience。

协议库使用

• golang.org/x/oauth2：用于通用 OAuth2 authorization code flow，包括生成登录跳转地址、使用 code 换取 token，以及管理 clientId、clientSecret、redirectUrl 和 scopes。
• golang.org/x/oauth2/github：提供 GitHub OAuth App 的 authorization 和 token endpoint 配置。
• GitHub REST API：使用 access token 调用 /user，必要时调用 /user/emails，并将稳定的 GitHub 数值用户 ID 映射为 Principal Subject。
• github.com/coreos/go-oidc/v3/oidc 或等价成熟 OIDC 库：用于标准 OIDC Provider 完成 discovery、ID Token 验签以及 claims/UserInfo 到 Principal 的映射。

通用 HTTP handler 根据 Provider ID 查找配置，再根据 type 选择 GitHub 或 OIDC Provider 实现。Provider token 只在对应 Provider 的后端认证流程中使用；Provider 最终统一返回 Principal，后续复用 Admin session、/api/v1/auth/token 和 AI Access JWT 链路。

新增或调整的接口

新增：

• GET /api/v1/auth/providers：返回已配置 Provider 的 id 和 displayName，供登录页动态展示；不返回 client secret、issuer 等内部配置。
• GET /api/v1/auth/providers/:provider/login：根据 Provider ID 查找配置并发起对应的 authorization code flow。
• GET /api/v1/auth/providers/:provider/callback：根据 Provider ID 处理 callback 并创建本地 session。
• POST /api/v1/auth/token：使用当前 Admin session 获取供 AI 服务使用的短期 Access JWT；不接受 refresh token。
• GET /api/v1/auth/jwks：发布 AI Access JWT 的验签公钥。
• GET /api/v1/auth/userinfo：返回当前登录用户 Principal。

Provider ID 必须精确匹配 console.auth.providers 中已配置的 key；不存在的 Provider 返回 404。请求不得直接提供 issuer、authorization endpoint、token endpoint 或其他外部 URL。

保留：

• POST /api/v1/auth/login：用户名密码登录。
• POST /api/v1/auth/logout：清理 Dubbo Admin 本地 session；前端同时清除运行时内存中的 Access JWT。

调整：

• auth middleware 使用显式 allowlist。
• 允许匿名访问 Provider 列表、通用登录入口、通用 callback 和 health check。
• /api/v1 下业务接口默认要求有效的 Admin session；Access JWT 获取接口要求有效的 Admin session，AI 服务的接口由其自身验证 Access JWT。

Principal 模型

Principal 是 Dubbo Admin 内部统一的已认证用户身份模型，用于屏蔽用户名密码、GitHub OAuth 和标准 OIDC 等身份来源的差异。各登录方式完成认证后统一生成 Principal；后续 Admin session、认证中间件、/api/v1/auth/userinfo 和 /api/v1/auth/token 只依赖该模型，不直接依赖 Provider token 或 Provider 特有的用户结构。

具体实现中，Principal 定义在 pkg/console/auth/principal.go。登录成功后将其以固定的 principal key 写入现有 Admin session；认证中间件从 session 读取 Principal 并放入当前请求上下文；/api/v1/auth/userinfo 返回当前 Principal；/api/v1/auth/token 根据当前 Principal 签发 AI Access JWT。Provider token 仅用于构造 Principal，不写入 session，不返回前端，也不传递给 AI 服务。AI 服务只解析 JWT 中的身份 claims，不直接依赖该 Go 类型。

统一身份模型建议为：

type Principal struct {
    Subject  string
    Username string
    Email    string
    Groups   []string
    Roles    []string
    AuthType string
    Provider string
}

GitHub OAuth 登录时：

• Subject 使用稳定的 GitHub 数值用户 ID，并以 Provider ID 作为命名空间，格式为 <provider-id>:<id>；默认 GitHub 配置对应 github:<id>。
• Username 来自 GitHub login。
• Email 来自 /user 或 /user/emails，不存在时允许为空。
• Groups 和 Roles 第一阶段为空，不参与权限拦截。
• AuthType 为 oauth，Provider 为当前 Provider ID，例如 github。

标准 OIDC 登录时：

• Subject 来自 ID Token 的 sub，并以 Provider ID 作为命名空间，格式为 <provider-id>:<sub>，避免多个 OIDC Provider 之间发生身份冲突。
• Username、Email、Groups 和 Roles 来自 ID Token claims 或 UserInfo。
• AuthType 为 oidc，Provider 使用当前 Provider ID，例如 company-sso。

用户名密码登录时：

• Subject 使用 local:<username>，避免与外部 Provider 的用户身份冲突。
• Username 来自表单中的用户名。
• Email 允许为空。
• Groups 和 Roles 第一阶段为空，不参与权限拦截。
• AuthType 为 password。
• Provider 为 local。

Fake GitHub OAuth Server

为了本地开发和 e2e 测试，需要提供轻量 fake GitHub OAuth server。它只模拟 GitHub OAuth 和用户 API 的协议边界。

测试通过依赖注入替换 GitHub OAuth 和 API endpoint，不对生产配置开放 endpoint override。

建议位置：

• test/fakegithub/：fake GitHub OAuth server 代码。
• app/dubbo-admin/dubbo-admin-github-oauth-local.yaml：本地 GitHub OAuth 配置。

最小 endpoint：

• GET /login/oauth/authorize
• POST /login/oauth/access_token
• GET /user
• GET /user/emails

测试用户示例：

{
  "id": 123456,
  "login": "zhangsan",
  "email": "zhangsan@example.com",
  "name": "Zhang San"
}

fake server 至少支持：

• 正常登录。
• 无效 authorization code。
• state 不匹配。
• GitHub 用户 ID 缺失或用户信息格式错误。

测试要求

后端测试应覆盖：

• 未登录访问业务接口返回 401。
• 用户名密码登录仍然可用。
• Provider 列表只返回已配置 Provider 的公开信息。
• 通用登录接口能根据 Provider ID 选择 GitHub 或 OIDC 实现，未知 Provider 返回 404。
• callback 拒绝错误 state、错误 code，以及与发起登录时不一致的 Provider ID。
• GitHub Provider 正确调用 GitHub endpoint，并在 callback 成功后写入 Principal session。
• OIDC Provider 根据配置的 issuer 完成 discovery 和 ID Token 校验，并在 callback 成功后写入 Principal session。
• Provider 返回的身份统一映射为 Principal，后续 session 和 AI Access JWT 行为与 Provider 类型无关。
• 登录后访问业务接口成功。
• 未登录时无法通过 /api/v1/auth/token 获取 Access JWT。
• 使用当前 Principal 签发的 Access JWT 可通过 AI 服务验签；过期或无效 JWT 被 AI 服务拒绝。
• logout 后 session 失效，前端内存中的 Access JWT 被清除；已签发 JWT 在过期前不支持即时撤销。

e2e 测试应覆盖：

• 登录页根据 Provider 列表动态展示登录入口，用户可选择 GitHub 登录。
• fake GitHub OAuth server 自动完成授权回调。
• 前端显示 fake 用户身份。
• 登录后业务 API 请求成功。
• 首次 AI 请求按需获取 Access JWT；并发 AI 请求只触发一次 token 获取。
• AI 返回 Access JWT 无效的 401 时只重试一次，403 不触发续签。
• 页面刷新后不恢复 JWT 到浏览器持久化存储，而是在下一次 AI 请求时基于 session 重新获取。
• 退出后再次访问业务页面会回到登录页。

安全要求

• 必须校验 state。
• session 中保存的 state、PKCE verifier 和 OIDC nonce 必须与 Provider ID 绑定；callback 路径中的 Provider ID 必须与发起登录时一致。
• 推荐使用 authorization code flow + PKCE。
• GitHub OAuth App 的 authorization code flow 和 PKCE 参数参考 GitHub 官方文档：Authorizing OAuth apps。
• clientSecret 只能保存在后端配置中。
• 路径中的 Provider ID 只能用于查找后端已配置的 Provider；不得接受请求传入任意 issuer 或协议 endpoint，避免 SSRF 和恶意跳转。
• GitHub access token 只能用于后端调用 GitHub API，不得写入 session、前端 localStorage 或普通 cookie。
• 标准 OIDC Provider 必须校验 ID Token 的 signature、issuer、audience、expiration 和 nonce；ID Token 和 refresh token 不得暴露给前端。
• Admin 签发的 AI Access JWT 只可保存在前端运行时内存，默认有效期为 30 分钟；不使用 refresh token，JWT 在过期前不支持即时撤销，因此泄露后仍可能被重放至 exp。
• Admin session cookie 应设置 HttpOnly 和合适的 SameSite；HTTPS 场景必须设置 Secure。Session 只负责浏览器与 Admin 的登录态，不作为 AI 服务认证凭据。
• 任一 OAuth Provider 开启时，生产环境不得使用默认 session secret。

兼容性

现有用户名密码登录继续可用，避免破坏已有部署。默认配置可以继续只启用 password；配置在 providers 下的 GitHub 和 OIDC Provider 自动作为可用外部登录方式，并允许与 password 或其他 Provider 同时启用。新增 OIDC 身份源只需要增加 Provider 配置，不需要增加路由或修改前端登录逻辑。

前端现有 auth-state 只应作为 UI 状态缓存，不能作为后端认证凭据。前端通过 /api/v1/auth/userinfo 同步当前真实登录态，并仅在运行时内存维护 AI Access JWT。

已确认决策

• 认证设计采用配置驱动的通用 OAuth Provider 框架，第一阶段支持 GitHub OAuth App 和标准 OIDC Provider。
• 所有外部身份源使用统一的 Provider 列表、登录和 callback 接口；路径中的 Provider ID 必须匹配 console.auth.providers 中的配置。
• GitHub OAuth 与标准 OIDC 不互斥，两者统一映射 Principal 并复用 Admin session、/api/v1/auth/token 和 AI Access JWT 链路。
• 第一阶段保留用户名密码登录。
• 第一阶段允许 password、多个 GitHub 和多个 OIDC Provider 同时启用。
• OAuth2 授权码流程使用 golang.org/x/oauth2，不手写协议细节。
• GitHub 用户身份通过 /user 和必要时的 /user/emails 获取，稳定数值 ID 映射为 Principal Subject。
• 标准 OIDC Provider 根据配置的 issuer 执行 discovery，不允许由登录请求提供任意 issuer 或 endpoint。
• Principal 的 Provider 和 Subject 命名空间使用 Provider 配置 ID，以区分多个同类型 Provider。
• Admin session cookie 负责 Web 登录态；Admin API 保持现有 session 鉴权。
• Access JWT 仅用于浏览器调用 AI 服务，由 /api/v1/auth/token 基于有效 session 按需签发，默认 TTL 为 30 分钟。
• Access JWT 不持久化，不使用 refresh token 或定时刷新；并发续签合并，401 最多续签并重试一次，403 不续签。
• logout 清除 Admin session 和前端内存 JWT；第一阶段不撤销已签发的 JWT。

开放问题

• sessionSecret 的默认值和生产环境校验策略如何定义。
• GitHub OAuth scopes 是否默认包含 user:email，还是仅在部署需要邮箱时启用。
• /admin 静态资源是否需要登录态保护，还是只保护 /api/v1 业务接口。

[robocanic]

1. Admin的接入没大问题，比较完整了。有一个点，如果后面企业用户自己想接入内部的OIDC provider时，能不能通过配置的方式来快速接入？目前的方案看下来，Admin侧的抽象是统一的，但github是作为一个特殊实现来做的。
2. AI 的access token尽量用localStorage，如果放在内存，每次关闭浏览器再打开，要重新获取token。