一键登录不难，难的是不出事：vibe 项目的社交登录实战

用户不是不想注册，是不想再记一个密码

很多 vibe 项目的注册漏斗死在一个很安静的地方：用户点开注册页，看到“设置密码、去邮箱点验证链接、回来再登录”这一串步骤，就关掉了页面。没有报错、没有投诉，只有一个再也没回来的访客。社交登录（用 Google、GitHub、Apple 等已有账号一键登录）解决的正是这一步：把“创建一个新身份”的成本，降到“点一下、确认一下”这个量级。

但社交登录不是“加三个按钮”那么简单。接错了，它会带来另一类麻烦：同一个用户用 Google 和 GitHub 各建了一个号、换了邮箱就登不进旧账号、拿到的权限比需要的多得多、授权回调被劫持导致账号被盗。这一篇讲的就是怎么把社交登录接对：先分清 OAuth 和 OIDC 各自负责什么，再谈选哪几家、账号怎么合并、安全清单有哪些、以及上线前必须跑完的测试。

文中的示例产品“松果清单”（一个虚构的待办清单工具）和用户“林晓”均为虚构，仅用于说明流程；涉及的具体接口参数以各平台当时的官方文档为准，本文不承诺某个平台的接口细节长期不变。

先分清两个概念：OAuth 是授权，OIDC 是认证

最常见的误解，是把 OAuth 2.0 当成“登录协议”。严格说，OAuth 2.0 解决的是授权问题：用户同意让你的应用以他的名义去访问某样东西（比如读取他的公开资料）。它本身并不告诉你“这个用户是谁”——你拿到的是一个访问令牌（access token），而不是一份身份证明。

OpenID Connect（OIDC）是建在 OAuth 2.0 之上的认证层，它加了一个 ID Token：一个由身份提供方签名的 JWT，里面写着这个用户的唯一标识（sub）、邮箱、邮箱是否已验证等信息。你的应用验证签名、核对签发方和受众之后，才能说“这个人就是 sub 对应的用户”。所以，社交登录的正确说法是“用 OIDC 做登录”，而不是“用 OAuth 做登录”。这个区分不是咬文嚼字：只拿 access token 当登录凭证的应用，等于把“能调接口”等同于“是这个人”，一旦 token 的权限范围被理解错，身份判断就会出错。

对 vibe 项目来说，实操结论很简单：优先选支持 OIDC 的提供方（Google、Apple、GitHub 通过相关端点等都提供用户信息接口），并且以 ID Token 里的 sub 作为该提供方下的用户唯一标识，不要用邮箱、昵称这类可能变化的字段当主键。邮箱会换、昵称会改，sub 在该提供方内是稳定的。

选哪几家：先覆盖 80% 的用户，再谈长尾

选提供方的原则是“按你的用户来”，不是“把市面上的按钮全摆上”。对面向全球开发者的工具，Google 和 GitHub 通常能覆盖绝大多数用户：Google 覆盖普通用户，GitHub 覆盖开发者——而且 GitHub 登录天然带着“这个人可能是开发者”的信号，对开发者工具类产品尤其合适。面向苹果生态用户较多的产品，再加 Apple 登录；苹果对 App Store 上架还有额外要求，某些场景下提供 Apple 登录是合规前提，上架前要先查当时的审核规则。

每多一家提供方，你就多一份维护成本：回调地址、密钥轮换、品牌规范、用户支持（“我用 X 登录为什么找不到账号”）都要乘以提供方数量。我的建议是：第一版只接两家，跑一个月看注册来源分布，再决定要不要加第三家。按钮顺序也有讲究：把转化最高的那家放最上面，而不是按字母顺序排列；同时永远保留邮箱登录入口——社交登录是“更方便的路”，不是“唯一的路”，否则提供方一出问题，你的用户就全被锁在门外。

还有一个经常被忽略的点：要提前想好“用户没有那个提供方账号怎么办”。比如你的产品面向企业用户，但对方公司禁用了个人 Google 账号登录企业工具，这时候如果只有社交登录，用户就卡住了。保留邮箱 + 密码（或邮箱验证码、Passkey）作为兜底，不是落后，而是在给所有用户留一条能走通的路。

最难的部分不是接通，而是账号合并

社交登录上线后最常见的客服问题，不是接不通，而是“我有两个号”。典型场景：林晓先用邮箱注册了松果清单，后来点了“用 Google 登录”，结果系统给他新建了一个空账号，旧的待办清单全在旧号里。用户看到的是“我的数据丢了”，而系统看到的是“两个合法账号”。

