Auth0 后端账号关联学习文档

Auth0 后端学习文档:从登录到安全关联账号

日期:2026-11-17。范围:基础概念、用户管理、会话与 Token、Actions、后端 API 集成。

本文用一个场景贯穿学习:用户先用邮箱密码注册,后来用 Google 登录。现在,用户希望两种方式都能进入原来的业务账号。

先记住三件事:验证用户是否控制两个账号;确定保留哪个主账号;处理业务数据库和旧会话。调用关联 API 只是其中一步。

本文使用短句、固定术语和明确步骤。未找到适用于本主题的根目录术语表,因此下文给出术语定义。官方行为附来源链接。标为“设计建议”的内容是本文提出的后端方案,不是 Auth0 自动提供的能力。代码均为学习示例。

1. 学习路线

阶段 需要回答的问题 对应章节
基础概念 Auth0、应用、身份提供商分别负责什么? 2
用户管理 一个用户如何拥有多个登录身份? 3
会话与 Token 后端凭什么确认当前用户是谁? 4
账号关联 如何证明用户控制两个账号? 5—7
后端集成 如何调用 API,处理失败和业务数据? 8—10
Actions 哪些逻辑适合放在登录流程中? 11
验证 如何确认实现没有关联错人? 12—13

2. 基础概念:先分清三种“用户”

Auth0 提供认证和授权服务。应用仍然需要维护自己的业务规则,例如谁能查看订单、谁属于某个企业。OAuth 2.0 解决访问授权问题;OIDC 在此基础上提供用户身份信息。来源:Auth0 Overview。

术语 本文含义 示例
Tenant,租户 Auth0 的配置与身份管理边界 开发环境的 Auth0 租户
Application,应用 在 Auth0 注册的客户端 服务端 Web 应用
API 接收 Access Token 的资源服务 订单 API
Connection,连接 接入某种身份来源的配置 Google 连接、邮箱密码数据库连接
Identity Provider,IdP 验证登录身份的系统 Google、企业身份系统
Identity,登录身份 用户在某个身份来源中的身份记录 Google 身份 google-oauth2 / g456
Auth0 User,Auth0 用户 Auth0 管理的用户档案 auth0|a123
Business User,业务用户 应用数据库中的用户实体 business_user_id = u42
Primary Account,主账号 关联后保留的 Auth0 用户档案 邮箱密码账号 A
Secondary Account,次账号 被关联到主账号的另一账号 Google 账号 B
Claim,声明 Token 中的一个字段 sub、iss、aud
Subject,主体标识 Token 的 sub 字段 某个 Auth0 用户标识

不要把邮箱当成永久用户主键。邮箱可能改变,也可能被重新分配。设计建议:业务表使用自己的稳定 ID;外部身份映射使用 (issuer, subject)。这样,不同租户中相同的 sub 不会意外相撞。

flowchart LR
  B[浏览器] --> W[应用后端]
  W --> A[Auth0]
  A --> I[Google 或其他 IdP]
  W --> D[业务数据库]
  W --> M[Auth0 Management API]

浏览器负责交互。Auth0 和 IdP 负责认证。后端负责验证结果、维护业务用户、检查权限和发起关联。

3. 用户管理:关联到底改变什么

3.1 关联前后

默认情况下,不同身份来源的登录可能产生独立 Auth0 用户。即使邮箱相同,也不能据此自动认定为同一个人。

关联前,有两个用户:

A:user_id = auth0|a123
   identities = [auth0 / a123]

B:user_id = google-oauth2|g456
   identities = [google-oauth2 / g456]

选择 A 为主账号,关联 B 后,主账号保留自己的用户 ID,身份列表加入 B。次账号不再作为独立用户出现在用户列表中。主账号 Metadata 保留,次账号 Metadata 不会自动合入。来源:User Account Linking。

A:user_id = auth0|a123
   identities = [auth0 / a123, google-oauth2 / g456]

业务目标:从任一登录方式进入,最终访问 business_user_id = u42。

上面的业务目标需要应用完成映射。Auth0 不知道订单表、积分表或订阅表的含义。

3.2 常见用户管理能力

能力 后端需要关注的事项
创建、查询、更新用户 区分 Auth0 档案与本地业务记录
邮箱验证、密码重置 让 Auth0 处理认证凭据;应用处理自己的业务状态
用户导入与迁移 维护旧 ID 到新身份的映射,验证登录路径
账号关联 验证两端身份,保留主账号,处理数据冲突
解除关联 检查剩余登录方式,重新定义业务数据归属
删除用户 明确身份删除与业务数据处理的边界

