跳到主要内容

配置外部 Casdoor

CSGHub 默认自带一个 Casdoor 实例,会自行初始化组织、应用、JWT 签名证书和管理员。本文说明在 Kubernetes(Helm)部署中如何改用自行运维的 Casdoor 实例(global.casdoor.enabled: false)。

使用外部 Casdoor 时,chart 不再创建任何 Casdoor 对象。需先在 Casdoor 中创建下列对象,再将生成的凭据填入 chart values。

chart 假定 Casdoor 的 schema 与内置镜像(casbin/casdoor:3.62.1)兼容。更早的版本可能缺少此处提及的部分配置项(例如 Signin session 开关),无法正确对接 CSGHub。

1. 前置条件​

  • 一个可访问的 Casdoor 实例。生产环境建议使用 HTTPS;本地或内网测试可直接使用 HTTP。endpoint 必须同时可从浏览器和 CSGHub 的 server Pod 访问,且 Casdoor 的 origin 配置必须等于 global.casdoor.external.endpoint 中填写的 URL,scheme 亦须一致。
  • 该 Casdoor 实例的管理员权限。
  • CSGHub 的访问地址(global.gateway.external.domain,TLS 按实际配置)。用于拼接 redirect URI。
  • 一个保存 JWT 签名证书的 Kubernetes Secret(在第 4 步创建)。

2. 确认 endpoint​

curl -sS https://sso.example.com/.well-known/openid-configuration | jq -r .issuer

issuer 必须等于 https://sso.example.com,结尾不带斜杠。若不一致,请先修正 Casdoor 的 origin / 前端地址后再继续。

Casdoor 使用 origin 生成 issuer 及 discovery 中的所有 endpoint(authorization_endpoint、token_endpoint、userinfo_endpoint)。集群内组件即使用这些 endpoint,Temporal 控制台还会使用 global.casdoor.external.endpoint 校验 ID token 的 issuer。因此,若 origin 配置为 localhost 或其他集群内无法访问的地址,最终会在换取 token 时失败。

3. 创建组织​

Casdoor:Organizations → Add。

  • Name:OpenCSG(也可使用自定义名称,并相应修改 global.casdoor.organization)
  • Password type:bcrypt,salt OpenCSG
  • Account items:保留 Tag 和 Is admin(详见下节)

Default application:暂时留空。下拉框仅列出已存在的应用,CSGHub 需在第 5 步创建。其余属性(logo、主题、语言、密码策略等)可按需设置,不影响 CSGHub 对接。

组织设置

Account items​

组织的 Account items 表决定注册及个人资料页中显示的用户字段。CSGHub 会读取用户的 Tag 字段和管理员标记,因此这两行必须保留在表中。

打开 Organizations → OpenCSG → Edit,向下滚动至 Account items。

Account items 表格

表格默认已填好完整条目,请定位以下两行:

NameVisibleView ruleModify rule
Tag开PublicAdmin
Is admin开AdminAdmin

以上为 Casdoor 的默认值,也是内置部署的配置,新建组织无需修改。编辑表格时需注意:

  • Name 列为已知条目的下拉框,不可任意输入。若某行被删除,点击 Account items 卡片标题栏的 Add,从下拉框中选择 Tag / Is admin。存储的为英文 key,切换界面语言不受影响。
  • View rule / Modify rule 两列仅在 Visible 开启时显示。Is admin 属于管理项,其 Modify rule 仅可选 Admin / Immutable。

删除任意一行不影响登录,但该字段将从 CSGHub 个人资料页中消失。

4. 创建 JWT 签名证书​

Casdoor:Certs → Add。

  • Organization:OpenCSG
  • Name:csghub-cert
  • Scope:JWT
  • Type:x509
  • Algorithm:RS256,bit size 4096

JWT 签名证书

Casdoor 将生成密钥对。请导出公钥证书(非 Casdoor endpoint 的 HTTPS 证书),并创建 Secret:

# tls.crt 必须为 csghub-cert 签名密钥对应的 PEM 公钥证书
kubectl create secret generic csghub-casdoor-cert \
--namespace csghub \
--from-file=tls.crt=./csghub-cert.crt

chart 会将此 Secret 挂载至 server、user、executor 三个 Pod,并将 STARHUB_SERVER_CASDOOR_CERTIFICATE 指向 tls.crt。

5. 创建 CSGHub 应用​

Casdoor:Applications → Add。相关字段分布在多个 tab 中。

Basic

  • Name:CSGHub(或修改 global.casdoor.application)
  • Organization:OpenCSG
  • Cert:csghub-cert
  • Redirect URI:<csghub-endpoint>/api/v1/callback/casdoor

CSGHub 应用:Basic tab

OIDC/OAuth

  • Token format:JWT
  • Grant types:Authorization Code

CSGHub 应用:OIDC/OAuth tab

Authentication

  • Signin session:开启
  • Enable signup:开启

CSGHub 应用:Authentication tab

UI Customization

  • Organization choice mode:Select

CSGHub 应用:UI Customization tab

若创建应用时 Cert 下拉框中无法选择 csghub-cert,请先保存其他字段(Organization 为必填项),重新打开应用后再选择证书。

复制 Basic tab 中生成的 Client ID 和 Client secret,分别填入 global.casdoor.external.applications.portal.clientId / clientSecret。

最后将 Organizations → OpenCSG → Edit → Default application 设置为 CSGHub。第 3 步暂时留空,是因为此时该应用尚未创建。

Default application

6. 创建 Admin 应用​

Temporal 和 Superset 控制台启用时使用。tab 划分与上文相同。

Casdoor:Applications → Add。

Basic

  • Name:Admin
  • Organization:OpenCSG
  • Cert:csghub-cert
  • Redirect URIs:
    • <csghub-endpoint>/-/temporal/auth/sso/callback
    • <csghub-endpoint>/-/superset/oauth-authorized/casdoor

Admin 应用:Basic tab

OIDC/OAuth

  • Token format:JWT
  • Grant types:Authorization Code

Admin 应用:OIDC/OAuth tab

Authentication

  • Signin session:开启
  • Enable signup:关闭

Admin 应用:Authentication tab

将其 client ID 和 secret 填入 global.casdoor.external.applications.admin.clientId / clientSecret。若启用了 Temporal 控制台或 Superset 但未填写这两个值,chart 将在渲染阶段直接失败。

7. 创建 CSGShip 应用(可选)​

仅在 CSGShip 对接此外部实例时需要。

Basic

  • Name:CSGShip
  • Organization:OpenCSG
  • Cert:csghub-cert
  • Redirect URI:<csgship-webAPI-endpoint>/api/v1/account/casdoor/login/callback

CSGShip 应用:Basic tab

OIDC/OAuth

  • Token format:JWT
  • Grant types:Authorization Code

CSGShip 应用:OIDC/OAuth tab

将凭据填入 global.casdoor.external.applications.csgship.clientId / clientSecret。

CSGHub umbrella 中的 CSGShip:umbrella 将 CSGShip 作为已发布的子 chart 引入,当前固定的版本尚不支持外部 Casdoor。因此,chart 会拒绝 global.casdoor.enabled=false 与 csgship.enabled=true 同时出现。请保持 csgship 关闭,或待 CSGShip chart 发布 global.casdoor 支持后再单独部署。

8. 创建 provider​

应用按名称引用 provider。请按需在 Providers 下创建:

  • Email_Provider(category Email):注册邮件流程需要。
  • Captcha_Provider(category Captcha):默认登录页会引用。
  • GitLab_Provider(category OAuth,type Custom):仅在使用 GitLab 登录时需要。

Providers

若应用引用了不存在的 provider,登录页将报错。

9. 创建第一个管理员​