处理这个问题的核心规则是：账号的身份，永远以你自己的用户表为准，提供方账号只是“绑定在这个用户上的登录方式”。数据模型上，一个用户可以绑定多个登录身份（identity）：每条 identity 记录提供方、该提供方下的 sub、以及绑定的时间。登录时，先根据 identity 找到用户；找不到时，再按规则决定是新建用户还是引导合并。

合并的时机和方式要分情况。最安全的做法是：当社交登录返回的邮箱，和一个已存在账号的邮箱相同、且该邮箱在提供方侧已验证时，提示用户“检测到已有账号，是否合并”，并要求用户先通过已有账号的验证（比如输入已有账号的密码、或点邮箱验证链接）再合并。绝不能只凭“邮箱相同”就自动合并——邮箱相同不等于同一个人，尤其是在企业邮箱回收、邮箱被转手的情况下。自动合并一旦错了，就是 A 能进 B 的账号，比“多一个号”的客服问题严重得多。

反过来也要处理“解绑”：用户想取消某个社交登录绑定时，不能让他把最后一个登录方式也解掉，否则账号就再也登不进去了。规则应该是：解绑前检查该用户是否还剩至少一种可用登录方式（另一个社交绑定、或邮箱密码、或 Passkey），没有就先引导他加上一种，再放行解绑。同样，换绑邮箱、注销账号这些操作，都要先过一遍“会不会把用户锁在门外”的检查。

安全清单：state、PKCE、回调校验，缺一不可

社交登录的安全问题大多不出在密码学上，而出在流程实现上。下面这几项是上线前必须逐项打勾的清单。

第一，state 参数必须随机、一次性、并绑定到当前会话。它的作用是防止跨站请求伪造（CSRF）：攻击者把自己的授权码发给受害者，让受害者的账号绑上攻击者的社交账号。实现上，生成一个随机 state 存进会话（或加密 cookie），回调时比对，不一致直接拒绝。不要用固定字符串、不要用可预测的时间戳当 state。

第二，PKCE（读作“pixy”）要用起来，尤其是移动端和单页应用。PKCE 的做法是：发起授权时先生成一个随机码验证器（code verifier），只把它的哈希（code challenge）发给提供方；换 token 时再出示原始 verifier。即使授权码在传输中被截获，没有 verifier 也换不到 token。对服务端应用，PKCE 同样值得开——它是纵深防御里成本最低的一层。

第三，回调地址必须在提供方后台精确登记，并且服务端要校验收到的回调地址、code 只能用一次、token 换取走服务端到服务端的请求。授权码、access token、refresh token 一律不许出现在前端 URL、日志和错误信息里。日志里只记“某用户在某时完成某提供方登录”，不记 token 本身；出问题排查时，没有 token 的日志才是安全的日志。

第四，ID Token 必须验签、验签发方、验受众、验过期时间。不要只解析 JWT 的 payload 就相信它——不验签的 JWT 和普通 JSON 没有区别。签发方的公钥要从提供方公布的 JWKS 地址动态获取并缓存，不要把某个时间点的公钥硬编码进代码。邮箱字段要看“是否已验证”这个标记：提供方说“这个邮箱已验证”，你才能把它当成可信的联系方式；否则，它只能当成展示用的昵称信息。

权限要最小化：只拿你真正需要的 scope

每个社交登录都会让用户看到一个授权页面，上面列着你的应用想要的权限。scope 要得越多，用户点“拒绝”的概率就越高，而且一旦出事，影响面也越大。原则是：登录只需要“识别这个人”——通常是 openid、profile、email 这几个基础 scope 就够了。不要在登录这一步顺手要“读取用户仓库”“读取通讯录”“代发动态”这类权限。

需要额外权限的正确做法是“渐进式授权”：用户用到某个功能时，再单独发起一次授权，并且在界面上说清楚“为什么需要这个权限、不用会怎样”。比如松果清单要做“把 GitHub issue 一键转成待办”，那就等用户第一次点这个功能时，再去要读取仓库的权限。这样做有两个好处：一是注册转化率不受拖累，二是用户在有上下文的时候更容易理解并同意。

还要定期审 scope 清单：产品迭代中加的权限，用不上的要及时下掉；提供方侧的授权页面也要定期自己走一遍，看看用户实际看到的是什么。很多团队的 scope 清单是“只加不减”长起来的，三年后回头看，才发现登录页在要一堆早已没人用的权限。

Token 怎么存、什么时候作废

登录成功后，你自己的会话怎么管，和提供方的 token 是两回事。推荐的做法是：用你自己的会话机制（cookie 会话或你自己的 token）来维持登录状态，不要把提供方的 access token 当成你自己的会话凭证长期存着。需要调用提供方 API 时，再用存好的 refresh token 去换——而且 refresh token 必须加密存储，绝不能明文躺在数据库里。