3.3 Metadata 不等于业务数据库

user_metadata 适合偏好等用户信息。不要信任它来授予权限。app_metadata 由受信任的应用管理,可存业务 ID 等访问相关信息。来源:Metadata。

设计建议:语言偏好可以按规则合并。管理员权限、组织成员资格、余额和订阅必须分别判断。不要把两个账号的权限数组直接取并集。

例如,A 有“企业 X 普通成员”身份,B 有“企业 Y 管理员”身份。不能仅因二者关联,就把“管理员”变成全局权限。

4. 会话与 Token:认证证据在哪里

4.1 三层会话

会话层 谁维护 典型作用
应用会话 你的后端 浏览器访问业务页面时识别用户
Auth0 会话 Auth0 应用之间复用登录状态
IdP 会话 Google 等上游系统 上游账号保持登录

清除应用 Cookie,不代表上游也已退出。账号 B 的认证过程,也不应覆盖关联事务保存的账号 A 身份。来源:Sessions and Cookies。

4.2 各种 Token 的用途

类型 谁使用 用途
ID Token OIDC 客户端应用 获得已验证的登录身份;aud 对应该应用
Access Token 目标 API 授权 API 调用;aud 对应资源服务
Refresh Token 客户端的受保护组件 在允许的条件下换取新 Token
Management API Access Token 后端管理服务 调用 Auth0 管理接口

ID Token 不能当作业务 API 的 Bearer 访问凭据。不要只解码 JWT 就相信它的内容。来源:Tokens。

后端应让成熟的 OIDC 库完成签名和声明验证。至少核对签发者、受众、过期时间,以及本次请求的 nonce。关联流程还要核对返回的主体是否等于预期账号。来源:Validate ID Tokens。

4.3 服务端登录的基本流程

  1. 后端建立认证事务,保存随机 state、nonce,并按所用 SDK 配置 PKCE。
  2. 浏览器跳转到 Auth0 /authorize。
  3. 用户完成认证。
  4. Auth0 把授权码送到已登记的回调地址。
  5. 后端校验事务,用授权码换取 Token。
  6. OIDC 库验证 Token,后端创建应用会话。

浏览器不持有后端 Client Secret。代码换 Token 在服务器进行。来源:Authorization Code Flow。

设计建议:关联流程采用独立回调地址,避免普通登录处理器提前覆盖应用当前用户。使用短期、一次性的关联事务,并把它绑定到发起者会话。

5. 账号关联的必要条件

5.1 相同邮箱只能用来找候选账号

假设 A 与 B 都显示 alice@example.com。这只是搜索线索。后端仍需证明发起者控制 A,也控制 B。Auth0 官方要求关联前认证两个账号。来源:User Account Linking — Precautions。

设计建议:对 A 做近期重新认证,再对 B 做独立认证。不要把“点了确认按钮”当成身份验证。prompt=login 可用于发起重新认证,但不同上游 IdP 的交互方式不同。必须验证实际连接的重新认证行为,不能仅根据页面是否出现密码框判断成功。

5.2 主账号由后端策略确定

优先保留已承载业务数据、且能通过认证验证的主账号。用户界面应明确显示将保留哪个账号。主账号 ID 不能只从请求体读取。

设计建议:本学习方案只处理两个尚未关联的独立用户。如果某一方已有关联身份,进入专门处理流程。不要把“关联一个身份”当成合并两棵身份集合。

5.3 邮箱不同是否允许关联

本文建议把“发现候选账号”和“证明身份”分开。相同邮箱适合做推荐;用户主动添加其他登录方式时,可以按产品规则接受不同邮箱。无论邮箱是否相同,都必须验证两端身份和业务限制。

6. 推荐主线:登录完成后,由后端关联

本文选择“账号设置页 → 添加登录方式”。这是设计建议。它便于把账号关联作为独立业务操作处理。

sequenceDiagram
  actor U as 用户
  participant B as 浏览器
  participant S as 应用后端
  participant A as Auth0
  participant D as 业务数据库
  U->>B: 在账号 A 下点击关联
  B->>S: POST 开始关联,携带 CSRF 防护信息
  S->>A: 发起 A 的重新认证
  A-->>S: 回调,后端验证 A
  S->>D: 保存关联事务和固定的主账号
  S->>A: 发起 B 的独立认证
  A-->>S: 回调,后端验证 B
  S-->>B: 显示关联结果预览
  U->>B: 确认
  B->>S: POST 确认关联
  S->>D: 锁定事务,检查冲突,保存必要快照
  S->>A: Management API 关联 B 到 A
  S->>A: 重新读取 A,核对 identities
  S->>D: 提交业务映射,记录完成状态
  S-->>B: 更新应用会话,显示成功

