twenty-oauth-mastery

该 Skill 是一套面向 Twenty CRM 开发者的专家级 OAuth 集成知识库，专注于解决企业级 CRM 系统中的身份认证与数据同步难题。

核心用法涵盖：实现 Google/Microsoft OAuth 认证流程、配置自动 Gmail/Calendar 同步、处理 Token 刷新与域限制、以及解决常见的重定向循环问题。文档提供了完整的 Passport Strategy 配置模式、OAuthSyncService 集成方案和部署检查清单，支持从开发到生产的全流程 OAuth 实施。

显著优点在于内容深度和实践性：不仅提供标准 OAuth 实现代码，更针对 Twenty CRM 特定架构（NestJS + TypeScript）提供了 5 大常见问题的详细解决方案，包括重定向循环、域限制阻塞、同步失败等。文档包含完整的测试策略（单元测试和 Playwright 集成测试）和分步部署检查清单，可直接用于生产环境故障排查，大幅降低 OAuth 集成调试时间。

潜在局限性包括：作为社区来源（T3）的文档，代码示例需要用户根据实际环境调整验证；部分内容高度依赖 Twenty CRM 特定版本（如文件路径结构），可能随框架升级而过时；且主要针对 Google/Microsoft 提供商，对其他 OAuth 提供商覆盖有限。此外，文档中涉及的域限制和 Token 管理配置错误可能导致合法用户被拦截或安全隐患。

适合目标群体为：Twenty CRM 二次开发者、需要集成企业邮箱/日历同步的后端工程师、以及负责身份认证系统维护的 DevOps 人员。特别适合正在处理 OAuth 登录故障、自动同步失败或域限制配置问题的技术团队。

使用风险包括：OAuth 凭证（Client Secret）需严格通过环境变量管理，避免硬编码泄露；Token 刷新时需处理并发控制和原始 Refresh Token 保留问题；域名白名单配置不当可能阻止合法用户访问；以及必须确保后端代码重新编译（nx build）后部署，避免容器运行旧版本代码导致的逻辑不一致。

概述

Twenty CRM OAuth Mastery Skill 是一份面向开发者的专家级技术文档，专门针对 Twenty CRM 平台的 OAuth 2.0 认证集成与故障排查。该 Skill 深度剖析了基于 NestJS/Passport 的认证架构，提供了从快速启动到生产部署的全链路指导。

核心用法

架构定位：聚焦 twenty-server/src/engine/core-modules/auth/ 目录，覆盖 Strategy（Google/Microsoft）、Controller、Service、Guard 四层结构。

关键实现模式：

• Passport Strategy：强制启用 passReqToCallback: true，确保请求状态可访问
• Token 透传：validate() 必须返回 accessToken 与 refreshToken，否则自动同步失效
• Cookie 配置：httpOnly: false 以便前端 JavaScript 读取 tokenPair

典型集成场景：
1. 新 OAuth Provider 接入（Google/Microsoft）
2. 登录后自动 Gmail/Calendar 同步（OAuthSyncService）
3. 多域名限制配置（.com/.co 共存场景）
4. Token 刷新失败恢复（Google OAuth2Client 错误码解析）

显著优点

• 实战导向：基于真实调试 session 提炼，非理论文档
• 问题闭环：每个 Issue 提供「症状→根因→修复→验证」完整链条
• 代码级精度：标注关键行（🔴 CRITICAL），明确正确/错误写法对比
• 部署可落地：含 Docker 容器验证、编译检查、健康探测等运维命令

潜在局限

• 版本绑定：紧密耦合 Twenty CRM 特定版本（2026-02 基准），上游架构变更可能导致示例失效
• 范围聚焦：仅限 Google/Microsoft OAuth，未覆盖 SAML/OIDC 等其他协议
• 环境依赖：大量命令假设 Nx monorepo + Docker 部署模式
• 前端片段有限：React 部分仅涉及 SignInUpGlobalScopeFormEffect，未覆盖完整前端状态管理

适合人群

| 角色 | 适用场景 |

|------|---------|

| 后端工程师 | NestJS OAuth 实现、Token 刷新服务开发 |

| DevOps/SE | 生产环境部署、容器验证、配置排查 |

| 全栈开发者 | 端到端 OAuth 调试、前后端联调 |

| 技术支持 | 客户现场 OAuth 登录问题诊断 |

常规风险

1. 编译遗漏风险：TypeScript 源文件修改后未执行 nx build，容器运行旧代码
2. Token 丢失风险：validate() 未返回 tokens 导致同步静默失败
3. 域名硬编码风险：生产环境遗漏 .co 等变体域名，造成合法用户被拒
4. Cookie 安全权衡：httpOnly: false 降低 XSS 防护，需配合 CSP 等补偿措施
5. Refresh Token 过期：Google invalid_grant 需引导用户重新授权，无法自动恢复