跳到主要内容

签名密钥

Logto OIDC 签名密钥，也被称为 “OIDC 私钥” 和 “OIDC Cookie 密钥”，是用于在 Logto 登录会话 中对 JWT（访问令牌 (Access token) 和 ID 令牌 (ID token)）以及浏览器 Cookie 进行签名的密钥。这些签名密钥会在初始化 Logto 数据库（开源版）或创建新租户（云端）时生成，并可通过 CLI（开源版）、Management API 或控制台界面进行管理。

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

备注:

理论上，签名密钥不应泄露且没有过期时间，因此无需轮换。但定期在一段时间后轮换签名密钥可以提升安全性。

工作原理​

  • OIDC 私钥 在初始化 Logto 实例时，会自动生成一对公钥和私钥，并注册到底层 OIDC 提供方。因此，当 Logto 颁发新的 JWT（访问令牌 (Access token) 或 ID 令牌 (ID token)）时，令牌会用私钥进行签名。同时，任何收到 JWT 的客户端应用都可以使用配对的公钥验证令牌签名，以确保令牌未被第三方篡改。私钥在 Logto 服务器上受到保护。而公钥，顾名思义，是公开的，任何人都可以通过 OIDC 端点的 /oidc/jwks 接口访问。在生成私钥时可以指定签名密钥算法，Logto 默认使用 EC（椭圆曲线）算法。管理员用户可以通过轮换私钥将默认算法更改为 RSA（Rivest-Shamir-Adleman）。
  • OIDC Cookie 密钥 当用户发起登录或注册流程时，服务器上会创建一个 “OIDC 会话”，以及一组浏览器 Cookie。借助这些 Cookie，浏览器可以代表用户请求 Logto Experience API 执行一系列交互操作，如登录、注册和重置密码。但与 JWT 不同，Cookie 只由 Logto OIDC 服务自身签名和验证，不需要非对称加密措施。因此，Cookie 签名密钥没有配对的公钥，也不使用非对称加密算法。

通过控制台界面轮换签名密钥​

Logto 引入了 “签名密钥轮换” 功能，允许你在租户中创建新的 OIDC 私钥和 Cookie 密钥。

  1. 前往 控制台 > 租户设置 > OIDC 配置。在这里，你可以管理 OIDC 私钥和 OIDC Cookie 密钥。

  2. 要轮换签名密钥，点击 “轮换私钥” 或 “轮换 Cookie 密钥” 按钮。轮换私钥时，你可以选择更改签名算法。

  3. 你会看到一个表格，列出了所有正在使用的签名密钥。对于 OIDC 私钥，你可以删除上一个密钥，但不能删除当前或下一个密钥。对于 OIDC Cookie 密钥，你可以删除上一个密钥，但不能删除当前密钥。

    状态说明
    下一个用于分阶段 OIDC 私钥轮换的状态。密钥已创建，但 Logto 不会用它签发新的 JWT，直到宽限期结束且密钥生效。
    当前表示 Logto 当前用于签发新 JWT 或 Cookie 的密钥。
    上一个指之前使用过但已被轮换的密钥。用该密钥签名的现有 JWT 或 Cookie 在过期或密钥被删除前仍然有效。

请记住，轮换涉及以下三个操作：

  1. 创建新签名密钥：对于 OIDC 私钥，Logto 可以先将新密钥分阶段为 “下一个”，这样你的应用和 API 就有时间从 /oidc/jwks 端点刷新公钥，然后再用新密钥进行签名。
  2. 轮换当前密钥：当轮换生效时，“下一个”密钥变为 “当前”，原有 “当前” 密钥变为 “上一个”。用上一个密钥签名的令牌仍然有效。
  3. 移除最旧的上一个密钥：Logto 最多只保留一个 “上一个” 私钥。如果在分阶段密钥变为当前时已存在上一个私钥，则会移除更早的上一个密钥。

对于 Logto Cloud，OIDC 私钥轮换在 4 小时宽限期后生效。在此期间，新密钥已准备好并通过 JWKS 暴露，Logto 会在宽限期结束后才用它签发新的 JWT。在控制台表格中，生效时间 列显示分阶段 “下一个” 密钥变为 “当前” 的时间。

对于自托管开源部署，默认私钥轮换宽限期为 0 秒，即轮换立即生效。要使用分阶段轮换，请在 Logto 服务上设置 PRIVATE_KEY_ROTATION_GRACE_PERIOD 环境变量，或在调用 Management API 端点 POST /api/configs/oidc/private-keys/rotate 时在请求体中传递显式的 rotationGracePeriod 值。

注意:

在待轮换生效前，避免反复轮换签名密钥，除非你有意替换分阶段的 “下一个” 密钥。

过早删除唯一的 “上一个” 密钥，可能会导致用该密钥签名的现有 JWT 或 Cookie 失效。

JWT 中 EC 与 RSA 签名算法简介