签名密钥 API

签名密钥接口用于管理 JWT 令牌的签名密钥。OIDC 令牌使用 ES256（ECDSA）算法进行签名，密钥可以进行轮换以提升安全性。

所有接口均需要管理员令牌认证：Authorization: Bearer <admin_token>

---

获取签名密钥列表

GET /api/v1/signing-keys

获取所有签名密钥。列表中包含当前活跃密钥和历史密钥。

请求示例：

curl -X GET https://your-domain/api/v1/signing-keys \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": "sk_001",
      "status": "active",
      "algorithm": "ES256",
      "created_at": "2025-06-01T00:00:00Z"
    },
    {
      "id": "sk_000",
      "status": "previous",
      "algorithm": "ES256",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

响应字段说明：

字段	类型	说明
id	string	签名密钥 ID
status	string	密钥状态：active（当前活跃）、previous（已轮换的旧密钥）
algorithm	string	签名算法（当前固定为 ES256）
created_at	string	创建时间（ISO 8601）

说明： 状态为 previous 的密钥仍用于验证旧令牌，直到这些令牌过期。

---

轮换签名密钥

POST /api/v1/signing-keys/rotate

生成一个新的签名密钥并将其设为活跃密钥。当前活跃密钥会变为 previous 状态。

请求示例：

curl -X POST https://your-domain/api/v1/signing-keys/rotate \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "sk_002",
    "status": "active",
    "algorithm": "ES256",
    "created_at": "2025-06-15T08:00:00Z"
  }
}

注意事项：

• 轮换后，新签发的令牌将使用新密钥签名。
• 旧密钥（previous 状态）仍然保留用于验证之前签发的令牌。
• 建议在低峰期进行密钥轮换操作。
• JWKS 端点（/.well-known/jwks.json）会自动包含所有状态的公钥。

---

删除签名密钥

DELETE /api/v1/signing-keys/:id

删除指定的签名密钥。

警告： 删除密钥后，使用该密钥签名的令牌将无法通过验证。请确保只删除已无活跃令牌引用的旧密钥。

路径参数：

参数	类型	说明
id	string	签名密钥 ID

请求示例：

curl -X DELETE https://your-domain/api/v1/signing-keys/sk_000 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": null
}

错误响应（尝试删除活跃密钥）：

{
  "code": 400,
  "message": "无法删除当前活跃的签名密钥",
  "result": ""
}

---

最佳实践

1. 定期轮换密钥： 建议每 90 天轮换一次签名密钥，以降低密钥泄露风险。
2. 保留旧密钥： 轮换后至少保留旧密钥一个令牌有效期周期，确保已签发的令牌不会因密钥删除而失效。
3. 监控 JWKS： 依赖方应通过 /.well-known/jwks.json 端点动态获取公钥，而非硬编码。
4. 审计日志： 密钥轮换和删除操作会记录在审计日志中，建议定期检查。