跳到主要内容

保护你的 API

如果你不需要灵活、细粒度的访问控制策略,你可以直接保护你的 API。我们将通过一个序列图和必要的步骤来指导你如何将访问控制集成到你的应用中。

在本教程中

  • Logto 端点:https://tenant-id.logto.app
  • 客户端应用程序:https://client.example.org
  • API 资源服务器:https://resource-server.com/api

在实现时,你应该用你的实际端点替换这些。

认证请求 (Authentication Request)

认证请求 (Authentication Request) 中提供资源指示器参数列表。它将指示用户可能请求的所有受保护资源。

GET https://tenant-id.logto.app/oidc/auth?response_type=code
&client_id=s6BhdRkqt3
&state=tNwzQ87pC6llebpmac_IDeeq-mCR2wLDYljHUZUAWuI
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&resource=https%3A%2F%2Fresource-server.com%2Fapi
&scope=read%20write

Logto 将验证并存储这些资源指示器。一个 authorization_code 将被授予并返回,权限将限制在这些指定的资源上。

Logto SDK 的示例配置:

const config: LogtoConfig = {
// ...其他配置
resources: ['https://resource-server.com/api'],
scopes: ['read', 'write'],
};

令牌请求 (Token Request)

当资源参数与上面授予的 authorization_code 一起出现在 令牌请求 (Token Request) 中时,它将指定请求的访问令牌的目标 API 资源受众。

POST https://tenant-id.logto.app/oidc/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&code=10esc29BWC2qZB0acc9v8zAv9ltc2pko105tQauZ&resource=https%3A%2F%2Fresource-server.com%2Fapi

Logto 将授予一个受限于此请求资源的受众的加密访问令牌。令牌携带所有你需要的数据来表示请求的授权状态。例如,请求用户的身份和角色,令牌的受众和过期时间。

Logto SDK 的示例代码:

const accessToken = await logtoClient.getAccessToken('https://resource-server.com/api');

accessToken 的负载将包含:

{
iss: '<your-logto-endpoint>/oidc',
aud: 'https://resource-server.com/api',
scope: 'read write'
}

对 API 资源的请求

客户端用户通过在授权头中提供给定的 access_token 向 API 资源发送请求。

GET https://resource-server.com/api/users
Authorization: Bearer eyJhbGciOiJIUz...

Logto 遵循标准的基于令牌的授权协议来保护你的 API 资源。要了解更多关于 OAuth 2.0 的信息,请参考 OAuth 2.0 的官方文档

验证 API 请求的授权令牌

Logto 为每个授权的 API 请求发布一个标准的 JWT 格式的授权令牌。令牌被加密并签名为 JWS 令牌。

理解 JWS 令牌

一个编码的 JWS 令牌由三部分构成:

  • JOSE Header:声明代码类型和编码算法
  • JWS Payload:包含令牌的所有声明
  • JWS Signature:使用 JWK 签名的签名

Logto 发布的 JWS Payload 的标准模式:(声明可能会有所不同,基于你的自定义 OIDC 配置)

keydescription
jti唯一的 JWT ID
sub主体,通常是用户 ID
iat令牌签发的时间戳
exp令牌过期的时间戳
client_id应用程序 ID
iss令牌发行者身份
aud令牌的受众
scope令牌的权限 (Permissions)
备注

在开发过程中,为了直观地检查 JWT 令牌,你可以访问 JWT 解码工具 来解码和检查你收到的令牌。请小心或永远不要使用来自生产环境的令牌。由于这是第三方提供的公共在线服务,你的令牌可能会被暴露。

验证授权令牌

  1. 验证 JWT
  2. 验证 JWS 签名
  3. 令牌的发行者是 https://<your-logto-domain>/oidc(由你的 Logto 认证服务器发行)
  4. 令牌的受众等于 Logto 管理控制台中注册的当前接收者的资源指示器
  5. 令牌在其过期时间内
  6. (仅限 RBAC)令牌具有所需的 scope

有各种开源库和包可以帮助你轻松验证和解码 JWT 令牌。你可以根据你使用的语言和框架选择一个并集成到你的后端应用程序中。请查看我们的一些示例:

参考

Logto 使用基于代码的 OAuth 2.0 授权协议来确保你的 API 请求安全。如果你对其背后的策略感兴趣,请参考 OAuth 2.0 的规范以获取更多详细信息。