跳到主要内容

签名密钥

Logto OIDC 签名密钥，也称为 "OIDC 私钥" 和 "OIDC cookie 密钥"，是用于在 Logto 登录会话中签署 JWT 令牌（访问令牌 和 ID 令牌）和浏览器 cookie 的签名密钥。这些签名密钥是在初始化 Logto 数据库时生成的（开源）或创建新租户时生成的（云端），可以通过 CLI（开源）、Management API 或控制台 UI 进行管理。

默认情况下，Logto 使用椭圆曲线 (EC) 算法生成数字签名。然而，考虑到用户经常需要验证 JWT 签名，而许多旧工具不支持 EC 算法（仅支持 RSA），我们实现了旋转私钥的功能，并允许用户选择签名算法（包括 RSA 和 EC）。这确保了与使用过时签名验证工具的服务的兼容性。

备注:

理论上，签名密钥不应泄露且没有过期时间，这意味着不需要旋转它们。然而，定期在一定时间后旋转签名密钥可以增强安全性。

它是如何工作的？​

  • OIDC 私钥 在初始化 Logto 实例时，会自动生成一对公钥和私钥，并在底层 OIDC 提供商中注册。因此，当 Logto 发布新的 JWT 令牌（访问令牌或 ID 令牌）时，令牌会用私钥签名。同时，任何接收到 JWT 令牌的客户端应用程序都可以使用配对的公钥验证令牌签名，以确保令牌未被任何第三方篡改。私钥在 Logto 服务器上受到保护。然而，正如其名称所示，公钥是公开的，可以通过 OIDC 端点的 /oidc/jwks 接口访问。生成私钥时可以指定签名密钥算法，Logto 默认使用 EC（椭圆曲线）算法。管理员用户可以通过旋转私钥将默认算法更改为 RSA（Rivest-Shamir-Adleman）。
  • OIDC cookie 密钥 当用户启动登录或注册流程时，服务器上会创建一个 "OIDC 会话"，以及一组浏览器 cookie。通过这些 cookie，浏览器可以请求 Logto Experience API 代表用户执行一系列交互，例如登录、注册和重置密码。然而，与 JWT 令牌不同，cookie 仅由 Logto OIDC 服务本身签名和验证，不需要非对称加密措施。因此，我们没有用于 cookie 签名密钥的配对公钥，也没有非对称加密算法。

从控制台 UI 旋转签名密钥​

Logto 引入了 "签名密钥旋转" 功能，允许你在租户中创建新的 OIDC 私钥和 cookie 密钥。

  1. 导航到 控制台 > 签名密钥。在这里，你可以管理 OIDC 私钥和 OIDC cookie 密钥。

  2. 要旋转签名密钥，点击 "旋转私钥" 或 "旋转 cookie 密钥" 按钮。在旋转私钥时，你可以选择更改签名算法。

  3. 你会看到一个列出所有正在使用的签名密钥的表格。注意：你可以删除以前的密钥，但不能删除当前的密钥。

    状态描述
    当前表示此密钥当前在你的应用程序和 API 中处于活动使用状态。
    以前指的是一个以前使用过但已被旋转出的密钥。使用此签名密钥的现有令牌仍然有效。

请记住，旋转涉及以下三个操作：

  1. 创建新的签名密钥：这将要求你的所有 应用程序 和 API 采用新的签名密钥。
  2. 旋转当前密钥：现有密钥将在旋转后被指定为 "以前"，并且不会被新创建的应用程序和 API 使用。然而，用此密钥签名的令牌仍然有效。
  3. 移除以前的密钥：标记为 "以前" 的密钥将被撤销并从表中移除。
注意:

切勿连续旋转签名密钥（两次或更多次），因为这可能会使所有已发行的令牌失效。

  • 对于 OSS 用户，旋转签名密钥后，需要重启 Logto 实例以使新签名密钥生效。
  • 对于云端用户，新签名密钥在旋转后立即生效，但请确保不要连续多次旋转签名密钥。

JWT 中的 EC 和 RSA 签名算法介绍