虽然 Logto 提供了一个基于网页的控制台来管理身份，但当你想自动化工作流程或以编程方式访问 Logto 时，使用管理 API 是一个强大的替代方案。本指南将引导你在不同场景中使用 Logto 管理 API 的步骤。 ## 概述你可能会注意到在 Logto 控制台中有一个内置的 API 资源 "Logto Management API"。它将在本指南中扮演关键角色。与其他 API 资源相比，目前 Logto 管理 API 不允许终端用户直接访问，因为它被设计用于机器对机器的通信，并且功能强大，可以用于管理你的 Logto 账户和资源。以下是一些你可能想使用 Logto 管理 API 的典型场景： **CI/CD** ```mermaid graph LR CI(持续集成作业) <-->|创建新用户| L(Logto 管理 API) ``` **服务通信** ```mermaid graph LR B(后端服务) <-->|搜索用户| L(Logto 管理 API) ``` **单页应用** ```mermaid graph LR F(前端) -->|1 列出订单| B(后端服务) B <-->|2 查找订单| D(数据库) B <-->|3 搜索与订单相关的用户| L(Logto 管理 API) B -->|4 合并响应| F ``` **渲染 HTML 的 Web 服务器** ```mermaid graph LR W(Web 服务器) <-->|搜索用户| L(Logto 管理 API) ``` ## 架构无论场景如何，访问 Logto 管理 API 有两种模式可以使用。 **模式 1：直接访问** 在此模式中，你的客户端或服务将直接访问 Logto 管理 API。在 Logto 中，客户端或服务称为 "machine-to-machine" 应用。一个使用后端服务的例子： ```mermaid graph LR B(后端服务) <-->|使用客户端凭据| L(Logto 管理 API) ``` **模式 2：间接访问** 在此模式中，你的客户端或服务将通过后端服务访问 Logto 管理 API。模式 2 建立在模式 1 之上，涉及到另一个应用。新应用可以是一个传统的 Web、本机或单页应用，它将访问后端服务。一个使用单页应用的例子： ```mermaid graph LR S(单页应用) -->|请求带有访问令牌| B(后端服务) <-->|使用客户端凭据| L(Logto 管理 API) B -->|带数据的响应| S ``` 当你想要自定义逻辑来控制对 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 应用。目前 Logto 管理 API 只有一个权限 all，允许所有操作。我们正在努力增加更多的细粒度权限。 ### 获取访问令牌你可以按照[这篇文章](https://docs.logto.io/docs/recipes/integrate-logto/machine-to-machine/)中的步骤，通过客户端凭据授权为你的 machine-to-machine 应用获取访问令牌。通过向 Logto 管理 API 中的一个端点发送请求来测试访问令牌。现在你已经准备好使用模式 1。注意访问令牌在有效期内较短，因此如果你想缓存它，可能需要定期刷新。 ## 添加另一层虽然不允许终端用户访问 Logto 管理 API，但你可以添加另一层来利用 Logto 管理 API 的能力并让其支持你的服务。例如，你正在用一个单页应用和一个后端服务构建一个在线社区。你可能希望有一个功能允许签入用户查看拥有最多粉丝的前 10 名用户。一个端点 `GET /api/top-users` 将被创建： ```mermaid graph LR S(单页应用) --> E(GET /api/top-users) subgraph 后端服务 E end ``` 为了确保端点仅能被签入用户访问，你可以在 Logto 控制台中创建一个 "单页应用"，并将 [Logto SDK 集成](https://docs.logto.io/docs/recipes/integrate-logto/)到该应用中。然后你可以使用 SDK 获取访问令牌并将请求发送到端点： ```mermaid graph LR S(单页应用) -->|1 请求带有访问令牌| E(GET /api/top-users) subgraph 后端服务 E end ``` 在后端服务中，你可以首先从数据库中查询前 10 名用户，然后使用 Logto 管理 API 获取用户的信息： ```mermaid graph LR E(GET /api/top-users) <-->|2 查询前 10 名用户| D(数据库) E <-->|3 通过 ID 获取用户信息| L(Logto 管理 API) subgraph 后端服务 E end ``` 最后，你可以将响应返回给单页应用： ```mermaid graph LR E(GET /api/top-users) -->|4 返回合并响应| S(单页应用) subgraph 后端服务 E end ``` 完整的时序图： ```mermaid sequenceDiagram participant S as 单页应用 participant E as GET /api/top-users participant D as 数据库 participant LM as Logto 管理 API participant L as Logto OIDC S ->> L: 用户登录 L ->> S: 完成登录 S ->> L: 请求后端服务的访问令牌 (通过授权代码或刷新令牌) L ->> S: 返回访问令牌 S ->> E: 请求带有访问令牌 E ->> E: 验证访问令牌 E ->> D: 查询前 10 名用户 D ->> E: 返回 ID 的前 10 名用户 E ->> L: 请求 Logto 管理 API 的访问令牌 (通过客户端凭据) L ->> E: 返回访问令牌 E ->> LM: 获取前 10 名用户信息 LM ->> E: 返回用户信息 E ->> E: 将用户信息与前 10 名用户合并 E ->> S: 返回合并响应 ``` 在此流程中，它涉及两种类型的访问令牌：一种是用于后端服务以访问 Logto 管理 API，另一种是用于单页应用访问后端服务。前者的访问令牌是你在前一节中获得的。后者的访问令牌是你可以从 Logto SDK 获取的。 **我在单页应用中的访问令牌不是 JSON Web Token (JWT)** 如果你在调用 Logto SDKs 的 `getAccessToken` 方法时未指定资源，该访问令牌将是一个用于 [userinfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#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 请求的授权令牌](https://docs.logto.io/docs/recipes/protect-your-api/#validate-the-api-requests-authorization-token)。 **单页应用中的 JWT 意味着什么？** JWT 仅意味着用户已登录并尝试访问 API 资源。不意味着用户拥有 API 资源的特定权限。是否授予用户访问 API 资源的权限由你决定。如果你需要更细粒度的访问控制，也可以对用户应用基于角色的访问控制 (RBAC)。详情请参见 [🔐 基于角色的访问控制 (RBAC)](https://docs.logto.io/docs/recipes/rbac/)。 ## 结束语 Logto 管理 API 在多个场景中非常强大且灵活。借助标准协议，你可以轻松地将 Logto 管理 API 集成到你的应用程序中，构建一个安全且可扩展的系统。如果你有任何问题，请随时联系我们。免费试用 Logto Cloud