如何用 Logto CLI 带宽限期轮换 OIDC 私钥并清理旧密钥【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto如果你在运营一个 Logto 实例需要更换用于签发 OIDC 令牌的私钥但又不想让密钥切换瞬间影响所有节点对旧令牌的验证就可以用 Logto CLI 的config rotate命令做一次「分阶段staged轮换」新密钥先进入等待状态经过你指定的宽限期grace period后再自动接管。宽限期结束后旧密钥会降级为Previous此时再用config trim把它从数据库里清理掉。整个过程只操作 Logto 的 PostgreSQL 数据库中的配置行命令入口在 config.ts密钥状态流转逻辑在 oidc-private-key.ts。准备条件CLI 版本logto/cli1.43.0package.json 中声明的 Node 要求为^22.14.0。可访问的 Logto 数据库rotate/trim直接读写数据库中的logto_configs配置行因此 CLI 必须能连到目标实例的 PostgreSQL。数据库 URL 有三种提供方式见 database.ts 和 index.ts命令行参数--db url别名--db-url、--database-url环境变量DB_URL可通过--env指定.env文件载入都不提供时交互式终端下 CLI 会提示输入默认值postgresql://localhost:5432/logto非交互环境下读不到 URL 会直接报错。多租户rotate、trim、get都支持--tenantId不传时操作默认租户default定义在 tenant.ts。轮换只作用于 OIDC 配置中的两个键oidc.privateKeysOIDC 私钥和oidc.cookieKeysCookie 密钥。本文场景是OIDC 私钥即oidc.privateKeys。带宽限期执行轮换基本命令logto db config rotate oidc.privateKeys --gracePeriod 3600 --type EC --db postgres://用户:密码主机:5432/logto参数说明均来自 config.ts 中的 builder 定义--gracePeriod宽限期单位秒是oidc.privateKeys分阶段轮换的时长。--type新私钥的签名算法可选RSA、EC默认EC。只对oidc.privateKeys生效轮换oidc.cookieKeys时该值固定按EC处理。--tenantId要操作的租户默认default。宽限期的取值优先级见 config-rotation.ts 的getEffectiveRotationGracePeriod命令行传了--gracePeriod必须是 ≥0 的整数则以它为准没传则回退到环境变量PRIVATE_KEY_ROTATION_GRACE_PERIOD必须是 ≥0 的整数两者都没有则为0即立即轮换。所以如果希望实例默认就走分阶段轮换也可以不在每条命令上带--gracePeriod而是给 Logto 服务容器设置PRIVATE_KEY_ROTATION_GRACE_PERIOD。根目录的 docker-compose.yml 里就透传了这个变量注释写得很直白Optional default grace period, in seconds, for OIDC private key rotation when the API request omitsrotationGracePeriod.注意一个容易踩的坑oidc.cookieKeys不支持宽限期。对 cookie 密钥传--gracePeriod会直接抛错oidc.cookieKeys does not support grace period。宽限期如何改变密钥状态轮换时 CLI 会在新事务里同时更新两个配置行oidc.privateKeys和租户配置signingKeyRotationState状态结构为{ tenantCacheExpiresAt, signingKeyRotationAt }定义在 index.ts。密钥数组里每个元素带有status字段取值Next/Current/Previous宽限期 0分阶段轮换新数组为见getStagedRotatedOidcPrivateKeys新密钥 →Next等待激活现有Current→ 保持Current已有的Previous保留。同时写入的轮换状态里signingKeyRotationAt now gracePeriod * 1000即新密钥的激活时间tenantCacheExpiresAt now表示当前租户实例的缓存应视为失效、下次重新加载时会读到新的签名密钥数据。宽限期 0立即轮换见getImmediatelyRotatedOidcPrivateKeys新密钥 → 直接成为Current原Current→ 降为Previous更旧的Previous被丢弃数组里至多保留 2 个密钥若此时已存在一个Next密钥即上一轮分阶段轮换还没完成立即轮换会被拒绝Immediate OIDC private key rotation is not allowed when a Next key exists。立即轮换时只写tenantCacheExpiresAt不写signingKeyRotationAt。查看轮换结果用同族的get命令核对数据库里落盘的状态get key [keys...]会按 JSON 打印配置值logto db config get oidc.privateKeys signingKeyRotationState --db postgres://用户:密码主机:5432/logto分阶段轮换刚执行完时oidc.privateKeys里应能看到刚生成的密钥处于Next原密钥仍是CurrentsigningKeyRotationState的signingKeyRotationAt对应now gracePeriod * 1000的时间戳。rotate命令本身的执行反馈也直接给出密钥总数config.tsRotate oidc.privateKeys succeeded, now it has 2 keys宽限期结束后清理旧密钥等signingKeyRotationAt到达、新密钥被提升为Current、旧密钥降为Previous之后可以用trim从密钥数组尾部删除Previous密钥logto db config trim oidc.privateKeys 1 --db postgres://用户:密码主机:5432/logtolength是要删除的密钥数量默认1。trim对oidc.privateKeys的限制见getTrimmedOidcPrivateKeys与 config.ts只有Previous状态的密钥可以被裁剪length超过现有Previous数量会报Only Previous OIDC private keys can be trimmed——也就是说如果上一轮宽限期还没走完、旧密钥还不是Previoustrim 会失败这不是命令写错而是时机未到裁剪后数组不能为空You should keep at least one key in the array, current lengthN。trim执行成功后同样打印剩余密钥数Trim oidc.privateKeys succeeded, now it has 1 keystrim也会顺带更新signingKeyRotationState只写tenantCacheExpiresAt now让各节点在下次重新加载配置时丢弃旧的签名密钥缓存。限制与注意事项轮换与裁剪都要求密钥数组里恰好一个Current、至多一个Next和Previous否则规范化时会报Malformed OIDC private key status configuration旧数据里没有status字段时按数组下标解释第 1 个是Current第 2 个是Previous。--type只接受RSA/EC传其他值会报Invalid private key type ... found, expected one of RSA, EC。--gracePeriod必须是 ≥0 的整数环境变量PRIVATE_KEY_ROTATION_GRACE_PERIOD非法非整数或负数时会报Invalid PRIVATE_KEY_ROTATION_GRACE_PERIOD env value。根目录的 docker-compose.yml 开头注明该 compose 文件仅用于演示for demonstration only生产环境的部署方式需另行确认本文命令只要求能连到目标实例的数据库即可。【免费下载链接】logto Authentication and authorization infrastructure for SaaS and AI apps, built on OIDC and OAuth 2.1 with multi-tenancy, SSO, and RBAC.项目地址: https://gitcode.com/GitHub_Trending/lo/logto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考