每一步的后端检查:

步骤 必须检查
开始 当前会话有效;来源合法;目标连接在允许列表中
A 回调 返回主体就是发起者;认证足够新;事务未过期
B 回调 state、nonce、Token 有效;B 与 A 不同;如预选了 B,其主体必须匹配
确认 用户确认的是同一事务;没有更换主账号或次账号
写入前 重新读取双方档案;没有并发关联;业务规则允许
写入后 主账号确实包含目标身份;业务映射持久化成功
完成 会话指向预期业务用户;旧权限缓存已失效

官方服务端示例也强调:验证实际认证的目标用户与预期目标一致,再关联。示例中的 Metadata 合并顺序不能代替自己的业务冲突规则。来源:Server-Side Implementation。

7. 后端需要保存的关联事务

以下数据结构是设计建议。它存储在后端数据库或带过期时间的服务端存储中。

AccountLinkTransaction
  id                      随机、不透明的事务 ID
  initiating_session_id   发起者应用会话的关联标识
  issuer                  固定的 Auth0 签发者
  primary_user_id         A 认证后固定,不接受前端覆盖
  expected_secondary_id   推荐关联时使用;主动添加时可以暂空
  verified_secondary_id   B 认证后填写
  primary_authenticated_at
  secondary_authenticated_at
  expires_at
  status
  version                 用于并发控制
  confirmed_at
  error_code              经过脱敏的错误分类

OIDC 的 state、nonce 和 PKCE 材料由认证事务组件管理,并与此业务事务绑定。不同认证步骤使用不同的一次性状态,不把一个 state 反复用于两次登录。

推荐状态:

CREATED → PRIMARY_VERIFIED → BOTH_VERIFIED → CONFIRMED
        → LINKING → AUTH0_LINKED → COMPLETED

异常分支:CANCELLED / EXPIRED / FAILED / RECONCILIATION_REQUIRED

RECONCILIATION_REQUIRED 表示需要核对远端事实。例如请求超时,但 Auth0 可能已经完成关联。此时不应直接提示“未关联”,也不应立即重新发起一个新事务。

8. 后端 API 集成

8.1 两类 API

Authentication API 负责认证协议,例如授权和换取 Token。Management API 负责管理资源,例如查询用户、更新 Metadata 和关联身份。

设计建议:注册一个 Regular Web Application 处理用户登录;另设一个 Machine-to-Machine Application 供后端调用 Management API。后者只获得本功能所需的权限。

8.2 后端获取管理 Token

下面是 HTTP 协议示例。所有大写值都是占位符。不要直接执行。

POST https://TENANT_DOMAIN/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "BACKEND_M2M_CLIENT_ID",
  "client_secret": "BACKEND_M2M_CLIENT_SECRET",
  "audience": "https://TENANT_DOMAIN/api/v2/"
}

后端按返回的 expires_in 缓存 Token,并在到期前更新。使用 Dashboard 中 Management API 的实际 Identifier 作为 audience;不要因使用自定义登录域名就推断 audience。来源:Production Management API Tokens。

本方案通常需要 read:users 查询档案,以及 update:users 执行关联和资料更新。该管理凭据不能发给浏览器。

8.3 关联请求

POST https://TENANT_DOMAIN/api/v2/users/auth0%7Ca123/identities
Authorization: Bearer MANAGEMENT_API_ACCESS_TOKEN
Content-Type: application/json

{
  "provider": "google-oauth2",
  "user_id": "g456"
}

路径是完整主账号 ID,并做 URL 编码。请求体是次账号的 provider 与该身份的 user_id。建议从后端读取的 identities 记录中取值,避免手工拆分字符串。数据库连接存在歧义时,根据接口约定提供 connection_id。

这个管理调用使用 update:users。接口另有 link_with 模式;不要把该模式的字段与本例混合。成功响应是身份数组,不是完整用户档案。来源:Link a User Account API。

管理 Token 只能证明“后端有管理权限”。它不能证明“本次浏览器用户控制两个账号”。后一个证明由前面的双端认证和事务绑定完成。

