跳到主要内容

使用 Logto Management API 配置你的应用服务

Logto 提供了强大的 Management API，让你可以在应用内创建并自定义自己的组织 (Organization) 流程。 理解其工作原理是设计自定义方案的关键。以下是集成 Management API 以实现组织 (Organization) 体验的基本步骤和概要。

如果你已经了解基础知识，可以直接跳转到教程。熟悉设置后，你还可以探索更多 API，以根据业务需求定制其余流程。

建立机器对机器 (Machine-to-Machine) 连接​

Logto 使用机器对机器 (M2M) 认证 (Authentication)，安全地将你的后端服务连接到 Logto Management API 端点。 你的后端服务随后可以使用 Management API 处理与组织 (Organization) 相关的任务，如创建组织 (Organization)、添加或移除成员等。

具体步骤如下：

  1. 在 Logto 控制台中创建一个机器对机器 (M2M) 应用。
M2M app details
  1. 从 Logto 获取 M2M 访问令牌 (Access token)。了解更多。
  2. 从你的后端服务调用 Logto Management API。例如，列出所有组织 (Organizations)：
curl \
 -X GET https://[tenant_id].logto.app/api/organizations \
 -H "Authorization: Bearer $M2M_ACCESS_TOKEN" \
 -H "Content-Type: application/json"

保护你的应用服务器​

由于终端用户可以自行执行某些组织 (Organization) 操作，因此在终端用户与应用服务器之间添加授权 (Authorization) 层非常重要。你可以根据所用的 Logto Management API 端点以及产品 API 的结构，将此层应用于全局或组织 (Organization) 级别。服务器应拦截每个请求，验证用户的组织令牌 (Organization token) 及所需权限 (Scopes)，然后仅使用服务器持有的 M2M 凭证调用 Management API。

当用户提交组织令牌 (Organization token) 请求某个操作（例如创建组织 (Organization)）时，服务器首先验证令牌中的权限 (Scopes)。如果令牌包含所需权限 (Scope)，如 org:create，则授权 (Authorization) 请求，并通过 M2M 流程调用 Logto Management API 创建组织 (Organization)。

如果令牌不包含所需权限 (Scopes)，则返回 403 Forbidden 并跳过 M2M 逻辑。这确保了没有相应权限的用户无法创建组织 (Organization)。

以下是常见的授权 (Authorization) 模式。

使用组织 (Organization) 权限 (Permissions)​

首先，确保你已在上一节的组织 (Organization) 模板中定义了组织 (Organization) 权限 (Permissions) 和角色 (Roles)。

然后，确保在 Logto 配置中包含了 UserScope.Organizations（值：urn:logto:organization）。以 React SDK 为例：

// src/App.js
import { UserScope } from '@logto/react';

const config = {
  endpoint: 'https://<tenant-id>.logto.app/', // 你的 Logto endpoint
  appId: '40fmibayagoo00lj26coc', // 你的 app id
  resources: [
    'https://my.company.com/api', // 你的全局 API 资源标识符
  ],
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations, // 请求组织令牌 (Organization token)
  ],
};

这样，当调用 getOrganizationToken(organizationId) 时，客户端 SDK 会请求包含分配给用户的组织 (Organization) 权限 (Permissions) 的组织令牌 (Organization token)。你的后端服务随后可以验证该令牌，并根据这些权限 (Permissions) 授权 (Authorization) 后续请求。

关于保护组织级（非 API）权限 (Permissions) 的详细信息，请参阅完整指南。

使用 API 级权限 (Permissions)​

当你的 API 资源和权限 (Permissions) 在全局注册，但角色 (Roles) 在组织 (Organization) 级别定义时适用（你可以在组织 (Organization) 模板中将 API 级权限 (Permissions) 分配给组织 (Organization) 角色 (Roles)）。

实现方式与上一节相同。始终提供组织 (Organization) ID 并调用 getOrganizationToken(organizationId) 获取组织令牌 (Organization token)；否则不会包含组织 (Organization) 权限 (Permissions)。

关于保护组织级 API 权限 (Permissions) 的详细信息，请参阅完整指南。

使用全局 RBAC​

在这种情况下，你可以使用 Logto Management API 实现系统级访问控制。

在多租户环境下，常见模式是拥有超级用户或超级管理员角色。例如，如果你正在使用 Logto 构建 SaaS 平台，可能希望有一个超级用户可以直接在你的应用内管理所有客户组织 (Organizations)，而无需登录 Logto 控制台。

该超级用户可以执行更高层级的操作，如批量创建或删除组织 (Organizations)，这些操作需要超越任何单一组织 (Organization) 上下文的系统级权限。为此，在 Logto 中注册一个 API 资源，同时利用 Logto Management API，并使用全局 RBAC 管理这些权限 (Permissions)。

有关集成和管理 RBAC 访问控制的更多细节，请参阅完整指南。