在 Catalyst 平台上实现用户登录/注册与第三方认证时…

在 Zoho Catalyst 上开发用户认证（登录、注册、社交登录、OAuth、第三方 IdP）时，按流程选择认证方式并规避 ZAID 环境陷阱。

适用场景

解决思路

1. 本地开发认证功能时，必须通过 `catalyst serve` 提供服务；绝不要使用原生开发服务器（`npm run dev`、`vite`、`next dev`、`ng serve` 等），因为 Catalyst 认证中间件、cookie 注入和 `/__catalyst/sdk/init.js` 仅在 `catalyst serve` 下可用。
2. 先识别认证流程类型：托管登录（重定向到 Catalyst 登录页）、嵌入式登录（自定义 UI），还是后端 `getCurrentUser` 检查。
3. 加载 `references/auth-basics.md`，获取注册/登录流程、ZAID 陷阱、托管登录与嵌入式登录的对比以及常见认证错误。
4. 始终校验当前环境：ZAID 在 Development 和 Production 之间不同，这是生产环境认证问题的头号原因。
5. 若涉及控制谁可以调用函数，转到 `catalyst-functions` 技能及其 `references/functions-basics.md` 的 Security Rules 部分；Security Rules 有两个参数：(a) `methods`——函数启用的 HTTP 方法（GET/POST/PUT/DELETE/PATCH），移除某方法即完全阻止该动词；(b) `authentication`——单一二元标志（`optional` = 公开，`required` = 仅认证用户），作用于整个函数而非按方法区分。
6. 若涉及基于角色的数据访问控制，转到 DataStore 的 Scopes and Permissions（Console → Table → Scopes and Permissions）。
7. 若涉及外部 API 的 OAuth 令牌管理（Zoho 或第三方），加载 `references/connections.md`。
8. 若涉及 Okta、Auth0、Duo、自定义 IdP、Google/Facebook/LinkedIn/Microsoft 登录、`generateCustomToken` 或 `signinWithJwt`，加载 `references/auth-thirdparty.md`。
9. 上线前，用 Production ZAID 和生产应用域名重新配置在 Development 中配置的社交登录（Google、Facebook、LinkedIn、Microsoft）；使用错误的 ZAID 会导致生产环境所有社交登录静默失败。
10. 注意 DataStore 权限与函数级认证是分开的：在 Security Rules 中要求认证只控制谁可以调用函数；App User 表权限（Console → Table → Scopes and Permissions）单独控制已认证用户可执行哪些 DataStore 操作。

适用边界 · 注意事项

• 不使用 `catalyst serve` 而用原生开发服务器（`npm run dev`、`vite`、`next dev`、`ng serve`）时，认证功能无法正常工作。
• 仅需控制函数调用权限时，不要在本技能中处理，应转到 `catalyst-functions` 技能的 Security Rules。
• 仅需基于角色的数据访问控制时，不要在本技能中处理，应转到 DataStore 的 Scopes and Permissions。