跳到主要内容

签名密钥

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

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

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

    状态说明
    当前表示该密钥当前在你的应用和 API 中处于激活状态。
    之前指之前使用过但已被轮换的密钥。使用该签名密钥签发的现有令牌仍然有效。

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

  1. 创建新签名密钥：这将要求你所有的应用程序和API采用新的签名密钥。
  2. 轮换当前密钥：轮换后，现有密钥将被标记为 “之前”，不会被新创建的应用和 API 使用。但用该密钥签名的令牌仍然有效。
  3. 移除之前的密钥：标记为 “之前” 的密钥将被吊销并从表格中移除。
注意:

切勿连续（两次或以上）轮换签名密钥，否则可能导致所有已签发的令牌失效。

  • 对于 OSS 用户，轮换签名密钥后需要重启 Logto 实例，新签名密钥才会生效。
  • 对于云端用户，新签名密钥在轮换后立即生效，但请务必不要连续多次轮换签名密钥。

JWT 中 EC 与 RSA 签名算法简介