authentication-setup

认证设置

当实际任务是为真实应用选择和规划产品认证方案时，请使用此技能；而不是单纯贴出 JWT 代码片段，也不要把认证、授权、安全加固和文档当成同一项任务。

authentication-setup 负责设置层面的工作，包括：

• 选择托管式、框架原生、平台原生、企业附加组件或可自托管的认证方案
• 确定会话／Cookie 与令牌的边界
• 选择登录方式：邮箱／密码、魔法链接、社交 OAuth、通行密钥
• 明确哪些用户／个人资料／组织／成员关系数据由应用自行管理
• 规划 SSO／SCIM、域名映射和迁移／切换边界
• 记录回调 URL、Cookie 域、预览／暂存环境差异和发布说明

在选择方案或移交任务前，请先阅读以下支持文档：

• references/auth-decision-matrix.md
• references/boundary-checklist.md
• references/session-and-deployment-notes.md
• references/enterprise-and-migration-notes.md

何时使用此技能

• 为新的 Web 应用、SaaS 产品、管理应用或由 API 支持的产品设置认证
• 在 Clerk、Auth.js、Better Auth、Supabase Auth、Firebase Auth、Cognito、Keycloak 或类似方案之间进行选择
• 添加或重构会话、Cookie、刷新令牌策略、OAuth 提供方或通行密钥
• 围绕认证提供方定义由应用自行管理的用户、个人资料、组织、成员关系和角色边界
• 将组织、邀请、企业 SSO、SCIM 或域名验证列为下一阶段目标
• 理清前端路由、中间件、后端 API 和数据库策略层之间的认证边界
• 评估当前认证技术栈是否过度耦合于供应商、过于依赖自行实现，或定义过于含糊而无法安全扩展

何时不使用此技能

• 主要任务是授权策略、权限继承或 ABAC／ReBAC 建模 → 将其视为独立的授权设计问题，并将契约语义交由 api-design 处理
• 主要任务是 Cookie 标志、CSRF、速率限制、机密信息处理、防滥用或通用漏洞加固 → 使用 security-best-practices
• 主要任务是在将认证妥善纳入 API 之前设计 API 契约／接口 → 使用 api-design
• 主要任务是编写面向开发者的参考文档、快速入门指南或面向使用者的 API 认证文档 → 使用 api-documentation
• 主要任务是后端回归覆盖、登录／回调测试或角色矩阵测试规划 → 使用 backend-testing
• 主要任务是深入的架构规范化／索引设计，而非认证管理的表和身份边界 → 使用 database-schema-design

说明

第 1 步：在提及供应商前，先对认证任务分类

先明确任务需求。

auth_setup_profile:
  app_type: saas | internal-tool | marketplace | consumer-app | api-only | mixed | unknown
  auth_lane: hosted | framework-native | platform-native | enterprise-add-on | self-hosted | unknown
  runtimes: browser | server | edge | mobile | api | mixed
  login_methods: password | magic-link | social-oauth | passkeys | sso | mixed | unknown
  identity_scope: single-user | teams-orgs | b2b-enterprise | mixed | unknown
  session_model: server-session | stateless-jwt | hybrid | unknown
  data_ownership: vendor-owned | app-owned | hybrid | unknown
  rollout_stage: greenfield | mvp | scale-up | migration | enterprise-expansion

询问或推断：

1. 现有的框架、运行时和部署环境有哪些？
2. 团队优先考虑的是尽快安全上线、更高程度的控制、企业支持，还是自托管？
3. 应用只需要登录，还是还需要组织、邀请、角色、管理员访问和客户 SSO？
4. 当前技术栈中，哪些认证／数据组件已经确定？

步骤 2：选择最精简且可靠的认证路径

使用 auth-decision-matrix.md，而不是凭记忆重新梳理整个领域。

默认路径选择：

• 托管式认证：最看重速度、预构建 UX、身份提供方、MFA/通行密钥和完善的引导流程时
• 框架原生认证：团队希望认证紧贴应用代码，并由应用管理数据时
• 平台原生认证：已确定使用 Supabase/Firebase/Appwrite 等平台时
• 企业级附加功能：请求涉及 SAML/OIDC SSO、SCIM、目录同步或域名验证时
• 自托管：主权、隔离网络、仅开源或本地部署要求占主导时

规则：

1. 推荐一个主要路径，最多再提供一个备选路径。
2. 如果后端平台已经确定，优先评估平台原生方案。
3. 如果提到企业身份认证，应明确转入该分支，而不是将其简化为消费者登录。
4. 如果迁移或切换风险很重要，请参考 enterprise-and-migration-notes.md。

步骤 3：划定身份提供方与应用的所有权边界

实施之前，明确各方负责什么。

最低限度的边界清单：

• **身份提供方通常负责：**登录方式、密码重置/邮箱验证、MFA/通行密钥验证流程、令牌/会话签发、企业联合身份认证入口
• **应用通常负责：**本地用户/个人资料记录、组织/工作区成员关系、角色/权限、与计费关联的访问权限、管理/支持例外、特定领域的授权
• **共同边界：**复制到令牌或会话中的声明、Webhook/用户同步、回调 URL、中间件、Cookie 配置、审计/事件可见性

