docker/jwkstuf

OIDC Provider Public Key Ledger Manager (TUF)

镜像概述和主要用途

本Docker镜像用于在TUF（The Update Framework，软件更新框架）中管理OIDC（OpenID Connect，开放ID连接）提供商的公钥账本。TUF是一种保障软件更新安全的框架，而OIDC是基于OAuth 2.0的身份验证协议。该镜像通过集成TUF规范，提供OIDC提供商公钥的全生命周期管理，确保公钥信息的安全存储、分发和更新，解决分布式系统中OIDC公钥同步不一致及安全风险问题。

核心功能和特性

• 公钥账本管理：支持OIDC提供商公钥的添加、更新、删除及查询操作，维护完整的公钥变更记录。
• TUF规范集成：遵循TUF框架的元数据管理机制，生成符合TUF标准的公钥元数据（如root.json、targets.json），确保公钥分发的安全性。
• 自动同步机制：可配置定时任务或触发式同步，将最新公钥信息同步至TUF仓库，确保依赖OIDC服务的节点获取实时公钥。
• 安全合规：符合OIDC Core规范和TUF安全最佳实践，支持公钥过期策略、签名验证等安全机制，防止公钥篡改或伪造。
• 可观测性：提供日志输出（支持JSON格式）和健康检查接口，便于监控公钥账本状态及同步情况。

使用场景和适用范围

• 分布式身份验证系统：在采用OIDC进行跨服务身份验证的分布式架构中，统一管理各OIDC提供商的公钥，避免节点间公钥不一致导致的验证失败。
• TUF生态集成：已部署TUF框架的环境中，扩展支持OIDC公钥的安全管理，如容器平台、IoT设备管理系统等。
• 企业级应用：对身份验证安全性要求较高的企业应用，需严格控制OIDC公钥的生命周期，防止未授权公钥接入。
• 微服务架构：微服务间通过OIDC实现单点登录（SSO）时，确保各微服务节点实时获取最新公钥，保障身份验证连续性。

使用方法和配置说明

前置条件

• 已安装Docker Engine（20.10+）或Docker Desktop。
• 已部署TUF仓库（本地文件系统或远程存储，如S3、GCS），并拥有读写权限。
• 需提供OIDC提供商的基本信息（如provider ID、公钥类型等）。

Docker运行示例

bash
docker run -d \
  --name oidc-tuf-ledger \
  -v /path/to/local/tuf-repo:/tuf/repo \  # 挂载TUF仓库目录
  -e TUF_REPO_PATH=/tuf/repo \           # TUF仓库路径（容器内）
  -e LOG_LEVEL=info \                    # 日志级别（debug/info/warn/error）
  -e SYNC_INTERVAL=3600 \                # 公钥同步间隔（秒，默认3600）
  -p 8080:8080 \                         # 暴露健康检查和API端口
  oidc-tuf-ledger-manager:latest

环境变量配置

Docker Compose配置示例

yaml
version: '3.8'
services:
  oidc-tuf-ledger:
    image: oidc-tuf-ledger-manager:latest
    container_name: oidc-tuf-ledger
    volumes:
      - ./tuf-repo:/tuf/repo  # 本地TUF仓库目录映射
    environment:
      - TUF_REPO_PATH=/tuf/repo
      - LOG_LEVEL=info
      - SYNC_INTERVAL=1800  # 每30分钟同步一次
      - HEALTH_CHECK_PORT=8080
    ports:
      - "8080:8080"
    restart: unless-stopped

基本操作命令

容器运行后，可通过docker exec执行以下命令管理公钥账本：

添加OIDC提供商公钥

bash
docker exec oidc-tuf-ledger add-oidc-key \
  --provider-id "my-oidc-provider" \
  --public-key "-----BEGIN PUBLIC KEY-----..." \  # PEM格式公钥
  --algorithm "RS256" \  # 公钥算法（如RS256、ES256）
  --expires "2025-12-31T23:59:59Z"  # 公钥过期时间（可选）

更新OIDC提供商公钥

bash
docker exec oidc-tuf-ledger update-oidc-key \
  --provider-id "my-oidc-provider" \
  --new-public-key "-----BEGIN PUBLIC KEY-----..." \  # 新PEM公钥
  --new-algorithm "RS256"  # 新算法（可选，如不变可省略）

查看公钥账本

bash
docker exec oidc-tuf-ledger list-oidc-keys

触发手动同步

bash
docker exec oidc-tuf-ledger sync-tuf-repo

健康检查

容器暴露http://localhost:8080/health接口，返回状态码200表示服务正常，包含当前公钥账本版本、最后同步时间等信息：

json
{
  "status": "healthy",
  "ledger_version": 5,
  "last_sync_time": "2024-05-20T14:30:00Z",
  "provider_count": 3
}