oidc-agent 容器镜像文档

概述

本镜像为oidc-agent的容器化版本，oidc-agent是一款轻量级工具，用于安全管理OpenID Connect (OIDC) 凭证（如访问令牌、刷新令牌）。该镜像解决了传统环境中凭证明文存储、手动刷新及跨应用共享困难等问题，提供加密存储、自动更新及标准化共享机制，适用于各类需要OIDC认证的应用场景。

核心功能

• 安全凭证存储：采用加密方式存储OIDC凭证，避免明文暴露，支持用户自定义加密密码。
• 自动令牌刷新：监控凭证有效期，自动向OIDC提供商发起刷新请求，维持凭证有效性。
• 跨应用共享：通过Unix域套接字实现凭证跨进程/容器共享，支持多个应用使用同一套凭证。
• 多提供商支持：兼容主流OIDC提供商（如Keycloak、Google、Microsoft Azure AD等），支持自定义提供商配置。
• 完整命令行工具：内置oidc-add（添加凭证）、oidc-token（获取令牌）、oidc-remove（删除凭证）等命令，满足凭证全生命周期管理需求。

使用场景

• 开发环境：本地开发时管理OIDC凭证，避免硬编码或手动复制令牌。
• 多应用服务器：同一主机/容器集群内多个应用共享OIDC凭证，减少重复认证流程。
• 长时间运行服务：后台服务、定时任务等需持续使用OIDC凭证的场景，依赖自动刷新功能维持服务连续性。
• CI/CD流水线：在构建或部署阶段临时注入OIDC凭证，完成需认证的资源访问（如拉取私有镜像、调用API）。

使用方法

基本运行

启动容器并持久化存储凭证数据（推荐挂载宿主机目录以保留配置和凭证）：

bash
docker run -d \
  --name oidc-agent \
  -v /host/path/oidc-agent-data:/var/lib/oidc-agent \  # 持久化凭证数据
  -v /host/path/oidc-agent-config:/root/.oidc-agent \  # 持久化配置文件
  --restart unless-stopped \
  oidc-agent:latest

进入容器操作

通过docker exec进入容器，使用oidc-agent命令管理凭证：

bash
# 进入容器
docker exec -it oidc-agent bash

# 添加OIDC提供商凭证（示例：添加名为"my-provider"的凭证）
oidc-add my-provider --issuer [***]

# 获取凭证（供其他应用使用）
oidc-token my-provider

跨容器共享凭证

其他容器可通过挂载/host/path/oidc-agent-config目录（包含Unix套接字）访问凭证：

bash
# 示例：启动应用容器并共享oidc-agent凭证
docker run -d \
  --name my-app \
  -v /host/path/oidc-agent-config:/root/.oidc-agent \  # 共享套接字目录
  my-app-image:latest

配置参数

环境变量

数据卷挂载

示例配置

docker-compose.yml

yaml
version: '3.8'

services:
  oidc-agent:
    image: oidc-agent:latest
    container_name: oidc-agent
    volumes:
      - ./oidc-agent-data:/var/lib/oidc-agent
      - ./oidc-agent-config:/root/.oidc-agent
    environment:
      - OIDC_AGENT_LOG_LEVEL=info
      - OIDC_AGENT_ENCRYPT_PASSWORD=${OIDC_ENCRYPT_PASSWORD}  # 从环境变量注入加密密码
    restart: unless-stopped

  app:
    image: my-app:latest
    volumes:
      - ./oidc-agent-config:/root/.oidc-agent  # 共享凭证套接字
    depends_on:
      - oidc-agent

注意事项

• 数据持久化：必须挂载数据卷（/var/lib/oidc-agent和/root/.oidc-agent），否则容器重启后凭证和配置将丢失。
• 加密密码安全：OIDC_AGENT_ENCRYPT_PASSWORD建议通过容器编排工具的secret管理功能（如Docker Swarm Secrets、Kubernetes Secrets）注入，避免明文暴露。
• 网络隔离：限制容器网络访问，仅允许信任的应用容器挂载套接字目录，防止未授权访问凭证。
• 版本更新：定期更新镜像至最新版本，以获取安全补丁和功能优化。