签名密钥
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 密钥。
-
导航到 控制台 > 签名密钥。在这里,你可以管理 OIDC 私钥和 OIDC cookie 密钥。
-
要旋转签名密钥,点击 "旋转私钥" 或 "旋转 cookie 密钥" 按钮。在旋转私钥时,你可以选择更改签名算法。
-
你会看到一个列出所有正在使用的签名密钥的表格。注意:你可以删除以前的密钥,但不能删除当前的密钥。
状态 描述 当前 表示此密钥当前在你的应用程序和 API 中处于活动使用状态。 以前 指的是一个以前使用过但已被旋转出的密钥。使用此签名密钥的现有令牌仍然有效。
请记住,旋转涉及以下三个操作:
- 创建新的签名密钥:这将要求你的所有 应用程序 和 API 采用新的签名密钥。
- 旋转当前密钥:现有密钥将在旋转后被指定为 "以前",并且不会被新创建的应用程序和 API 使用。然而,用此密钥签名的令牌仍然有效。
- 移除以前的密钥:标记为 "以前" 的密钥将被撤销并从表中移除。
注意:
切勿连续旋转签名密钥(两次或更多次),因为这可能会使所有已发行的令牌失效。
- 对于 OSS 用户,旋转签名密钥后,需要重启 Logto 实例以使新签名密钥生效。
- 对于云端用户,新签名密钥在旋转后立即生效,但请确保不要连续多次旋转签名密钥。
相关资源
JWT 中的 EC 和 RSA 签名算法介绍