第三方应用组织权限集成指南

本文档面向接入 Code Bird Cloud 的第三方应用工程师，说明如何获取和使用用户在组织中的角色与权限信息。

权限体系结构

权限模板（scope）: manage:members, read:members, read:projects ...
       ↓ 绑定
角色模板（role）: admin, member, viewer
       ↓ 分配给
用户在某个组织中的角色: 张三 → org_123 → admin
       ↓ 体现在
OIDC Token 的 claims 中

Code Bird Cloud 管理员已在后台完成权限模板创建、角色模板创建、角色-权限绑定、用户-组织-角色分配等配置。第三方应用无需关心配置细节，只需从 Token 中读取权限信息。

集成步骤

第一步：授权请求中添加必要的 scope

在发起 OIDC 授权请求时，scope 参数需包含以下值：

scope=openid profile email offline_access urn:codebird:scope:organizations urn:codebird:scope:organization_roles

Scope	作用
`urn:codebird:scope:organizations`	Token 中返回用户所属的组织列表
`urn:codebird:scope:organization_roles`	Token 中返回用户在组织中的角色
`offline_access`	获取 refresh_token（获取带权限的组织 Token 必须）

第二步：获取带权限的组织级 Token

标准登录换取 Token 后，ID Token 中只有角色名称，没有具体权限列表。要获取具体权限，需要用 refresh_token 再换一次组织级 Token：

http

POST /oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
organization_id=org_123&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

第三步：从返回的 Access Token 中读取权限

返回的 Access Token（JWT）解码后结构如下：

json

{
  "aud": "urn:codebird:organization:org_123",
  "sub": "user_zhangsan",
  "organization_id": "org_123",
  "organization_name": "Acme 公司",
  "organization_roles": ["admin"],
  "organization_is_admin": true,
  "scope": "manage:members read:members manage:projects read:projects"
}

注意：这里展示的是组织级 Access Token 的 payload 示例。因为它已经固定在单一组织上下文中，organization_roles 可以是当前组织下的纯角色名数组，例如 ["admin"]。如果你是在前端 SDK 的轻量 claims 中读取多组织角色，或在标准 /oidc/userinfo 中读取组织角色，请以 ["org_id:role_name"] 的字符串数组格式为准。

关键字段说明：

字段	类型	说明
`organization_id`	string	当前组织 ID
`organization_name`	string	当前组织名称
`organization_roles`	string[]	用户在该组织中的角色名称列表
`organization_is_admin`	boolean	当前用户在该组织下是否为组织管理员
`scope`	string	用户的实际权限列表（空格分隔），是该用户所有角色绑定权限的并集

第四步：在应用中做权限判断

javascript

const decoded = decodeJWT(access_token);

// 判断当前用户是否为组织管理员
if (decoded.organization_is_admin === true) {
  // 组织管理员逻辑
}

// 判断具体权限（推荐）
const scopes = decoded.scope.split(" ");
if (scopes.includes("manage:members")) {
  // 允许成员管理操作
}
if (scopes.includes("read:projects")) {
  // 允许查看项目
}

完整流程示例

1. 第三方应用发起授权请求
   GET /oidc/authorize?
     client_id=xxx&
     redirect_uri=xxx&
     response_type=code&
     scope=openid profile email offline_access urn:codebird:scope:organizations urn:codebird:scope:organization_roles&
     organization_id=org_123&
     state=xxx

2. 用户登录 → 回调返回 code

3. 用 code 换取 Token（获得 id_token + access_token + refresh_token）
   POST /oidc/token
     grant_type=authorization_code&code=xxx&...

   此时 id_token 中有：
   {
     "organization_id": "org_123",
     "organization_roles": ["org_123:admin"],  ← 格式：组织ID:角色名
     "organization_is_admin": true
   }

4. 用 refresh_token 换取组织级 Token：
   POST /oidc/token
     grant_type=refresh_token&
     refresh_token=xxx&
     organization_id=org_123&
     client_id=xxx&
     client_secret=xxx

   返回的 access_token 中有：
   {
     "organization_roles": ["admin"],            ← 角色名
     "organization_is_admin": true,              ← 当前组织管理员标记
     "scope": "manage:members read:members ..."   ← 具体权限
   }

说明：第 4 步返回的是组织级 Token，它面向当前组织的权限判断和资源访问。如果你的前端需要获取“当前用户实时是否仍属于该组织、是否仍为组织管理员、当前应用是什么”，建议继续调用 GET /api/session/context，不要只依赖登录时的 claims 快照。

两种用法对比

	只用第 3 步的 Token	加上第 4 步的组织级 Token
获取内容	角色名称 + 当前组织管理员标记	角色名称 + 当前组织管理员标记 + 具体权限 scope
权限判断方式	按角色名称判断	按 scope 精确判断
是否需要 refresh_token	否	是（scope 需含 `offline_access`）
适用场景	简单场景，角色即权限	需要细粒度权限控制

组织级 API 资源 Token

如果第三方应用有受保护的 API 资源（已在 Code Bird Cloud 注册），可在第 4 步额外传入 resource 参数：

http

POST /oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
organization_id=org_123&
resource=https://api.yourapp.com&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

返回的 Access Token：

json

{
  "aud": "https://api.yourapp.com",
  "sub": "user_zhangsan",
  "organization_id": "org_123",
  "scope": "read:orders write:orders"
}

此时 aud 为 API 资源标识符，scope 为该用户角色绑定的 API 资源权限。

错误处理

场景	返回	说明
用户不是该组织成员	`403 access_denied`	登录成功但不属于指定组织
组织 ID 不存在	`400 invalid_request`	检查 organization_id 是否正确
缺少 offline_access scope	无 refresh_token 返回	无法执行第 4 步获取组织级 Token

第三方应用组织权限集成指南 ​

权限体系结构 ​

集成步骤 ​

第一步：授权请求中添加必要的 scope ​

第二步：获取带权限的组织级 Token ​

第三步：从返回的 Access Token 中读取权限 ​

第四步：在应用中做权限判断 ​

完整流程示例 ​

两种用法对比 ​

组织级 API 资源 Token ​

错误处理 ​

相关文档 ​