digimon
/
template-monorepo
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
template-monorepo/deploy/zitadel/README.md

4.0 KiB
Raw Blame History

ZITADEL（dev / k6）

本機跑 k6 測試用的 ZITADEL stack（docker-compose profile: k6）。

啟動

make k6-up

會啟動 mongo / redis / mailhog / postgres / openldap / zitadel。

ZITADEL 首次啟動會 init Postgres schema 並執行 steps.yaml 預載：

  • Instance 名稱：ZITADEL
  • Org：GatewayDev
  • Admin 使用者：zitadel-admin@zitadel.localhost / Password1!
  • Service Account：zitadel-admin-sa（產生 PAT 寫到 machinekey/zitadel-admin-sa.token）

完成需 30~90 秒，可用 make k6-wait 等到 /debug/healthz 200。

PAT 取用

cat deploy/zitadel/machinekey/zitadel-admin-sa.token

把這個值塞進 etc/gateway.k6.yaml 的 Zitadel.ServiceUserToken，或用環境變數：

export ZITADEL_SERVICE_TOKEN=$(cat deploy/zitadel/machinekey/zitadel-admin-sa.token)

make k6-gateway 會自動做這件事。

密碼登入（/auth/login）

ZITADEL v2 預設停用 OAuth Resource Owner Password Grant（unsupported_grant_type）。 本 repo 的 Gateway 在未設定 OAuthClientID / OAuthClientSecret 時，會改用 v2 Sessions API（PAT）驗證密碼，無需額外建立 OIDC App。

若要在正式環境使用 ROPG，請自行建立 OIDC Application 並設定：

export ZITADEL_OAUTH_CLIENT_ID=...
export ZITADEL_OAUTH_CLIENT_SECRET=...

重設

make k6-down                                    # 停容器（保留 volume）
docker volume rm template-monorepo_postgres_data   # 清 ZITADEL 資料
rm deploy/zitadel/machinekey/zitadel-admin-sa.*    # 清 PAT

Google / LDAP 聯邦登入（Social + LDAP IdP）

Gateway 不直接 bind LDAP；登入／註冊走 ZITADEL OIDC，並以 idp_id 指定外部 IdP。

1. 建立 OIDC Application（User Agent）

在 ZITADEL Console → Project → Applications → User Agent：

  • Redirect URIs（本機前端，經 Vite proxy 打 API）：
    • http://localhost:5173/auth/callback/login
    • http://localhost:5173/auth/callback/register
  • Grant types：Authorization Code
  • Response type：code
  • Scopes：openid profile email

記下 Client ID / Client Secret，寫入 Gateway：

export ZITADEL_OAUTH_CLIENT_ID=...
export ZITADEL_OAUTH_CLIENT_SECRET=...

或 etc/gateway.k6.yaml 的 Zitadel.OAuthClientID / OAuthClientSecret。

2. 設定 Google IdP

Console → Settings → Identity Providers → Google → 建立後複製 IdP ID：

Zitadel:
  GoogleIdPID: "<zitadel-google-idp-id>"
  # Google OAuth client 也可放在 Zitadel IdP 設定內

3. 設定 LDAP IdP（本機 OpenLDAP）

make k6-up 已含測試目錄，帳號與 ZITADEL 欄位對照見 deploy/openldap/README.md。

摘要（在 ZITADEL Console 建 Generic LDAP IdP）：

欄位 值
Server ldap://openldap:389
Bind DN cn=admin,dc=gateway,dc=local
Bind password admin
User base ou=people,dc=gateway,dc=local
Login uid=alice，密碼=Password1!

建立後複製 IdP ID → Zitadel.LdapIdPID，並確認已設定 OIDC App（§1）。

Zitadel:
  LdapIdPID: "<zitadel-ldap-idp-id>"

驗證目錄：make ldap-test

4. 行為摘要

流程 Google LDAP
登入 需已有會員；否則 404「請先註冊」 首登可 EnsureFromLDAP 自動建立會員
註冊 EnsureFromOIDC + 邀請碼 支援但通常改走 LDAP 登入
TOTP 已啟用 callback 回 mfa_required，前端導回登入頁輸入 TOTP 同左

重啟 Gateway：make dev-restart-gateway（或 make k6-gateway）。

端點

不可帶上 prod

MasterkeyNeedsToHave32Characters 與 steps.yaml 內的密碼都是固定 dev 值，只能本機用。