跳到主要内容

认证与访问控制配置

SupKube 支持 OIDC 单点登录、静态 API 令牌、HTTP Basic 三种认证方式，并内置基于角色的访问控制（RBAC，Role-Based Access Control）。

前置条件​

已完成安装并能访问 SupKube 的 Web 界面。

三种认证方式如何被识别​

所有 /api/v1/* 接口（除公开探针等少数例外）都要求 Authorization 请求头，后端按内容自动判断使用哪种方式，判断逻辑是固定的、单向的，不会互相回退：

                    Authorization 请求头
                            │
            ┌───────────────┴───────────────┐
        Basic <base64>                Bearer <token>
            │                               │
            ▼                               ▼
      ┌───────────┐            能按 "." 拆成三段非空？
      │ htpasswd  │                         │
      │   校验     │          ┌──────────────┴──────────────┐
      └───────────┘        像 JWT                      不像 JWT
                              │                            │
                              ▼                            ▼
                     ┌─────────────────┐        ┌────────────────────┐
                     │  OIDC JWT 校验   │        │  静态令牌哈希比对    │
                     │  （JWKS 验签）   │        │  （SHA-256）        │
                     └────────┬────────┘        └─────────┬──────────┘
                        失败 │ ╳ 不回退           失败 │ ╳ 不回退
                              ▼                            ▼
                             401                          401

「不回退」是安全要求而非实现细节：若 JWT 验签失败后还允许回退去查静态令牌表，攻击者便可构造结构像 JWT、实则用于撞哈希的令牌绕过签名校验。

  • Authorization: Basic <base64> → 走 HTTP Basic（htpasswd 校验）。
  • Authorization: Bearer <token> → 先做一次结构判断：如果 <token> 能按 . 拆成三段非空内容（结构上像一个 JWT），就只按 OIDC JWT 校验，校验失败直接拒绝，不会再尝试当作静态令牌；否则只按静态 API 令牌（SHA-256 哈希比对）校验，失败也不会回退去当 JWT 解析。
默认内置一个演示账号，生产环境必须处理

Helm Chart 默认启用内置的 Dex 身份代理（auth.dex.enabled=true）并附带一个静态演示账号：用户名 admin（邮箱 admin@supkube.local），密码 admin。这意味着任何新装的 SupKube 默认就能用这个账号登录。生产环境请至少做到以下一项：接入真实身份提供方（IdP）后清空 auth.dex.staticPasswords；或修改该密码对应的哈希；或直接设置 auth.dex.enabled=false 改用外部 OIDC。

内置 Dex 与外部 IdP 的三种部署形态​

形态配置适用场景
内置 Dex + 演示账号auth.dex.enabled=true，不配置 connectors本地评估/演示
内置 Dex + 上游连接器auth.dex.enabled=true，配置 auth.dex.connectors（如 Keycloak、Okta、Azure AD）生产，希望由 SupKube 托管 Dex
外部 OIDCauth.dex.enabled=false，配置 auth.oidc.issuerURL生产，已有 Dex/Keycloak 等身份平台

以接入 Keycloak 为例（写入 values.yaml 或通过 -f 传入自定义文件）：

auth:
  dex:
    enabled: true
    publicURL: "http://example.com"   # 必填，见下方安装期校验
    connectors:
      - type: oidc
        id: keycloak
        name: "使用 Keycloak 登录"
        config:
          issuer: https://keycloak.example.com/realms/master
          clientID: supkube
          clientSecret: "<KEYCLOAK_CLIENT_SECRET>"
          redirectURI: http://example.com/dex/callback
          scopes: [openid, profile, email, groups]
          getUserInfo: true
publicURL 是安装期强制校验项

auth.dex.enabled=true 时必须显式设置 auth.dex.publicURL（浏览器访问 SupKube 使用的外部地址），否则 helm install / helm upgrade 在渲染阶段就会直接失败——这是刻意的 fail-fast 设计，因为早期版本的 localhost 默认值会导致登录后静默跳转失败。若同时设置了 frontend.basePath（非 /），publicURL 的路径部分必须与 basePath 一致，否则同样会安装失败。

RBAC（基于角色的访问控制）​

三个角色单调递增：viewer < editor < admin。

  • viewer：只读全部资源（审计日志、RBAC 绑定关系除外）。
  • editor：在 viewer 基础上可以创建/修改/删除 Backup、Restore、Schedule、Import Policy，但仅限于其命名空间作用域（namespaceScope）内的命名空间。
  • admin：不受命名空间限制，额外拥有 BSL/VSL、Transform Set、集群注册、跨存储位置复制、清理孤儿资源、审计日志等管理权限。

角色通过 auth.rbac.bindings 按 OIDC 的 groups 声明或用户名/邮箱匹配：

auth:
  rbac:
    enabled: true
    defaultRole: "viewer"
    bindings:
      - group: platform-admins
        role: admin
      - group: app-team-postgres
        role: editor
        namespaces: [postgres-prod, postgres-staging]
      - group: auditors
        role: viewer

auth.rbac.enabled=false 时（旧版本默认行为），所有已认证用户一律按 admin 处理，RBAC 中间件退化为空操作——不建议在生产环境使用。

静态 API 令牌（脚本 / CI 用）​

用于脚本、CI/CD、MCP Server 等非交互场景，令牌本身带有固定角色，不经过 RBAC 绑定表解析：

# 在您自己的工作站上生成明文令牌与其哈希，明文只交给调用方保管
PLAIN=$(openssl rand -hex 32)
echo "明文令牌（请安全保存，不会再次显示）：$PLAIN"
echo -n "$PLAIN" | sha256sum
auth:
  staticTokens:
    enabled: true
    tokens:
      - name: ci-pipeline
        hash: "<上一步得到的 sha256 十六进制值>"
        role: editor
        namespaces: [shop-prod]

HTTP Basic（无 IdP 环境兜底）​

htpasswd -bnBC 10 alice '<password>' > htpasswd
kubectl create secret generic supkube-htpasswd -n supkube --from-file=htpasswd
auth:
  basic:
    enabled: true
    secretName: supkube-htpasswd

仅接受 bcrypt 格式的哈希条目（htpasswd 的 -B 参数），MD5/SHA1 格式的行会在启动时被跳过并记录警告。

验证方法​

# 未带凭据应返回 401
curl -s -o /dev/null -w '%{http_code}\n' http://<your-supkube-host>/api/v1/auth/me

# 带上有效 token 后应返回你的身份、角色与命名空间作用域
curl -s -H "Authorization: Bearer <token>" http://<your-supkube-host>/api/v1/auth/me

相关文档​