Users 页面在顶部组织选择器当前选中的组织中创建新用户,而非在创建时选择的组织。默认选中 All,此时点击 Users → Add 会尝试在 built-in 组织中创建用户,Casdoor 将拒绝该操作:

adding a new user to the 'built-in' organization is currently disabled ... all users in the 'built-in' organization are global administrators in Casdoor

不要通过为 built-in 开启 Has privilege consent 来规避此限制:该设置会将用户授予 Casdoor 全局管理员权限,并非 CSGHub 所需。请按以下步骤操作:

  1. 在顶部导航栏右侧(语言/主题按钮与账号菜单之间)找到组织下拉框,默认显示 All,将其切换为 OpenCSG。该下拉框仅对管理员可见,且在窄窗口(移动端布局)下隐藏;若未显示,请加宽浏览器窗口。

    组织选择器

  2. 点击 Users → Add。Casdoor 将在 OpenCSG 组织中创建 user_<随机串> 并打开其编辑页。

    OpenCSG 里的用户

  3. 将 Name 设为 root,Tag 设为 is_admin,勾选 Is admin,保存。

    root 用户字段

    Is admin 勾选框

用户名必须为 root:CSGHub 仅在 root 首次登录时将其提升为管理员。其他用户名的管理员不会被自动提升。

10. 配置 chart​

开关、组织/应用名称和外部配置均位于 global.casdoor,因为 Casdoor 实例与部署中的其他 chart 共用:

global:
casdoor:
enabled: false # false = 使用外部实例
organization: "OpenCSG" # CSGHub 认证使用的组织
application: "CSGHub" # CSGHub 认证使用的应用
external:
endpoint: "https://sso.example.com"
existingSecret: "csghub-casdoor-cert"
applications:
portal: # CSGHub 门户登录使用的应用
clientId: "<portal client id>"
clientSecret: "<portal client secret>"
admin: # 启用 Temporal 控制台或 Superset 时必填
clientId: "<admin client id>"
clientSecret: "<admin client secret>"
csgship: # 仅独立部署 CSGShip 时需要
clientId: "<csgship client id>"
clientSecret: "<csgship client secret>"

applications 下的键表示用途(role),而非 Casdoor 应用名;外部实例中的应用可任意命名。portal 为 CSGHub 门户登录使用的应用(其名称填入 global.casdoor.application),admin 为 Temporal 和 Superset 控制台使用的应用,csgship 为 CSGShip 使用的应用。

global.casdoor.external.endpoint 会覆盖所有使用 Casdoor URL 的位置:server configmap、门户登录 URL、CORS、Temporal 和 Superset 的 OIDC 配置,以及重定向路由。

global.casdoor.enabled=false 时,chart 不会创建任何 Casdoor 对象。existingSecret 或 applications 中的凭据缺失会导致渲染失败,可在安装阶段发现;endpoint 缺失不会中断渲染,但会回落到内置 Casdoor 的地址,运行时无法登录,因此同样必须配置:

缺失的值何时必须配置
global.casdoor.external.endpoint始终
global.casdoor.external.existingSecretCSGHub chart(server、user、executor 需挂载 JWT 证书);独立 CSGShip 不需要
global.casdoor.external.applications.portal.clientId / clientSecret始终
global.casdoor.external.applications.admin.clientId / clientSecret启用 Temporal 控制台或 Superset 时
global.casdoor.external.applications.csgship.clientId / clientSecret独立部署 CSGShip 时

11. 可选:将 CSGHub 管理员角色同步到 Casdoor​

内置部署通过 PostgreSQL 外部数据包装器(FDW)使 Casdoor 的 user.is_admin 与 CSGHub 的 role_mask 保持一致。使用外部 Casdoor 时不会自动配置,需自行执行。

外部 Casdoor 数据库必须满足:

  1. 可被内置 PostgreSQL 访问。
  2. 存在角色 csghub_server_fdw,具备 CONNECT、schema public 的 USAGE,以及 public."user" 的 SELECT, UPDATE。