使用 boundary-checklist.md，避免此技能偏离到相邻领域。

步骤 4：有意识地选择会话和登录模式

使用 session-and-deployment-notes.md 查看详细的启发式指南。

快速默认选项：

• 服务器会话 / 签名 Cookie：适用于以浏览器为主的应用、SSR 和便于中间件处理认证状态的场景
• 无状态 JWT：适用于以 API 为主的多服务流量，且令牌验证是首要要求的场景
• 混合模式：适用于浏览器会话和 API/机器令牌都很重要的场景

始终记录：

• 选择了哪些登录方式，以及当前为何需要它们
• 令牌/会话的有效期和刷新策略
• 登出/撤销方面的预期
• 在本地、预览、暂存和生产环境中回调 URL 与 Cookie/域名的行为
• 可能影响辅助函数可用性的边缘运行时限制

步骤 5：为应用自有的认证数据建模

即使使用托管式认证，通常仍然需要本地数据表。

通常至少定义：

• users 或 profiles
• 如果支持多租户，则定义 organizations / workspaces
• memberships / roles
• 如果团队成员通过邀请或管理员管理，则定义邀请、预配或席位状态

记录：

• 身份提供方和应用数据库之间稳定的用户标识符
• 哪些字段由供应商持有，哪些字段会在本地镜像
• 权限存放在声明、本地数据表，还是两者都有
• 如何检测并修复 Webhook 或同步故障

如果请求延伸到更广泛的架构设计，请将更深入的建模工作交由 database-schema-design 处理。

步骤 6：明确分支处理企业认证或迁移工作

如果请求涉及 SSO、SCIM、域名验证、现有用户关联、身份提供方迁移或自托管切换风险，请使用 enterprise-and-migration-notes.md。

明确列出以下事项：

• 这是附加功能还是替换方案
• 账户关联以及组织/域名映射规则
• 预配/取消预配行为
• 客户引导/支持预期
• 发布或迁移出错时的回滚边界

第 7 步：生成身份验证设置方案

输出应有助于顺利推进下一步实施。

建议方案包含：

1. 选择的身份验证路径及原因
2. 首选技术栈建议及备选方案
3. 提供方与应用的所有权边界
4. 会话与登录模型
5. 应用自有数据模型概述
6. 环境检查清单
7. 相关任务的分流建议
8. 未解决的风险或迁移说明

输出格式

除非用户要求其他格式，否则使用此结构：

# Authentication Setup Plan

## Auth lane
- chosen lane
- why it fits

## Recommended stack
- primary option
- fallback option
- tradeoffs

## Ownership boundary
- provider owns
- app owns
- shared edge / sync points

## Session + login model
- sessions vs JWT vs hybrid
- chosen login methods
- callback/cookie/runtime notes

## App-owned data model
- users/profiles
- orgs/memberships/roles
- sync strategy

## Environment + rollout checklist
- local
- preview/staging
- production
- migration notes

## Route-outs
- adjacent skills and why

示例

示例 1：带有产品身份验证的 Next.js SaaS

输入：

为一个 Next.js SaaS 应用设置身份验证，支持电子邮件登录、Google OAuth、组织角色和管理面板。

预期处理：

• 将其归类为浏览器与服务器混合型 SaaS，并支持团队/组织
• 比较托管方案与框架原生方案，而不是直接给出 JWT 代码片段
• 定义应用自有的组织/成员关系表
• 说明 SSR/中间件/ Cookie 的边界
• 将安全加固和身份验证流程测试分流到相关技能

示例 2：以 Supabase 为主的应用

输入：

我们已经在使用 Supabase。请确定哪些身份验证功能应放在 Supabase 中，哪些应放在我们的应用数据库中，以及角色应如何运作。

预期处理：

• 优先选择平台原生路径
• 将提供方身份与应用自有的权限权益分开
• 指出 RLS/授权的后续工作属于相关设计/测试事项

示例 3：企业扩展或迁移

输入：

我们已经有登录功能。现在要为 B2B 客户添加企业 SSO 和 SCIM，同时不重写整个身份验证技术栈。

预期处理：

• 将其归类为企业功能扩展或对迁移敏感的工作，而非基础消费级登录设置
• 涵盖账户关联、组织/域名映射和用户配置边界
• 不要假设 SSO/SCIM 与社交登录或密码身份验证是同一项工作

最佳实践

1. 先说明身份验证路径和所有权边界，不要一开始就给代码片段。
2. 将身份验证设置与更深入的授权策略及常规安全加固分开。
3. 即使使用托管身份验证，也要假设大多数产品仍需要应用自有的用户/组织/成员关系表。
4. 一旦出现 B2B 或切换压力，就应将企业 SSO/SCIM 和迁移视为独立分支。
5. 尽早记录特定环境下的回调、Cookie 和预览部署行为。
6. 优先给出一个明确的首选建议和一个备选方案，而不是罗列大量供应商。
7. 明确分流相关工作，让 authentication-setup 保持通用，而不是变成另一个后端万能工具。

参考资料

• Next.js 身份验证
• Auth.js
• Clerk 文档
• Supabase Auth 文档
• Keycloak 文档
• WorkOS 文档