moai-platform-auth

认证平台专家

涵盖三大主流平台的全面认证与授权指南：Auth0（企业安全）、Clerk（现代化用户体验）和 Firebase Auth（移动优先）。

快速选择平台

Auth0——企业安全

面向企业的身份平台，专注于安全合规与攻击防护。

适用场景：需要强合规能力（FAPI、GDPR、HIPAA）、高级攻击防护、带发送方约束（DPoP/mTLS）的令牌安全，以及多租户 B2B SaaS 的企业级应用。

核心优势：高级攻击防护（机器人检测、泄露密码检测、暴力破解防护）、自适应 MFA、合规认证（ISO 27001、SOC 2、FAPI）、令牌安全（DPoP、mTLS）、全面的安全监控。

成本模式：根据月活跃用户数量定价，企业功能需选择更高阶套餐。

Context7 库：/auth0/docs

Clerk——现代化用户体验

提供精美的预构建 UI 组件并支持 WebAuthn 的现代认证服务。

适用场景：重视开发者体验和用户体验的现代 Web 应用、Next.js 应用、需要以极少配置实现社交登录的应用，以及无密码认证。

核心优势：可直接集成、界面精美的 React 组件，支持 WebAuthn 和通行密钥，与 Next.js 无缝集成，组织管理功能，以及简洁的 API 和出色的开发者体验。

成本模式：提供免费套餐，根据月活跃用户数量定价，且免费套餐额度充足。

Context7 库：/clerk/clerk-docs

Firebase Auth——移动优先集成

与 Firebase 服务无缝集成的 Google 生态系统认证服务。

适用场景：移动应用（iOS、Android、Flutter）、Google 生态系统集成、无服务器 Cloud Functions、需要支持升级路径的匿名认证的应用，以及中小型 Web 应用。

核心优势：适用于 iOS/Android/Flutter 的原生移动 SDK、Google Sign-In 集成、Firebase 服务集成（Firestore、Storage、Cloud Functions）、手机号认证，以及额度充足的免费套餐。

成本模式：提供额度充足的免费套餐，使用量较高时按量付费。

Context7 库：/firebase/firebase-docs

快速决策指南

选择 Auth0 的情况：

• 企业安全和合规要求至关重要
• 需要高级攻击防护和安全监控
• 实现发送方约束令牌（DPoP、mTLS）
• 支持复杂的 B2B 多租户场景
• 需要满足 FAPI、GDPR、HIPAA 或 PCI DSS 合规要求

选择 Clerk 的情况：

• 构建现代 Next.js 或 React 应用
• 优先考虑开发者体验和精美 UI
• 需要快速实现无密码或 WebAuthn 认证
• 希望将应用中的认证代码降至最低
• 需要带有基于角色的访问控制的组织管理功能

选择 Firebase Auth 的情况：

• 构建移动优先应用
• 已在使用 Firebase 生态系统（Firestore、Storage、Functions）
• 需要 Google Sign-In 或 Google 生态系统集成
• 希望实现支持升级路径的匿名认证
• 倾向于采用 Cloud Functions 的无服务器架构

常见认证模式

通用模式

这些模式适用于所有三个平台，但具体实现因平台而异。

会话管理：

所有平台都支持会话持久化、刷新令牌和会话失效。Auth0 使用刷新令牌轮换，Clerk 使用自动刷新的会话令牌，Firebase 使用带自定义声明的 ID 令牌刷新。

多因素身份验证：

所有平台都支持多种 MFA 因素，包括 TOTP、SMS 和推送通知。Auth0 提供 WebAuthn 和自适应 MFA，Clerk 提供带通行密钥的 WebAuthn，Firebase 提供电话验证和自定义 MFA。

社交身份验证：

所有平台都支持主流社交提供商（Google、Facebook、GitHub、Apple）。Auth0 要求为每个提供商配置连接，Clerk 提供预配置的社交登录按钮，Firebase 要求配置 OAuth 并设置 SDK。

基于角色的访问控制：

所有平台都支持使用自定义声明或元数据进行授权。Auth0 使用 Actions 在 JWT 令牌中添加自定义声明，Clerk 使用组织角色和元数据，Firebase 使用 Admin SDK 设置自定义声明。

令牌管理：

所有平台都会签发用于 API 授权的 JWT 令牌。Auth0 提供带作用域的访问令牌和刷新令牌，Clerk 通过 getToken() 提供会话令牌，Firebase 提供带自定义声明的 ID 令牌。

安全最佳实践

适用于所有平台：

令牌存储：

• 在 Web 上切勿将令牌存储在 localStorage 中（存在 XSS 漏洞风险）
• 尽可能使用 httpOnly Cookie
• 对于 SPA，使用内存存储并启用刷新令牌轮换
• 移动应用使用安全存储（Keychain、Keystore）

强制使用 HTTPS：

• 在生产环境中始终使用 HTTPS
• 配置安全的重定向 URI
• 启用 HSTS 标头

令牌验证：

• 始终验证令牌签名
• 验证令牌受众（aud 声明）
• 检查令牌过期时间（exp 声明）
• 验证签发者（iss 声明）

密码策略：

• 强制执行强密码要求
• 启用泄露密码检测
• 多次尝试失败后锁定账户
• 使用密码强度指示器

API 安全：

• 要求所有受保护的端点都进行身份验证
• 实施速率限制
• 使用作用域或权限进行授权
• 记录身份验证和授权事件

平台特定实现

有关平台特定实现的详细指导，请参阅参考文件：

