Code Bird Cloud

Appearance

M2M 组织成员管理配置指南 ​

本文档面向平台管理员、实施工程师和运维人员，介绍如何在 Code Bird Cloud 控制台中配置“第三方 M2M 应用管理组织成员”的能力。

如果你在排查旧系统为什么仍按角色名 admin 判断组织管理员，请先阅读 管理员身份判定迁移说明。当前组织管理员的最新判定方式是成员关系字段 is_admin。

如果你是第三方系统的开发工程师，请优先阅读：

本文档重点回答的是：

  • 后台要怎么配，第三方应用才能在某个组织里管理成员
  • 组织角色、组织权限、API 资源权限分别起什么作用
  • 为什么“应用已经绑定组织了”，但接口还是会返回 403
  • 如何检查某个组织下的 M2M 应用到底有没有真正拿到可用权限

一句话理解这套模型 ​

要让某个第三方 M2M 应用能够管理某个组织下的成员，后台至少要完成这四步：

text
创建 M2M 应用
  -> 准备组织角色模板
  -> 给角色模板绑定可用 scope
  -> 把应用绑定到目标组织并分配组织角色

只有“绑定组织”还不够。

真正生效的是：

text
组织内应用 -> 组织角色 -> 角色绑定的 scope -> Token 中的 scope -> API 鉴权通过

核心概念 ​

1. 应用绑定组织 ​

表示这个 M2M 应用可以在某个组织上下文里申请 Token。

如果应用没有绑定组织，即使它是一个合法的 M2M 应用，也无法用 organization_id 为该组织申请 Token。

2. 组织角色模板 ​

组织角色模板是租户级的共享模板，可以分配给：

  • 组织成员
  • 组织中的 M2M 应用

角色名本身只是一个标签，比如：

  • admin
  • member-manager
  • viewer

真正决定权限的是角色背后绑定的 scope。

3. 组织权限模板（Organization Scope） ​

这是组织内部语义的权限，比如：

  • manage:organizations
  • read:members
  • manage:settings

当 M2M 应用申请组织 Scope Token 时，Token 中的 scope 来自这里。

4. API 资源权限（Resource Scope） ​

这是某个 API Resource 上定义的 scope，比如 Management API Resource 上的：

  • all

当 M2M 应用申请组织级 API 资源 Token 时，Token 中的 scope 来自这里。

5. 组织管理员 ​

组织管理员是组织成员关系上的独立标记，不是第三方应用可操作的对象。

当前规则：

  • 后台管理员可以设置和取消组织管理员
  • 第三方 M2M 应用不能设置管理员
  • 第三方 M2M 应用不能取消管理员
  • 第三方 M2M 应用不能移除管理员
  • 后台也不能把最后一个管理员取消掉或移除掉

推荐配置方式 ​

如果你的目标是让第三方应用管理组织成员，推荐按以下方式设计：

  • 使用一个专门的组织角色模板，例如 org-member-manager
  • 给这个角色模板配置成员管理所需 scope
  • 把这个角色分配给目标组织中的目标 M2M 应用

不建议直接依赖角色名称，例如“角色名叫 admin 就应该能管成员”。

正确的判断方式应该是：

  • 这个角色有没有绑定 manage:organizations
  • 或这个角色有没有绑定 Management API Resource 的 all

控制台配置步骤 ​

第 1 步：创建 M2M 应用 ​

导航路径：

text
控制台 -> 应用管理

操作：

  1. 点击“新建应用”
  2. 选择类型 MachineToMachine
  3. 填写应用名称和描述
  4. 创建后保存 Client ID 和 Client Secret

注意：

  • 只有 MachineToMachine 类型的应用才能使用 client_credentials
  • 后续第三方系统会使用这个应用的 Client ID / Client Secret

第 2 步：准备组织角色模板 ​

导航路径：

text
控制台 -> 组织模板

操作建议：

  1. 新建一个组织角色模板，例如 org-member-manager
  2. 为这个角色写清楚用途描述，例如“允许第三方系统管理组织普通成员”

建议不要直接复用语义不清晰的角色名，例如泛化的 admin。更推荐使用与业务能力对应的角色名。

第 3 步：为组织角色模板绑定权限 ​

这一步是最关键的。

方式 A：绑定组织权限模板 ​

在“组织模板 -> 角色模板 -> 管理权限”中，给角色模板分配组织权限模板。

如果你走的是组织 Scope Token 模式，至少要确保角色模板绑定了：

  • manage:organizations

方式 B：绑定 API 资源权限 ​

在“组织模板 -> 角色模板 -> API 资源权限”中，给角色模板分配 Management API Resource 上的 scope。

如果你走的是组织级 API Resource Token 模式，至少要确保角色模板绑定了：

  • all

推荐做法 ​

推荐优先使用 方式 B，即：

  • 让第三方应用请求组织级 API Resource Token
  • 组织角色模板上配置 Management API 的资源权限

