签名密钥
概述
签名密钥模块用于管理 OIDC 令牌签名所使用的密钥对。Code Bird Cloud 使用 ECDSA（ES256 算法）对 JWT 令牌进行签名，确保令牌的完整性和不可伪造性。
导航路径: 侧边栏 -> 签名密钥
权限要求: 此模块仅对超级管理员可见（
isSuper权限）。
核心概念
OIDC 令牌签名
在 OIDC/OAuth 2.1 协议中，服务端使用私钥对 JWT 令牌（如 ID Token、Access Token）进行签名，客户端通过 JWKS（JSON Web Key Set）端点获取公钥来验证令牌的合法性。
ES256 算法
Code Bird Cloud 使用 ECDSA（Elliptic Curve Digital Signature Algorithm）的 ES256 变体进行令牌签名：
- 算法: ES256（ECDSA using P-256 curve and SHA-256 hash）
- 密钥类型: EC（Elliptic Curve）
- 优势: 相比 RSA，在相同安全级别下密钥更短、签名更快
密钥列表
展示当前系统中所有的签名密钥。
列表字段
| 字段 | 说明 |
|---|---|
| ID | 密钥的唯一标识 |
| 密钥类型 | 密钥的类型（如 EC） |
| 算法 | 签名算法（如 ES256） |
| JWK | JSON Web Key 格式的公钥数据 |
| 创建时间 | 密钥创建时间 |
API 调用:
GET /api/v1/signing-keys轮换密钥
密钥轮换操作会生成一对新的 ECDSA 密钥对，新签发的令牌将使用新密钥进行签名。
操作方式: 在签名密钥页面点击 "轮换密钥" 按钮。
API 调用:
POST /api/v1/signing-keys/rotate轮换流程
- 系统生成新的 ECDSA 密钥对（ES256 算法）
- 新密钥立即生效，后续签发的令牌使用新密钥签名
- 旧密钥暂时保留，确保使用旧密钥签发的令牌在有效期内仍可验证
- 管理员可在确认所有旧令牌过期后，手动删除旧密钥
轮换时机
以下场景建议执行密钥轮换：
- 定期轮换: 建议每 90 天执行一次密钥轮换，作为安全最佳实践
- 密钥泄露: 如果怀疑私钥可能泄露，应立即执行密钥轮换
- 安全合规: 满足安全合规要求中关于密钥管理的规定
删除旧密钥
当旧密钥签发的所有令牌都已过期后，可以删除旧密钥以保持密钥列表整洁。
注意: 删除仍有令牌在使用的密钥会导致这些令牌验证失败。删除前请确保：
- 所有使用该密钥签发的 Access Token 已过期
- 所有使用该密钥签发的 ID Token 已过期
- 所有使用该密钥签发的 Refresh Token 已过期或已被刷新
JWKS 端点
客户端和资源服务器通过 JWKS 端点获取公钥信息来验证令牌签名。JWKS 端点通常位于：
GET /.well-known/jwks.json该端点返回当前所有有效签名密钥的公钥部分，客户端根据令牌头部的 kid（Key ID）字段匹配对应的公钥进行验证。
安全建议
- 定期轮换: 即使没有安全事件，也建议定期（如每季度）轮换签名密钥
- 及时清理: 旧密钥对应的令牌全部过期后，及时删除旧密钥
- 访问控制: 仅授权超级管理员管理签名密钥，避免密钥管理权限泄露
- 监控日志: 关注签名密钥相关的操作日志，确保所有密钥操作可追溯
- 应急准备: 制定密钥泄露应急响应预案，确保可以在最短时间内完成密钥轮换