From 013f744f0b71d3b225f3c19aa1f978aa24afc6a1 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Mon, 21 Sep 2026 10:07:05 +0800 Subject: [PATCH] docs(deploy): clarify Feishu OAuth configuration and validation Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/03-authentication-design.md | 2 +- docs/09-deployment.md | 31 +++++++++++++++++++ scripts/tests/validate-release-config-test.sh | 22 +++++++++++++ scripts/validate-release-config.sh | 15 +++++++++ 4 files changed, 69 insertions(+), 1 deletion(-) diff --git a/docs/03-authentication-design.md b/docs/03-authentication-design.md index c609f4f1..4fcb8b30 100644 --- a/docs/03-authentication-design.md +++ b/docs/03-authentication-design.md @@ -330,7 +330,7 @@ OAUTH2_FEISHU_USER_INFO_URI=https://open.feishu.cn/open-apis/authen/v1/user_info 选择对应的标准 token endpoint；如需代理、区域或私有化 endpoint，可通过 `OAUTH2_FEISHU_TOKEN_URI` 覆盖。授权和 userinfo endpoint 也分别通过 `OAUTH2_FEISHU_AUTHORIZATION_URI`、`OAUTH2_FEISHU_USER_INFO_URI` 配置。协议版本不合法 -时应用启动失败。不会在 v3 失败后自动使用 v2，因为 authorization code 只能使用一次， +时发布配置校验失败，应用也会拒绝启动。不会在 v3 失败后自动使用 v2，因为 authorization code 只能使用一次， 自动重试可能造成重复请求并掩盖配置错误。旧的 `OAUTH2_FEISHU_AUTHORIZE_URI` 和 `OAUTH2_FEISHU_BASE_URI` 仍作为 base-URI 兼容回退，但新部署应使用完整 endpoint 变量。 diff --git a/docs/09-deployment.md b/docs/09-deployment.md index 23ff0e8a..bbceba19 100644 --- a/docs/09-deployment.md +++ b/docs/09-deployment.md @@ -303,6 +303,37 @@ services: 确认，因此 `emailVerified` 恒为 false；若在 `application.yml` 中把 `skillhub.access-policy.mode` 设为 `EMAIL_DOMAIN`，该策略会拒绝所有未验证邮箱， 飞书登录将一律失败。启用飞书时请保留默认的 `OPEN` 或改用其他准入模式。 + + 启用飞书前，使用一个测试租户完成一次真实回调验收。不要把真实 client secret + 写入仓库、报告或聊天记录；只在受控的 `.env.release`、CI Secret 或 Kubernetes + Secret 中注入： + + 1. 在飞书自建应用中登记 + `https://<公网域名>/login/oauth2/code/feishu`，并开启用户信息所需权限。 + 2. 在受控环境设置 `OAUTH2_FEISHU_CLIENT_ID`、`OAUTH2_FEISHU_CLIENT_SECRET`，确认 + `OAUTH2_FEISHU_PROTOCOL_VERSION` 与 token endpoint 匹配，然后运行： + + ```bash + make validate-release-config + docker compose --env-file .env.release -f compose.release.yml up -d + curl -fsS http://127.0.0.1:8080/actuator/health + curl -fsS http://127.0.0.1:8080/api/v1/auth/methods + ``` + + 3. 在登录页选择“飞书”，确认浏览器跳转到配置的授权域名；完成授权后应回到 + `/login/oauth2/code/feishu`，最终进入 `/` 或原始的 root-relative `returnTo`。 + 4. 用同一个飞书账号再次登录，确认仍绑定同一个 SkillHub 账号；再用已禁用的 + SkillHub 账号登录，预期跳转 `/access-denied`，且不创建新 Session。 + 5. 检查日志中只有 provider、HTTP 状态、错误码和阶段信息，不应出现 client secret、 + authorization code、access token、`open_id` 或上游错误文本： + + ```bash + docker compose -f compose.release.yml logs --tail=200 server \ + | rg -i 'client_secret|authorization code|access[_-]?token|open_id|secret|token' + ``` + + 本地 mock 回调只能证明 SkillHub 与协议形状的集成，不能替代上述真实租户验收。 + 没有可用飞书租户时，应将该项记录为“未验证”，不要宣称 Feishu 登录已通过。 - 如果要启用密码重置验证码邮件，参见：`docs/19-smtp-password-reset-email-setup.md` ## 8 OIDC 登录配置 diff --git a/scripts/tests/validate-release-config-test.sh b/scripts/tests/validate-release-config-test.sh index d26b0145..be16f291 100755 --- a/scripts/tests/validate-release-config-test.sh +++ b/scripts/tests/validate-release-config-test.sh @@ -70,6 +70,28 @@ valid_env="$tmp/valid.env" write_env "$valid_env" "release-download-secret-32-bytes-minimum" "$SCRIPT" "$valid_env" >/dev/null +valid_feishu_env="$tmp/valid-feishu.env" +write_env "$valid_feishu_env" "release-download-secret-32-bytes-minimum" +cat >>"$valid_feishu_env" <<'EOF' +OAUTH2_FEISHU_CLIENT_ID=cli_test +OAUTH2_FEISHU_CLIENT_SECRET=secret_test +OAUTH2_FEISHU_PROTOCOL_VERSION=v2 +OAUTH2_FEISHU_AUTHORIZATION_URI=https://accounts.feishu.cn/open-apis/authen/v1/authorize +OAUTH2_FEISHU_TOKEN_URI=https://open.feishu.cn/open-apis/authen/v2/oauth/token +OAUTH2_FEISHU_USER_INFO_URI=https://open.feishu.cn/open-apis/authen/v1/user_info +EOF +"$SCRIPT" "$valid_feishu_env" >/dev/null + +invalid_feishu_protocol_env="$tmp/invalid-feishu-protocol.env" +write_env "$invalid_feishu_protocol_env" "release-download-secret-32-bytes-minimum" +printf '%s\n' "OAUTH2_FEISHU_PROTOCOL_VERSION=v1" >>"$invalid_feishu_protocol_env" +expect_fail "$invalid_feishu_protocol_env" "OAUTH2_FEISHU_PROTOCOL_VERSION must be either v2 or v3" + +invalid_feishu_endpoint_env="$tmp/invalid-feishu-endpoint.env" +write_env "$invalid_feishu_endpoint_env" "release-download-secret-32-bytes-minimum" +printf '%s\n' "OAUTH2_FEISHU_TOKEN_URI=https://open.feishu.cn/oauth/token?tenant=prod" >>"$invalid_feishu_endpoint_env" +expect_fail "$invalid_feishu_endpoint_env" "OAUTH2_FEISHU_TOKEN_URI must not contain a query" + disabled_builtin_skills_env="$tmp/disabled-builtin-skills.env" write_env "$disabled_builtin_skills_env" "release-download-secret-32-bytes-minimum" printf '%s\n' "SKILLHUB_BUILTIN_SKILLS_ENABLED=false" >>"$disabled_builtin_skills_env" diff --git a/scripts/validate-release-config.sh b/scripts/validate-release-config.sh index 9a64729f..03ba596b 100755 --- a/scripts/validate-release-config.sh +++ b/scripts/validate-release-config.sh @@ -391,6 +391,21 @@ for provider in GITHUB GITLAB FEISHU; do fi done +feishu_protocol="${OAUTH2_FEISHU_PROTOCOL_VERSION:-v3}" +case "$feishu_protocol" in + v2|v3) ;; + *) error "OAUTH2_FEISHU_PROTOCOL_VERSION must be either v2 or v3" ;; +esac + +# OAuth endpoints are sent directly to the provider. Validate them here so a +# typo fails before the release container starts. +for feishu_endpoint in OAUTH2_FEISHU_AUTHORIZATION_URI OAUTH2_FEISHU_TOKEN_URI OAUTH2_FEISHU_USER_INFO_URI; do + eval "feishu_endpoint_value=\${$feishu_endpoint:-}" + if [ -n "$feishu_endpoint_value" ]; then + validate_url "$feishu_endpoint" + fi +done + if [ "$errors" -gt 0 ]; then echo "Release config validation failed: $errors error(s), $warnings warning(s)." >&2 exit 1