跳到主要内容

自定义访问令牌 (Access token)

Logto 提供了在访问令牌 (访问令牌 / 不透明令牌) 中添加自定义声明 (Claims) 的灵活性。通过此功能，你可以在令牌中安全地传递业务逻辑所需的额外信息，并且在使用不透明令牌时可通过内省接口获取这些信息。

简介​

访问令牌 (Access tokens) 在认证 (Authentication) 与授权 (Authorization) 流程中扮演着关键角色，携带主体的身份信息和权限，并在 Logto 服务器（作为认证服务器或身份提供商 (IdP)）、你的 Web 服务服务器（资源提供方）和客户端应用程序（客户端）之间传递。

令牌声明 (Claims) 是提供关于实体或令牌本身信息的键值对。声明 (Claims) 可能包含用户信息、令牌过期时间、权限以及与认证 (Authentication) 和授权 (Authorization) 流程相关的其他元数据。

在 Logto 中有两种类型的访问令牌 (Access tokens)：

  • JSON Web Token： JSON Web Token (JWT) 是一种流行的格式，以安全且可被客户端读取的方式编码声明 (Claims)。常见声明 (Claims) 如 sub、iss、aud 等，符合 OAuth 2.0 协议（详见 此链接）。JWT 允许消费者直接访问声明 (Claims) 而无需额外验证步骤。在 Logto 中，当客户端初始化特定资源或组织的授权 (Authorization) 请求时，默认以 JWT 格式颁发访问令牌 (Access token)。
  • 不透明令牌 (Opaque token)： 不透明令牌 (Opaque token) 不是自包含的，始终需要通过 令牌内省 端点进行额外的验证步骤。尽管其格式不透明，不透明令牌 (Opaque token) 仍可用于获取声明 (Claims) 并在各方之间安全传递。令牌声明 (Claims) 被安全地存储在 Logto 服务器中，客户端应用程序可通过令牌内省端点访问。访问令牌 (Access token) 在授权 (Authorization) 请求中未包含特定资源或组织时以不透明格式颁发。这些令牌主要用于访问 OIDC 的 userinfo 端点及其他通用用途。

在许多情况下，标准声明 (Claims) 并不能满足你的应用的特定需求，无论你使用的是 JWT 还是不透明令牌 (Opaque token)。为此，Logto 提供了在访问令牌 (Access token) 中添加自定义声明 (Claims) 的灵活性。通过此功能，你可以在令牌中安全地传递业务逻辑所需的额外信息，并且在使用不透明令牌 (Opaque token) 时可通过内省接口获取这些信息。

自定义令牌声明 (Claims) 如何工作？​

Logto 允许你通过回调函数 getCustomJwtClaims 向 访问令牌 (Access token) 插入自定义声明 (Claims)。你可以实现自己的 getCustomJwtClaims 函数，返回一个包含自定义声明 (Claims) 的对象。返回值将与原始令牌负载合并，并签名生成最终的访问令牌 (Access token)。

信息:

Logto 内置的令牌声明 (Claims) 不能被覆盖或修改。自定义声明 (Claims) 会作为附加声明 (Claims) 添加到令牌中。如果自定义声明 (Claims) 与内置声明 (Claims) 冲突，则这些自定义声明 (Claims) 会被忽略。

注意:

安全提示：在自托管部署中，自定义 JWT 脚本以与 Logto 服务器进程相同的权限执行，因此授予脚本编辑或测试权限等同于授予 Logto 主机上的代码执行权限。此功能仅面向受信任的管理员：不要允许不受信任或低权限用户创建、修改或测试这些脚本，也不要与他们共享管理控制台。

使用 Logto 为 JWT 访问令牌 (Access token) 添加自定义声明 (Claims)，提升你的授权 (Authorization)