吊销和过期也要有预案。用户在你的产品里点“退出”时，只清你自己的会话就够了，一般不需要去吊销提供方侧的授权；但用户点“断开与某社交账号的绑定”时，应该同时去提供方侧吊销对应的授权（如果提供方支持吊销端点），否则你的数据库里删了绑定，提供方那边还以为授权有效。同样，用户注销账号时，所有绑定的社交授权都应该一并清理，并留一条审计记录：谁、在什么时候、断开了哪个提供方。

还有一个容易被忽略的场景：提供方侧的账号被用户删除、或邮箱被回收后，你的应用要怎么处理？稳妥的做法是：下次该 identity 再来登录时，如果提供方返回的 sub 已不存在或邮箱已变，要走“重新验证”流程，而不是静默地沿用旧绑定。把“提供方说这个人还在”当成持续有效的假设，是很多账号接管问题的根源。

上线前必须跑完的测试清单

社交登录的测试不能只测“ happy path”（点按钮、授权、进首页）。下面这些用例，至少要在上线前跑一遍。第一，新用户用每个提供方各注册一次，确认资料（头像、昵称、邮箱）填充正确，且没有重复建号。第二，老用户用社交账号登录，邮箱与已有账号相同时，走合并引导流程，合并后两个登录方式都能进同一个号，数据没有丢。第三，拒绝授权、授权中途关闭窗口、回调超时，这三种中断都要回到登录页并给出可读的提示，而不是白屏或 500。

第四，安全负向测试：伪造 state 回调、重放已用过的授权码、篡改 ID Token 的 payload 不验签——这三项都必须被拒绝。第五，多设备与多浏览器：手机浏览器、应用内 WebView、桌面浏览器各跑一次，因为回调和 cookie 策略在这些环境里表现并不相同。第六，断网与慢网：提供方接口超时时，你的登录页要给出“登录服务暂时不可用，请稍后再试”，而不是无限转圈。

最后，上线后还要盯三组数据：各提供方的注册转化率、社交登录用户的次日留存（和邮箱注册用户对比）、以及“合并账号”类客服工单的数量。如果某家提供方的转化率明显低于其他家，先去看它的授权页面——很可能是 scope 要多了，或者品牌展示出了问题，而不是用户不喜欢这家。社交登录接上线只是开始，盯着数据调，才是它真正产生价值的部分。

自建还是用现成 Auth 服务：按团队规模选

做到这一步，很多小团队会纠结：社交登录是自己接，还是直接用现成的身份服务（比如 Auth0、Clerk、Supabase Auth 这类）？答案取决于你的团队规模和账号体系的复杂度。如果你只有一个产品、两三家提供方、且已经有自己的用户表和会话机制，自己接并不难：核心就是授权跳转、回调校验、identity 绑定这三段逻辑，代码量可控，而且你对账号数据的掌控最完整。

但如果你有多个产品要共享登录、或者需要企业级单点登录（SSO）、多租户、细粒度审计这类能力，现成服务的价值就显现出来了：它把各家提供方的差异、密钥轮换、合规细节都包了进去，你付的是订阅费，省的是踩坑时间。判断标准可以定得很实际：当你发现自己在为“第三家提供方的回调又出幺蛾子”花掉一整天时，就是该考虑托管服务的时候；反过来，如果你的账号体系很简单、且你希望用户数据尽量少经过第三方，那就继续自建。两种路线没有高下，只有成本结构不同。

还有一个容易被低估的成本：品牌与合规细节。各家提供方对登录按钮的样式、文案、Logo 使用都有品牌规范，比如按钮上必须写“使用 Google 账号登录”而不是“Google 登录一下”，Logo 不能改色、不能加描边。这些规范不是可有可无的装饰：违反品牌规范可能导致应用审核被驳回，严重的会被暂停 OAuth 客户端资格。上线前，把每家提供方的品牌指南过一遍，把按钮截图存档，是半小时就能做完、却能省掉大麻烦的活。

隐私政策和数据使用说明也要同步更新：明确写出你通过社交登录收集了哪些字段（通常是头像、昵称、邮箱）、这些字段用来做什么、保存多久、用户如何删除。很多团队接了社交登录，却忘了更新隐私政策，结果是法务风险和用户信任风险同时存在。用户在授权页上看到的权限，和你的隐私政策里写的收集范围，应该是一致的；不一致的地方，就是未来客服和合规工单的来源。

总结一下：社交登录的价值在于把注册摩擦降到最低，但它的成本藏在账号合并、安全流程和长期维护里。接之前先定好三条规则：以自己的用户表为准、合并必须经过已有账号验证、权限只拿最小集。这三条立住了，社交登录就是帮你留住用户的利器；立不住，它就是帮你制造客服工单的机器。