在外部 Casdoor 数据库上执行 fdw-grant.sql 完成授权。该脚本创建的 csghub_server_fdw 角色无密码;跨实例访问需为其设置密码,下一步的 user mapping 须使用相同值:

ALTER ROLE csghub_server_fdw PASSWORD '<password>';

然后在 CSGHub server 数据库中创建 foreign server / trigger,将 host、port、库名和密码替换为你的 Casdoor 值:

CREATE EXTENSION IF NOT EXISTS postgres_fdw;

CREATE SERVER csghub_casdoor_fdw FOREIGN DATA WRAPPER postgres_fdw
OPTIONS (host '<casdoor-db-host>', port '5432', dbname '<casdoor-db>');

CREATE USER MAPPING FOR <csghub-server-db-user>
SERVER csghub_casdoor_fdw
OPTIONS (user 'csghub_server_fdw', password '<password>');

CREATE FOREIGN TABLE public.casdoor_users (id varchar(100), is_admin boolean)
SERVER csghub_casdoor_fdw OPTIONS (schema_name 'public', table_name 'user');

触发器函数、触发器和回填与 1789619535_sync_role_mask_admin.sql 完全一致。该文件中的 foreign server、user mapping 和 foreign table 与上文重复,请跳过这些部分,仅执行后续的触发器函数、触发器和回填。

跳过这一步,CSGHub 仍可正常工作,但在 CSGHub 中变更管理员不会同步至 Casdoor,这些用户将无法打开 Temporal 或 Superset 控制台。

12. 安装并验证​

helm upgrade --install csghub csghub/csghub \
--namespace csghub \
-f values.yaml

请按顺序检查:

  1. Endpoint:kubectl -n csghub get configmap <release>-core -o yaml | grep CASDOOR 可看到已配置的 endpoint、组织、应用和 client ID。
  2. 证书:server Pod 已挂载 tls.crt,内容为 csghub-cert 的公钥证书。
  3. 登录:打开 CSGHub 界面登录,确认浏览器返回 /api/v1/callback/casdoor 且无报错。
  4. Token 校验:登录后 server 日志中无 401 / 证书错误。
  5. 可选模块:打开 Temporal 控制台(若已启用),确认 SSO 可登录,且不会在每次访问时要求重新认证。

verify.sh 可对运行中的 release 执行上述只读检查。

排障​

现象可能原因
跳转至 Casdoor 后返回登录页tls.crt 为 HTTPS 证书而非 csghub-cert 的 JWT 证书;或 client ID / secret 与应用不匹配。
Casdoor 返回 invalid redirect_uriredirect URI 与 CSGHub 访问地址的 scheme / host / port 不完全一致。
invalid_clientclient ID 或 secret 复制自其他应用。
Temporal SSO 换取 token 失败,报错中的地址与配置不符Casdoor 的 origin 与 global.casdoor.external.endpoint 不一致,或修改 origin 后未重启 Temporal 控制台。对齐 origin 后重启 Temporal Deployment。
可登录,但每次进入 Temporal 控制台均需重新认证CSGHub / Admin 应用的 Signin session(Authentication tab)未开启。
在 CSGHub 中变更管理员后 Casdoor 无变化未配置 FDW 同步(第 11 步)。
server 日志出现 x509: certificate signed by unknown authorityCasdoor endpoint 使用私有 CA,server 容器不信任。请改用公共信任的证书,或通过 server 服务的 volumes / environments 覆盖挂载 CA 并设置 SSL_CERT_FILE。
登录页显示 provider 错误应用引用了不存在的 provider(第 8 步)。
安装报 global.casdoor.enabled=false cannot be combined with csgship.enabled=trueumbrella 中的 CSGShip 子 chart 尚不支持外部 Casdoor(第 7 步)。请保持 csgship 关闭。