组织模板
Logto 中的 组织模板 定义了你 SaaS 产品中每个组织（租户）可用的一套一致的角色和权限。通过集中管理这些定义，你可以强化安全性，实现可扩展的入驻流程，并确保所有组织都拥有出色的用户体验。
如果你没有构建多租户应用，或者不需要组织特定的角色 / 权限，可以跳过本节。Logto 的全局角色和权限已足够满足单租户或非组织型应用的需求。
什么是组织模板？
组织模板是一种蓝图，指定了每个组织中可用的角色和权限。你在 Logto 租户中创建的每个组织都会自动继承该模板，从而保证所有租户拥有一致的授权 (Authorization) 模型。
- 为什么要使用模板？
- 为每个组织强制执行统一的访问控制策略。
- 简化新租户和团队成员的入驻流程。
- 随着产品发展，使基于角色的访问控制 (RBAC) 的更新和审计更加容易。
核心概念
- 组织角色 (Organization roles)： 在组织内授予用户或 M2M（机器对机器）客户端的一组权限。角色定义了每个组织内部“谁可以做什么”。
- 组织权限 (Organization permissions)： 可分配给角色的细粒度非 API 操作（如 UI 功能、业务逻辑）。
- API 资源： 由权限保护的 API 端点 / 服务。组织角色可以关联 API 资源，实现组织范围的 API 访问。
- 角色-权限映射 (Role-permission mapping)： 模板中的每个组织角色都可以映射到一个或多个权限。
- 模板传播 (Template propagation)： 对模板的更改会更新所有组织可用的角色和权限。
组织角色和权限（包括 API 资源权限）与全局角色及其权限是不同的。但 API 资源及其权限是集中定义的，可以在全局和组织场景中引用。
与全局角色和权限的对比
角色类型对比
| 角色类型 | 可以拥有 API 资源权限？ | 可以拥有组织（非 API）权限？ |
|---|---|---|
| 全局 | 是 | 否 |
| 组织 | 是 | 是 |
权限类型对比
| 权限类型 | 定义位置 | 可分配给全局角色？ | 可分配给组织角色？ |
|---|---|---|---|
| API 资源 | API 资源实体 | 是 | 是 |
| 组织 | 组织模板 | 否 | 是 |
组织模板结构
一个组织模板由以下部分组成：
- 角色： 如
Admin、Member、Viewer、Billing - 组织权限 (Organization permissions)： 如
invite:member、manage:billing、view:analytics - 角色-权限矩阵 (Role-permission matrix)： 显示每个角色授予哪些权限（包括组织权限和 API 资源权限）的映射关系。
可视化概览
在 Logto 中创建的每个组织都会拥有同样的一套角色和权限，用户 / 客户端可以根据需要在每个组织中被分配不同的角色。
在你的产品中使用组织模板
Logto 的组织模板专为现代多租户 SaaS 应用设计，适用于以下场景：
- 每个组织在入驻、协作和管理时都应拥有相同的角色和权限选项。
- 你希望避免为每个新组织手动定义角色 / 权限。
- 一致的基于角色的访问控制 (RBAC) 对合规、安全和客户信任至关重要。
- 你需要随着产品变化灵活调整访问控制，而不会影响现有组织。
示例用例
- 提供工作区、团队或公司（每个为一个租户）的 SaaS 产品。
- 每个组织内有细粒度管理员 / 成员 / 观察者角色的平台。
- 同时拥有 API 和非 API 权限的产品。
最佳实践与版本管理
- 保持角色和权限以业务为导向： 使用能映射到实际操作的清晰名称（不仅仅是技术端点）。
- 避免角色 / 权限泛滥： 从简单开始，只有在产品真正需要时才添加新角色 / 权限。
- 沟通变更： 如果组织中的角色或权限选项即将变更，请及时通知用户 / 管理员。
- 持续演进模板： 随着产品发展，你可以随时更新模板，所有组织会自动获得新角色 / 权限。
- 版本管理（可选）： 对于重大变更，建议对模板进行版本管理，并向客户沟通迁移方案。
管理你的组织模板
你可以通过 控制台 → 组织模板 或 Logto Management API 管理组织模板。
- 创建角色： 向模板添加用户角色和 M2M 角色。每个角色对 Logto 租户下所有组织可用。
- 创建权限： 为 API 资源和非 API（应用内）操作定义权限。
- 编辑角色-权限矩阵： 使用 Logto 控制台或 Management API 将权限分配给角色。
- 更新或删除角色 / 权限： 对模板的更改会自动应用到所有组织。（用户 / 客户端的角色分配保持不变，仅权限集发生变化。）
关于如何管理组织角色和权限的分步指南，请参见 基于角色的访问控制 (RBAC)。
常见问题
我必须使用组织权限吗？
不需要，组织权限是可选的。如果你愿意，也可以仅用组织模板来定义角色和 API 资源权限。
如果我更改了组织模板会发生什么？
对角色或权限的更改会立即反映到所有组织。用户和客户端的角色分配保持不变，只是这些角色所拥有的权限可能发生变化。
我可以为每个组织自定义角色或权限吗？
不能直接自定义。组织模板在所有租户间强制执行一致的模型。（你仍然可以在每个组织中为不同用户 / 客户端分配不同的角色。）
如何回滚或迁移变更？
手动更新模板以恢复之前的角色 / 权限。对于复杂迁移，建议采用版本管理策略。
如果我删除了某个角色或权限会怎样？
拥有该角色的用户 / 客户端将失去与之关联的权限。删除某个权限会将其从所有拥有该权限的角色中移除。