使用 Logto 管理 API：分步指南

虽然 Logto 提供了一个基于网页的控制台来管理身份，但当你想自动化工作流程或以编程方式访问 Logto 时，使用管理 API 是一个强大的替代方案。本指南将引导你在不同场景中使用 Logto 管理 API 的步骤。

概述#

你可能会注意到在 Logto 控制台中有一个内置的 API 资源 "Logto Management API"。它将在本指南中扮演关键角色。

与其他 API 资源相比，目前 Logto 管理 API 不允许终端用户直接访问，因为它被设计用于机器对机器的通信，并且功能强大，可以用于管理你的 Logto 账户和资源。

以下是一些你可能想使用 Logto 管理 API 的典型场景：

CI/CD

服务通信

单页应用

渲染 HTML 的 Web 服务器

架构#

无论场景如何，访问 Logto 管理 API 有两种模式可以使用。

模式 1：直接访问

在此模式中，你的客户端或服务将直接访问 Logto 管理 API。在 Logto 中，客户端或服务称为 "machine-to-machine" 应用。

一个使用后端服务的例子：

模式 2：间接访问

在此模式中，你的客户端或服务将通过后端服务访问 Logto 管理 API。模式 2 建立在模式 1 之上，涉及到另一个应用。新应用可以是一个传统的 Web、本机或单页应用，它将访问后端服务。

一个使用单页应用的例子：

当你想要自定义逻辑来控制对 Logto 管理 API 的访问时，此模式很有用。例如，你可能想为消费者返回所有订单，并在每个订单中附加卖家信息。在这种情况下，你可以使用单页应用请求后端服务获取订单，并在后端服务中使用 Logto 管理 API 获取卖家信息。

访问 Logto 管理 API#

创建一个 machine-to-machine 应用#

首先，你需要在 Logto 控制台中创建一个 machine-to-machine 应用。前往 "应用程序" 标签并点击 "创建应用程序" 按钮。然后在 "Machine-to-machine" 卡片中点击 "开始构建"。

设置 machine-to-machine 角色#

为了访问 Logto 管理 API，你需要创建一个具有适当权限的 machine-to-machine 角色。在 Logto 控制台中，前往 "角色" 标签并点击 "创建角色" 按钮。点击 "显示更多选项" 并在 "角色类型" 部分选择 "Machine-to-machine app role"。

现在你可以看到 "Logto 管理 API" 出现在 "分配权限" 部分。勾选 API 资源的所有权限，然后点击 "创建角色" 按钮。

角色创建后，你可以将其分配给你在上一步中创建的 machine-to-machine 应用。

获取访问令牌#

你可以按照这篇文章中的步骤，通过客户端凭据授权为你的 machine-to-machine 应用获取访问令牌。通过向 Logto 管理 API 中的一个端点发送请求来测试访问令牌。

现在你已经准备好使用模式 1。注意访问令牌在有效期内较短，因此如果你想缓存它，可能需要定期刷新。

添加另一层#

虽然不允许终端用户访问 Logto 管理 API，但你可以添加另一层来利用 Logto 管理 API 的能力并让其支持你的服务。

例如，你正在用一个单页应用和一个后端服务构建一个在线社区。你可能希望有一个功能允许签入用户查看拥有最多粉丝的前 10 名用户。一个端点 GET /api/top-users 将被创建：

为了确保端点仅能被签入用户访问，你可以在 Logto 控制台中创建一个 "单页应用"，并将 Logto SDK 集成到该应用中。然后你可以使用 SDK 获取访问令牌并将请求发送到端点：

在后端服务中，你可以首先从数据库中查询前 10 名用户，然后使用 Logto 管理 API 获取用户的信息：

最后，你可以将响应返回给单页应用：

完整的时序图：

在此流程中，它涉及两种类型的访问令牌：一种是用于后端服务以访问 Logto 管理 API，另一种是用于单页应用访问后端服务。

前者的访问令牌是你在前一节中获得的。后者的访问令牌是你可以从 Logto SDK 获取的。

我在单页应用中的访问令牌不是 JSON Web Token (JWT)

如果你在调用 Logto SDKs 的 getAccessToken 方法时未指定资源，该访问令牌将是一个用于 userinfo 端点的不透明字符串。要获取 JWT：

1. 在 Logto 控制台中定义一个 API 资源，例如 https://api.example.com。
2. 将 API 资源添加到 Logto SDK 的 resources 配置中，例如 resources: ['https://api.example.com']。
3. 使用 API 资源调用 getAccessToken 方法，例如 getAccessToken('https://api.example.com')。

要在你的后端服务中验证 JWT，请参考 验证 API 请求的授权令牌。

单页应用中的 JWT 意味着什么？

JWT 仅意味着用户已登录并尝试访问 API 资源。不意味着用户拥有 API 资源的特定权限。是否授予用户访问 API 资源的权限由你决定。

如果你需要更细粒度的访问控制，也可以对用户应用基于角色的访问控制 (RBAC)。详情请参见 🔐 基于角色的访问控制 (RBAC)。

结束语#

Logto 管理 API 在多个场景中非常强大且灵活。借助标准协议，你可以轻松地将 Logto 管理 API 集成到你的应用程序中，构建一个安全且可扩展的系统。如果你有任何问题，请随时联系我们。