第三方对接总览

本文档面向第三方工程师、客户自研系统工程师和实施团队。

如果你要做的是下面任意一件事，请先读本页，再进入细分文档：

• 让终端用户通过 Code Bird Cloud 登录你的系统
• 在前端使用官方 React SDK 承接登录、回调、Token 刷新和账户中心跳转
• 在 Go 后端验证 Access Token，并根据用户 / 组织上下文做鉴权
• 使用 M2M 方式调用 Code Bird Cloud 的组织成员管理接口

本文档只做三件事：

1. 帮你判断应该走哪条接入路线
2. 明确前端、后端各自应该使用哪些官方能力
3. 统一第三方接入时最容易出错的字段口径、Token 约定和最佳实践

先判断你的接入场景

目标	推荐方案	推荐文档
让终端用户登录 React SPA	@codebird/react	React SDK 集成教程
React 前端 + Go 后端完整接入	React SDK + Go Verifier SDK	React SPA + Go 后端 SDK 配套接入
Go 后端验证前端带来的 Access Token	codebird-go-sdk Verifier	Go Verifier SDK 集成教程
业务后端使用 M2M 管理组织成员	codebird-go-sdk M2MClient	Go M2M 组织成员管理 SDK
快速安装、锁版本、升级 SDK	React SDK / Go SDK	SDK 安装与升级说明

当前推荐的前后端职责分工

这是当前对第三方系统最稳定、最推荐的职责划分。

前端 React SPA 负责

• 发起登录
• callback 页面处理
• 本地登录态恢复
• Access Token 自动续期
• 获取面向业务 API 的 Access Token
• 获取实时会话上下文
• 打开账户中心
• 在未认证态重新发起登录

推荐统一使用：

• @codebird/react

Go 业务后端负责

• 验证前端带来的 Bearer Token
• 从 Token claims 中读取轻量用户 / 组织上下文
• 基于 AuthContext 做接口鉴权
• 在需要最新数据库状态时，调用 /api/session/context
• 在需要服务端管理能力时，使用 M2M Token 调用管理接口

推荐统一使用：

• github.com/lshaofan/codebird-go-sdk

其中 M2MClient 当前正式支持的组织成员管理方法为：

• ListOrganizationMembers
• AddOrganizationMember
• RemoveOrganizationMember
• GetOrganizationMemberRoles
• UpdateOrganizationMemberRoles

明确不推荐的做法

• 前端自己维护一套 oidc-client-ts UserManager
• 前端自己直调 /oidc/token
• 前端自己根据 expires_at 判断是否跳登录页
• 前端自己监听 token 过期事件后直接清空本地登录态
• 前端自己拼裸 /sign-in 或裸 /account-center/...
• Go 后端自己手写 JWKS 拉取、JWT 验签和组织 claims 解析

当前接入模型的核心变化

这是 2026-03 之后第三方必须了解的接入约定。

1. 终端用户入口已经租户路径化

终端用户正式入口不再推荐使用裸路径：

• 不再推荐：/sign-in
• 不再推荐：/register
• 不再推荐：/forgot-password
• 不再推荐：/account-center/...

当前标准入口是：

• /t/{tenant.slug}/sign-in
• /t/{tenant.slug}/register
• /t/{tenant.slug}/forgot-password
• /t/{tenant.slug}/account-center/...

React SDK 和 Go SDK 都已经提供对应 helper。

2. 实时会话上下文已经返回顶层 tenant

推荐从 GET /api/session/context 获取：

• tenant.id
• tenant.slug
• tenant.name

其中 tenant.slug 是第三方拼接终端用户租户化 URL 的标准标识。

3. React SDK 已经内建 Token 生命周期管理

当前 React SDK 已经负责：

• Access Token 可用性判断
• audience / resource 匹配判断
• Access Token 自动刷新
• refresh_token + resource 续期
• refresh token 失效后的本地登录态清理

第三方项目不应该再在外面重复写一套。

Token 生命周期最佳实践

这是最近最容易踩坑的部分，建议第三方工程师严格按下面理解。

Access Token

前端永远不要缓存“自己理解的 access token 生命周期”。

正确做法：

• 需要请求业务 API 时，调用 auth.getAccessToken()
• 需要读取实时上下文时，调用 auth.getSessionContext()
• 需要打开账户中心时，调用 auth.openAccountCenter()

这些能力都会先检查当前 token 是否还能用于目标 resource。

Refresh Token

Refresh Token 只用于 SDK 内部续期。

第三方不要：