Auth0 实现

文件：reference/auth0.md

涵盖攻击防护配置、使用 WebAuthn 和自适应策略设置 MFA、使用 DPoP 和 mTLS 发送方约束保障令牌安全、FAPI/GDPR/HIPAA 合规功能、安全中心监控，以及持续会话保护。

主要章节：控制台导航、机器人检测配置、泄露密码检测、暴力破解防护、WebAuthn 设置、令牌验证、DPoP 实现、mTLS 证书绑定、合规认证。

Clerk 实现

文件：reference/clerk.md

涵盖 Next.js 的 ClerkProvider 设置、身份验证组件（SignIn、SignUp、UserButton）、使用中间件保护路由、useAuth 和 useUser Hooks、服务端身份验证、组织管理，以及 Core 2 迁移。

主要章节：环境变量、中间件配置、路由保护、访问用户数据、组织切换、自定义身份验证流程、Webhook 集成。

Firebase Auth 实现

文件：reference/firebase-auth.md

涵盖跨平台（Web、Flutter、iOS、Android）的 Firebase SDK 初始化、社交身份验证设置、通过 SMS 验证进行电话身份验证、带账户关联的匿名身份验证、用于 RBAC 的自定义声明，以及 Security Rules 集成。

主要章节：项目设置、SDK 初始化、Google Sign-In、Facebook Login、电话验证、自定义声明管理、Firestore 和 Storage 规则、Cloud Functions 触发器。

平台对比

文件：reference/comparison.md

提供涵盖功能、定价、使用场景、迁移注意事项和集成复杂度的详细对比矩阵。

主要部分：功能对比表、定价明细、使用场景决策矩阵、平台迁移策略、生态集成、开发者体验对比。

导航指南

使用身份验证功能时：

1. 如果要选择平台，请从上方的快速平台选择开始
2. 查看通用身份验证模式，了解通用概念
3. 打开特定平台的参考文件，查看实现细节
4. 评估多个平台时，请参阅 comparison.md
5. 使用 Context7 工具获取最新的平台文档

Context7 文档访问

使用 Context7 MCP 访问最新的平台文档：

Auth0：

• 使用 resolve-library-id 并传入 "auth0" 获取库 ID
• 使用 get-library-docs 并传入主题 "attack-protection"、"mfa"、"tokens"、"compliance"

Clerk：

• 使用 resolve-library-id 并传入 "clerk" 获取库 ID
• 使用 get-library-docs 并传入主题 "nextjs"、"react"、"authentication"

Firebase Auth：

• 使用 resolve-library-id 并传入 "firebase" 获取库 ID
• 使用 get-library-docs 并传入主题 "authentication"、"security-rules"

配合使用效果良好

• moai-platform-supabase：集成身份验证的数据库
• moai-platform-vercel：支持边缘身份验证的部署
• .claude/rules/moai/languages/typescript.md：身份验证 SDK 的 TypeScript 模式（通过 paths frontmatter 自动加载）
• moai-domain-backend：包含身份验证的后端架构
• moai-domain-frontend：React/Next.js 前端集成
• moai-expert-security：安全审计与威胁建模

---

状态：活跃 版本：2.0.0（整合平台覆盖范围） 最后更新：2026-02-09 平台：Auth0、Clerk、Firebase Auth

常见的自我安慰

自我安慰	事实
"仅密码身份验证足以满足内部工具的需求"	内部工具也会因凭证填充攻击而遭到入侵。任何可访问生产数据的工具都至少应启用 MFA。
"我会从头实现身份验证，以避免被供应商锁定"	自定义身份验证实现是安全漏洞的主要来源。应使用经过验证的提供商，并对接口进行抽象。
"用户不喜欢重新登录，所以会话过期时间可以设得很长"	长会话会扩大被盗令牌的攻击窗口。应使用短会话并进行静默刷新。
"社交登录只是一个便利功能"	社交登录将身份验证委托给身份提供商。这能减少密码存储带来的攻击面。
"WebAuthn/通行密钥还太新，不适合采用"	所有主流浏览器和平台都支持通行密钥。它们可以消除最常见的攻击途径——网络钓鱼。

危险信号

• 身份验证令牌存储在 localStorage 中，而不是 httpOnly Cookie 中
• 高权限账户没有可用的 MFA 选项
• 会话令牌没有过期时间或刷新机制
• 密码重置流程不会使现有会话失效
• OAuth 重定向 URI 接受通配符或未经验证的值

验证

• 令牌存储在 httpOnly、Secure、SameSite Cookie 中（而不是 localStorage）
• 所有用户账户均已启用或可使用 MFA
• 已配置会话过期时间和自动刷新机制
• 密码重置会使该账户的所有现有会话失效
• OAuth 重定向 URI 已通过精确匹配验证（无通配符）
• 身份验证提供商 SDK 版本为当前版本（显示依赖项版本）

重构说明

R4 审计结论（2026-04-23）：重构 — 保留三方范围（Clerk、Auth.js、Supabase Auth），并针对各供应商提供更精简的指导 SPEC：SPEC-V3R2-WF-001 §6.2 第 272 行 重构范围（推迟到未来的子 SPEC）：

• 针对各供应商（Clerk、Auth.js、Supabase Auth）提供更精简、更具可操作性的指导
• 添加实现模式对比表，便于选择供应商
• 将 OWASP 身份验证清单参考资料提取到 moai-ref-owasp-checklist

此技能将在 v3.0 中保留，但其正文将在后续 SPEC 中重构。