跳到主要内容

轮换签名密钥（OSS）

备注:

如果你正在使用 Logto Cloud，可以在控制台 UI 中轮换签名密钥，请参考本教程。

Logto OSS 从 v1.8 开始支持轮换签名密钥。

Logto OIDC 签名密钥，也称为“OIDC 私钥”和“OIDC Cookie 密钥”，是用于在 Logto 登录会话中签署 JWT（访问令牌 (Access tokens) 和 ID 令牌 (ID tokens)）以及浏览器 Cookie 的签名密钥。

定期轮换你的签名密钥可以降低密钥泄露的风险。Logto 建议你至少每年轮换一次签名密钥。

轮换 OIDC 私有签名密钥​

使用以下 CLI 命令生成新的 OIDC 私有签名密钥。默认情况下，新密钥会立即生效。若要分阶段轮换并给予客户端时间刷新 JWKS（在新密钥签署 JWT 之前），请配置宽限期。

可用选项：

--type          （可选）你的 JWT 的签名密钥算法。
                可选值为 "rsa" 或 "ec"。默认为 "ec"。
--gracePeriod   （可选）分阶段私钥轮换的宽限期（秒）。
                默认为 PRIVATE_KEY_ROTATION_GRACE_PERIOD 环境变量的值，未设置时为 0。
logto db config rotate oidc.privateKeys --type rsa

例如，要让新的私钥在 4 小时后生效，可以这样分阶段轮换：

logto db config rotate oidc.privateKeys --type rsa --gracePeriod 14400

你还可以通过环境变量设置私钥轮换的默认宽限期：

PRIVATE_KEY_ROTATION_GRACE_PERIOD=14400

当通过 Admin Console 或 Management API 轮换时，在 Logto 服务上设置此环境变量；通过 CLI 命令轮换时，在运行 CLI 命令的 shell 中设置。

使用以下 CLI 命令生成新的 OIDC Cookie 密钥。Cookie 密钥轮换不支持宽限期。

logto db config rotate oidc.cookieKeys

之前的密钥怎么办？​

对于 OIDC 私钥，Logto 在分阶段轮换期间最多保留三把密钥：

  • Next：等待宽限期结束的新密钥。
  • Current：当前用于签署新 JWT 的密钥。
  • Previous：最近被替换下来的密钥，保留以保证现有 JWT 仍然有效。

宽限期结束后，Next 密钥变为 Current，旧的 Current 变为 Previous，最早的 Previous 密钥被移除。

对于 Cookie 密钥，Logto 会保留当前和上一个密钥。删除上一个密钥时请谨慎，因为这可能导致意外问题。建议在确认所有使用该密钥签署的现有会话或令牌都已过期后再删除。

故障排查​

在 Cloudflare Zero Trust 中将 Logto 作为 OIDC 提供方使用​

如果你打算在 Cloudflare Zero Trust 中将 Logto 作为 OIDC 提供方，请注意其不支持使用 ECDSA 算法的 OIDC 提供方。在轮换 OIDC 私有签名密钥时，请确保通过在轮换命令中指定 --type rsa 使用 RSA 算法：

logto db config rotate oidc.privateKeys --type rsa