8.4 服务职责伪代码

下面是架构伪代码,没有对应的现成 SDK 方法。它不能直接运行。

confirmLink(request):
    verifyApplicationSessionAndCsrf(request)
    tx = atomicallyClaimConfirmedTransaction(request.transactionId)
    requireTransactionOwnedByCurrentSession(tx)
    requireFreshAuthenticationForBothAccounts(tx)

    acquireExclusiveIdentityLocks(tx.primary, tx.secondary)
    primary, secondary = readCurrentAuth0Profiles(tx)
    verifySubjectsAndSupportedAccountShape(tx, primary, secondary)
    plan = validateBusinessDataPolicy(primary, secondary)
    saveRecoverySnapshotAndPlan(tx, plan)

    try:
        linkSecondaryIdentityToPrimary(tx)
    catch uncertainNetworkFailure:
        markReconciliationRequired(tx)
        return pendingResult

    confirmedProfile = readPrimaryAndVerifyExpectedIdentity(tx)
    markAuth0Linked(tx)
    commitBusinessMappingAndApprovedMetadataChanges(tx, plan)
    markCompleted(tx)
    rotateApplicationSessionForCanonicalBusinessUser(tx)
    return success

失败处理和锁释放由实现补充。所有退出路径都必须持久化明确状态;不能靠单次 HTTP 请求的内存变量恢复事务。Metadata 更新也是远端写入,可能失败,应作为可重试步骤记录。

9. 业务数据合并:需要单独设计

9.1 建议的数据模型

business_users(id, status, ...)
external_principals(issuer, subject, business_user_id, status)
account_link_transactions(id, status, version, ...)

对 (issuer, subject) 建唯一约束。旧身份映射可保留为迁移审计记录,但是否允许旧 Token 继续访问,要由明确的会话和 Token 策略决定。

9.2 两种难度不同的情况

情况 处理建议
B 尚无业务数据 将新登录方式归到 A 对应的业务用户
A、B 均有业务数据 先生成业务合并计划,处理冲突,再执行身份关联

建议逐项定义规则:

这些规则属于业务后端。Auth0 关联接口不会替应用执行它们。

9.3 为什么不能使用一个数据库事务包住所有步骤

本地数据库和 Auth0 API 没有共同的本地事务边界。数据库回滚不能撤回已成功的远端关联。

设计建议:保存计划、必要快照和步骤状态;完成一项记录一项;失败后核对事实并继续修复。快照只保存恢复所需字段,并设置访问和保留限制。不要记录 Token 或密码。

10. 失败恢复、旧 Token 与解除关联

问题 建议动作
用户取消 B 登录 取消本次关联,保留 A 的业务会话
B 登录成了另一账号 拒绝本次结果,让用户重新选择
重复点击或重复回调 原子状态转换;返回已有事务状态
两个事务争抢同一身份 使用身份级锁与唯一约束,重新读取远端档案
API 返回 401/403 检查 Token、audience、权限;不自动扩大权限
限流或服务暂时不可用 有界重试;写操作结果不明时先查事实
关联请求超时 查询主账号身份列表,判断是否已成功
Auth0 成功,本地写入失败 标记待修复,阻止继续高风险业务操作,恢复映射
Metadata 更新失败 按已保存计划重试,不把整个流程当作从未执行

设计建议:关联后重新读取主档案并轮换应用会话。旧 Token 的内容不会因档案更新而被改写。不要假设关联或退出登录会让所有既有 Access Token 立即失效。应用可按风险采用短有效期、服务端会话版本或显式撤销机制,并验证所用机制覆盖哪些 Token。

解除关联会使次身份再次成为独立账号,且该账号没有 Metadata。因此,解除关联不能当成业务合并的完整逆操作。来源:Unlink User Accounts。

设计建议:解除前要求近期认证,检查至少保留可用登录方式,并明确订单、订阅和权限如何归属。解除后验证主、次账号的登录结果与访问边界。

11. Actions:放在哪里,承担什么职责

Actions 可以在认证流程的指定触发点运行自定义代码。账号关联常涉及 Post Login:检查当前登录用户,执行额外判断,或进入外部交互流程。

官方指出:如果在 Action 挂起登录后,又在相同 Auth0 域名上启动第二次登录,原会话可能被替换,导致 /continue 恢复失败。官方同时提示,可以在登录完成后关联。若在 Action 内完成关联,还要显式处理正确的主用户切换。来源:Link User Accounts。

