组织级登录

本文档介绍如何实现组织级别的 OIDC 登录，使第三方应用能在特定组织上下文中完成用户认证和授权。

两种模式

Code Bird Cloud 支持两种组织登录模式：

模式	适用场景	复杂度
一阶段模式	从特定组织入口登录，一步到位获取组织上下文 Token	低
两阶段模式	先统一登录，再按需获取不同组织的 Token（适合多组织切换）	中

---

一阶段模式（推荐用于单组织场景）

在 OIDC 授权请求中直接传入 organization_id，系统会在登录完成后自动验证用户的组织成员关系，并返回限定于该组织的 Token。

流程

1. 应用发起授权请求，携带 organization_id
   GET /oidc/authorize?
     client_id=YOUR_CLIENT_ID&
     redirect_uri=YOUR_CALLBACK_URL&
     response_type=code&
     scope=openid profile email offline_access urn:codebird:scope:organizations urn:codebird:scope:organization_roles&
     organization_id=ORG_ID&
     state=RANDOM_STATE

2. 用户在登录页完成身份认证

3. 系统自动验证：
   - 用户是否属于指定的组织
   - 若不属于，返回 access_denied 错误

4. 应用收到回调，用 code 换取 Token
   POST /oidc/token
     grant_type=authorization_code&
     code=AUTH_CODE&
     redirect_uri=YOUR_CALLBACK_URL&
     client_id=YOUR_CLIENT_ID&
     client_secret=YOUR_CLIENT_SECRET

请求参数

参数	必填	说明
organization_id	否	组织 ID。传入后启用组织级登录
organization_code	否	organization_id 的别名，两者等价

返回的 Token Claims

当指定 organization_id 后，ID Token 和 Access Token 中的组织相关 claims 仅包含该组织的数据：

{
  "sub": "用户ID",
  "organization_id": "org_123",
  "organizations": ["org_123"],
  "organization_roles": ["org_123:admin", "org_123:member"],
  "username": "admin",
  "email": "user@example.com"
}

UserInfo 响应

调用 GET /oidc/userinfo 时，组织 claims 同样限定于登录时指定的组织：

{
  "sub": "用户ID",
  "organization_id": "org_123",
  "organizations": ["org_123"],
  "organization_roles": ["org_123:admin"],
  "username": "admin"
}

错误处理

错误	说明
access_denied + "用户不是该组织的成员"	用户成功登录但不属于请求的组织

---

两阶段模式（适合多组织切换）

先进行标准 OIDC 认证（不指定组织），获取包含用户全部组织列表的 Token 和 refresh_token，然后使用 refresh_token 按需获取特定组织的 Token。

阶段一：标准认证

GET /oidc/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_CALLBACK_URL&
  response_type=code&
  scope=openid profile email offline_access urn:codebird:scope:organizations urn:codebird:scope:organization_roles&
  state=RANDOM_STATE

注意：不传 organization_id。

Token 交换后，ID Token 包含用户所属的全部组织：

{
  "sub": "用户ID",
  "organizations": ["org_1", "org_2", "org_3"],
  "organization_roles": ["org_1:admin", "org_2:member"]
}

应用可据此展示组织切换器，让用户选择进入哪个组织。

阶段二：获取组织级 Token

使用 refresh_token 获取特定组织的 Access Token：

POST /oidc/token
  grant_type=refresh_token&
  refresh_token=YOUR_REFRESH_TOKEN&
  organization_id=org_1

返回的 Access Token 示例：

{
  "aud": "urn:codebird:organization:org_1",
  "sub": "用户ID",
  "organization_id": "org_1",
  "organization_name": "Acme 公司",
  "organization_roles": ["admin"],
  "scope": "manage:members read:members manage:projects read:projects"
}

字段	说明
aud	urn:codebird:organization:{org_id} — 标识这是组织级 Token
organization_id	组织 ID
organization_name	组织名称
organization_roles	用户在该组织内的角色名称列表（不含 org_id 前缀）
scope	用户在该组织内所有角色绑定的组织权限模板名称的并集

如果用户不是该组织的成员，返回 403 access_denied。

组织级 API 资源 Token

如果需要在组织上下文中访问特定 API 资源，额外传入 resource 参数：

POST /oidc/token
  grant_type=refresh_token&
  refresh_token=YOUR_REFRESH_TOKEN&
  organization_id=org_1&
  resource=https://api.yourapp.com

返回的 Access Token 示例：

{
  "aud": "https://api.yourapp.com",
  "sub": "用户ID",
  "organization_id": "org_1",
  "scope": "read:orders write:orders"
}

字段	说明
aud	API 资源标识符（而非组织标识符）
organization_id	组织 ID
scope	用户在该组织内所有角色绑定的 API 资源权限名称的并集

---

organization_roles 格式

组织角色采用 组织ID:角色名称 格式的字符串数组：

{
  "organization_roles": [
    "org_123:admin",
    "org_456:member",
    "org_456:viewer"
  ]
}

这种格式方便解析，也与 Logto 的设计保持一致。

---

前置配置

使用组织级登录前，需确保以下配置。可以通过管理后台图形界面（授权 → 组织模板）或 API 完成。

1. 创建权限模板（可选，但推荐）

在管理后台 授权 → 组织模板 → 权限模板 Tab 中创建，或通过 API：

POST /api/v1/organization-permissions
{ "name": "manage:members", "description": "管理组织成员" }

2. 创建角色模板

在管理后台 授权 → 组织模板 → 角色模板 Tab 中创建，或通过 API：

POST /api/v1/organization-roles
{ "name": "admin", "description": "组织管理员" }

3. 为角色绑定权限

在角色模板列表点击「管理权限」按钮，或通过 API：

PUT /api/v1/organization-roles/:id/scopes
{ "scope_ids": ["perm_id_1", "perm_id_2"] }

如需绑定 API 资源权限：

PUT /api/v1/organization-roles/:id/resource-scopes
{ "scope_ids": ["api_scope_id_1"] }

4. 创建组织并添加成员

在管理后台 组织 页面操作，或通过 API：

# 创建组织
POST /api/v1/organizations  { "name": "Acme 公司" }

# 添加成员
POST /api/v1/organizations/:id/users  { "user_ids": ["user_id_1"] }

# 分配角色
PUT /api/v1/organizations/:id/users/:userId/roles  { "role_ids": ["admin_role_id"] }

5. 应用授权请求 Scope

第三方应用的 OIDC 授权请求中需包含以下 scope：

Scope	作用
urn:codebird:scope:organizations	Token 中返回 organizations 列表
urn:codebird:scope:organization_roles	Token 中返回 organization_roles 列表
offline_access	获取 refresh_token（两阶段模式必须）

详细的配置步骤参见 组织配置。

相关文档

• 组织管理 — 组织功能概述
• 组织配置 — 权限模板、角色模板创建与分配
• 成员管理 — 组织成员操作
• 组织级 RBAC — 组织角色与权限、Token 中的权限体现
• M2M 组织级 Token — 机器对机器的组织级认证