ZITADEL 配置清单（SURIED）

本文件用于在新实例上完整、无误地复现 Zitadel 配置，确保当前 Convex + Vue 前端能正常登录、识别租户与角色。

1. 基本信息

  • Zitadel 域名（Authority/Issuer）: https://auth.suried.com
  • 应用类型: SPA (Single Page Application)
  • 授权方式: OIDC Authorization Code + PKCE

2. Zitadel 控制台设置（必做）

2.1 创建应用

  • 进入 Zitadel Console → Project → Applications → Create
  • 类型选择 SPA
  • 启用 PKCE
  • 生成 Client ID（例如：5347547457453745）

2.2 Redirect URI（必须绝对路径）

必须允许：

  • http://localhost:5173/auth/callback
  • http://localhost:5173/
  • http://localhost:5173/auth/silent （可选，用于 silent renew）

生产环境要额外加入：

  • https://<YOUR_DOMAIN>/auth/callback
  • https://<YOUR_DOMAIN>/
  • https://<YOUR_DOMAIN>/auth/silent （可选）

2.3 CORS Allowed Origins

  • http://localhost:5173
  • https://<YOUR_DOMAIN>

2.4 Token / Claim 配置

确保 ID Token 包含以下字段：

  • sub
  • iss
  • aud（包含该 SPA 的 Client ID）
  • 租户标识 Claim（推荐）：
    • urn:zitadel:iam:org:id

如需角色识别，确保以下任一字段存在：

  • roles
  • groups
  • urn:zitadel:iam:org:project:roles
  • urn:zitadel:iam:org:roles

3. Convex 后端环境变量（必须设置）

注意：Convex 后端不会读取前端 .env，必须显式设置。

在 Convex 控制台或使用命令设置：

convex env set ZITADEL_AUTHORITY https://auth.suried.com
convex env set ZITADEL_CLIENT_ID <YOUR_CLIENT_ID>
convex env set ZITADEL_JWKS_URL https://auth.suried.com/oauth/v2/keys
convex env set CONVEX_TENANT_CLAIM urn:zitadel:iam:org:id

# 如有多 aud 且校验失败，可临时打开（仅开发）
convex env set ZITADEL_SKIP_AUD_CHECK true

4. 前端环境变量（.env.local）

VITE_OIDC_AUTHORITY=https://auth.suried.com
VITE_OIDC_CLIENT_ID=<YOUR_CLIENT_ID>
VITE_OIDC_SCOPE="openid profile email"
VITE_OIDC_TENANT_CLAIM=urn:zitadel:iam:org:id

# 可选：覆盖默认回调地址
# VITE_OIDC_REDIRECT_URI=http://localhost:5173/auth/callback
# VITE_OIDC_POST_LOGOUT_REDIRECT_URI=http://localhost:5173/
# VITE_OIDC_SILENT_REDIRECT_URI=http://localhost:5173/auth/silent

5. 验证方式（自检）

登录后在应用里查看：

  • Has ID Token: true
  • Issuer (iss): https://auth.suried.com
  • Audience (aud): 包含 Client ID
  • Roles: 可见角色列表

如果报 Unauthorized：

  • 先确认 ZITADEL_AUTHORITY 与 ZITADEL_CLIENT_ID 在 Convex 后端已设置
  • 确保 aud 包含当前 Client ID
  • 若 aud 为数组且包含多个 Client ID，请临时启用 ZITADEL_SKIP_AUD_CHECK=true

只要按本文件配置，新的 Zitadel 实例可以完整复现，不会因缺少环境变量或 Claim 导致鉴权失败。

标签: none

添加新评论