本文建议这样分工:

放置位置 适合的职责
Post Login Action 轻量检查、必要的自定义声明、登录流程规则
后端账号服务 双端认证事务、关联确认、业务数据计划、Management API 调用
后端恢复任务 核对远端状态、补全业务映射、处理失败步骤

设计建议:不要把订单迁移放在 Action 中;不要仅凭同邮箱执行自动关联;不要在登录关键路径中加入不可控的长任务。Action 使用的密钥与后端密钥均应通过各自受保护的配置管理。

自定义 Claim 可用于表达稳定业务用户 ID,但它只是签发时的快照。实时权限应在需要时由后端重新检查。Claim 的名称和可用 API 应按当前 Actions 文档与所用运行时确认。

12. 实验步骤与验收

这是后续可执行的学习实验计划。本次没有创建租户,也没有调用写入 API。

  1. 准备独立测试租户,确认套餐与登录方式支持所需关联能力。
  2. 注册服务端 Web 应用,配置精确回调地址与退出地址。
  3. 注册后端 M2M 应用,仅授予需要的 Management API 权限。
  4. 配置邮箱密码和一个社交连接,创建测试账号 A、B。
  5. 先打通普通登录,记录 A、B 的 (iss, sub) 与业务用户映射。
  6. 实现关联事务;先只验证 A、B,不执行关联。
  7. 加入确认页、业务规则检查、恢复记录,再接入关联 API。
  8. 分别用两种方式重新登录,核对业务用户与权限。
  9. 注入超时和本地写入失败,验证恢复流程。
  10. 单独测试解除关联,检查数据归属与剩余登录能力。

验收用例:

用例 预期结果
A、B 身份验证有效且规则允许 完成关联,两种新登录都进入正确业务用户
邮箱相同但未认证 B 不调用关联 API
前端替换主账号 ID 请求被拒绝或忽略该字段,不能改变主账号
回调 state 或 nonce 不匹配 拒绝回调,不改变账号
预选 B,却登录为 C 拒绝关联
回调重放 不再次执行写入
A、B 都有互斥权限 按业务规则阻止或进入专门处理流程
远端成功但本地失败 进入待修复状态,不显示完全成功
关联后使用旧会话 按明确策略重新验证或拒绝,不出现权限扩大
解除后 B 重新登录 不自动恢复已合并的业务权限和数据

13. 自测题

为什么相同且已验证的邮箱仍不足以直接关联?

邮箱匹配是候选发现依据。关联操作需要证明当前操作者控制两个账号,并通过本应用的业务规则。

为什么后端有 update:users,仍需重新认证用户?

管理权限授权后端修改用户。它没有证明某个浏览器请求者有权关联指定的两个账号。

为什么主账号选错会造成业务问题?

保留的 Auth0 用户标识会影响外部身份映射。如果业务表直接依赖旧标识,又没有迁移计划,用户可能进入错误档案或失去原数据入口。

为什么不把次账号的 app_metadata 全部复制过去?

其中可能有权限、组织或计费信息。合并这些字段需要独立规则,否则会扩大访问范围。

关联 API 超时,可以立刻重试吗?

先查询远端结果。请求超时只说明调用方没有收到确定结果,不说明远端没有执行。

解除关联能完整回滚吗?

不能。身份拆开与业务数据恢复是两个操作,Metadata 也不会自动恢复。

14. 官方资料与阅读顺序

以下资料于 2026-11-17 查阅。Auth0 功能、套餐、SDK 接口与文档示例会更新。本文没有指定或验证某个 SDK 版本。

  1. Auth0 Overview:先了解平台边界。
  2. Authorization Code Flow:理解后端登录。
  3. Tokens 与 Validate ID Tokens:理解认证证据。
  4. Sessions and Cookies:区分会话层。
  5. Metadata:区分资料和权限数据。
  6. User Account Linking:确认身份模型。
  7. Server-Side Implementation:理解服务端交互。
  8. Link User Accounts:用户提供的起点,含 Actions 注意事项。
  9. Link a User Account API:核对请求格式和权限。
  10. Production Management API Tokens:配置后端凭据。
  11. Unlink User Accounts:理解解除关联的边界。

验证范围:已核对上述官方页面中的核心流程、关联 API、Metadata 和解除关联行为;未对示例进行租户实测。Actions 概览和 API 对象页面在本次读取时不可访问,因此没有提供未经核对的可运行 Action 代码。