原因：

  • 更接近标准 API Resource 授权模型
  • 权限来源更清晰
  • 后续如果拆分更细粒度资源 scope，更容易演进

第 4 步：把应用绑定到目标组织 ​

导航路径：

text
控制台 -> 组织管理 -> 编辑组织 -> 机器对机器应用

操作：

  1. 点击“绑定应用”
  2. 选择需要接入的 M2M 应用
  3. 完成绑定

绑定完成后，这个应用才有资格用该组织的 organization_id 申请 Token。

如果没有这一步，请求 Token 时通常会出现：

  • access_denied
  • 应用未绑定到该组织

第 5 步：给这个组织中的应用分配组织角色 ​

仍在：

text
控制台 -> 组织管理 -> 编辑组织 -> 机器对机器应用

操作：

  1. 在应用列表中找到目标 M2M 应用
  2. 点击“管理角色”
  3. 给它分配前面创建好的组织角色模板

这一层关系是：

text
某个组织下的某个应用 -> 组织角色模板

不是全局应用角色，也不是后台管理员角色。

第 6 步：验证成员管理能力是否真正生效 ​

配置完成后，建议按下面的顺序验证。

检查 1：应用是否已经绑定组织 ​

在组织编辑页的“机器对机器应用”标签中确认：

  • 目标应用已经出现在列表里

检查 2：应用是否已经分配组织角色 ​

确认：

  • 该应用所在行的“组织角色”列已经有角色

检查 3：该组织角色是否绑定了正确的 scope ​

去“组织模板”里检查这个角色模板：

  • 是否绑定了 manage:organizations
  • 或是否绑定了 Management API 的 all

检查 4：第三方系统拿到的 Token 是否带了 organization_id ​

如果第三方提供了解析后的 JWT，可以确认：

  • token_type = "m2m"
  • organization_id = 目标组织 ID
  • scope 中包含 manage:organizations 或 all

如果缺了这些字段，通常说明后台角色和 scope 没配完整。

组织成员页中的管理员功能 ​

导航路径：

text
控制台 -> 组织管理 -> 编辑组织 -> 成员管理

当前页面支持：

  • 查看成员列表
  • 查看成员是否为管理员
  • 设置成员为管理员
  • 取消成员管理员身份
  • 给成员分配组织角色
  • 移除普通成员

管理员保护规则 ​

当前后台有两条硬限制：

  1. 不能移除最后一个组织管理员
  2. 不能取消最后一个组织管理员的管理员身份

这两条规则是为了保证每个组织始终有至少一名管理员。

推荐实施流程 ​

建议平台管理员按这个顺序操作：

  1. 创建 M2M 应用
  2. 创建或选择组织角色模板
  3. 给组织角色模板绑定需要的 scope
  4. 创建组织或进入已有组织
  5. 绑定 M2M 应用到目标组织
  6. 给该组织中的应用分配组织角色
  7. 如有需要，在成员管理页设置组织管理员
  8. 交付 Client ID、Client Secret、organization_id 给第三方系统
  9. 让第三方系统按接入文档调用接口验证

常见误区 ​

误区 1：绑定了组织就一定能调用接口 ​

不是。

绑定组织只代表这个应用具备“申请该组织上下文 Token”的资格，不代表一定有 API 权限。

还必须有：

  • 组织角色
  • 角色绑定的 scope

误区 2：角色名叫 admin 就一定有管理权限 ​

不是。

系统真正看的是 scope，不是角色名。

如果 admin 这个角色模板没有绑定 manage:organizations 或 all，那第三方应用依然会 403。

误区 3：第三方应用可以维护组织管理员 ​

不是。

当前实现里：

  • 第三方应用可以查看管理员
  • 不能设置管理员
  • 不能取消管理员
  • 不能移除管理员

常见故障排查 ​

场景 1：请求 Token 时报“应用未绑定到该组织” ​

排查：

  • 这个应用是否已经绑定到目标组织
  • 请求里的 organization_id 是否正确

场景 2：调用成员接口时报“组织上下文不匹配” ​

排查：

  • 请求 Token 时传入的 organization_id
  • 调用 API 时 URL 中的组织 ID

这两个值必须完全一致。

场景 3：调用成员接口时报“权限不足” ​

排查：

  1. 应用是否在该组织下分配了组织角色
  2. 该组织角色是否绑定了 manage:organizations
  3. 或该组织角色是否绑定了 Management API 的 all

场景 4：第三方应用无法移除某个成员 ​

如果错误提示与管理员保护相关，说明目标成员是组织管理员。

处理方式：

  • 由后台管理员先处理管理员身份
  • 再决定是否允许该成员离开组织

与其他文档的关系 ​

建议后台管理员按以下顺序阅读：

  1. 应用管理
  2. 组织模板
  3. 组织管理
  4. 本文档：M2M 组织成员管理配置指南
  5. M2M 组织成员管理接入指南

Released under the MIT License.

Copyright 2024-present Code Bird Team