• 自己保存 refresh token 做直调 /oidc/token
• 自己实现 refresh 队列
• 自己在前端判断 refresh token 是否过期

当 refresh token 已失效时，React SDK 会：

1. 识别 /oidc/token 返回的 invalid_grant
2. 清理本地登录态
3. 将认证状态切回未登录

然后由第三方的未认证处理逻辑决定是否重新登录。

推荐的未认证处理

如果你们使用官方守卫 CodeBirdAuthGuard，推荐接法是：

<CodeBirdAuthGuard
  loadingFallback={<div>Loading...</div>}
  unauthenticatedFallback={<div>Redirecting...</div>}
  onUnauthenticated={() => auth.signIn()}
>
  <App />
</CodeBirdAuthGuard>

这意味着：

• Access Token 过期但 Refresh Token 仍有效：SDK 自动续期，用户无感
• Refresh Token 过期：SDK 自动清本地状态，Guard 自动重新发起登录

轻量 claims 与实时上下文

第三方必须区分这两类数据来源。

来源	适合做什么	不适合做什么
Access Token claims / /oidc/userinfo	判断当前登录用户是谁、显示轻量身份信息、标准 OIDC 集成	判断用户当前是否仍在组织内、判断组织管理员状态是否已被后台改动
/api/session/context	获取用户、应用、组织和租户的最新数据库状态	替代标准 OIDC 登录协议

推荐原则：

• 首屏轻量展示可以先用 claims
• 权限判断、组织切换、管理员状态判断优先用实时上下文

当前字段口径

这是第三方最容易混淆的地方，当前统一按下面理解：

场景	字段	含义
OIDC 用户登录	organization_is_admin	当前登录用户在当前组织下是否为管理员
实时会话上下文	organization.is_admin	当前上下文组织下是否为管理员
组织成员管理接口	is_admin	目标成员是否为该组织管理员
OIDC claims	organization_roles	组织角色字符串数组，不再作为管理员判定依据
会话上下文	tenant.slug	终端用户租户化入口的标准路径标识

补充说明：

• organization_roles 当前标准格式是：["org_123:admin", "org_456:member"]
• 不要再根据 organization_roles 中是否包含 admin 推断管理员身份
• 管理员身份只看明确布尔字段：
  • claims：organization_is_admin
  • 实时上下文：organization.is_admin
  • 组织成员列表：is_admin

前后端必须对齐的参数

无论你用 React SDK、Go SDK 还是标准 OIDC 客户端，这几个值必须对齐。

概念	前端	后端
认证中心地址	React SDK endpoint	Go SDK Issuer
业务 API Resource	React SDK defaultResource	Go SDK Audience
终端用户租户路径标识	tenant.slug	如果后端要拼 URL，同样使用 tenant.slug
当前组织上下文	defaultOrganizationId 或 signIn({ organizationId })	从 Token claims / Session Context 读取

最关键的一条是：

React defaultResource == Go Audience

如果这两个值不一致，后端通常会返回 401，前端也会出现重复续期或错误 audience 的问题。

推荐阅读顺序

路线 A：React 前端接入

1. SDK 安装与升级说明
2. React SDK 集成教程
3. 如果前端还需要调 Go 业务后端，再读： React SPA + Go 后端 SDK 配套接入

路线 B：Go 后端接入

1. SDK 安装与升级说明
2. Go Verifier SDK 集成教程
3. 如果还要调组织成员管理，再读： Go M2M 组织成员管理 SDK

路线 C：需要最新权限 / 组织状态

1. 实时会话上下文 API
2. React SDK 集成教程
3. Go Verifier SDK 集成教程

常见误区

误区 1：前端自己判断 token 是否过期

不推荐。

应当让 React SDK 内部统一处理，业务代码只通过 SDK 取 token。

误区 2：refresh token 过期时 SDK 会默认跳到登录页

不完全对。

SDK 会自动清理本地登录态，但是否自动重新登录，取决于你是否在未认证态调用 auth.signIn()。推荐使用 CodeBirdAuthGuard。

误区 3：第三方应该自己拼 /sign-in

不推荐。

应优先：

• 用 React SDK 发起 auth.signIn()
• 或使用 SDK 提供的租户化 URL helper

误区 4：所有鉴权都只看 Access Token claims

不推荐。

claims 更像“登录时快照”。需要数据库最新状态时，请使用 /api/session/context。

相关文档

• 集成概览
• React SDK 集成教程
• Go Verifier SDK 集成教程
• React SPA + Go 后端 SDK 配套接入
• SDK 安装与升级说明
• 实时会话上下文 API