JWT Proxy 镜像文档

一、镜像概述与主要用途

JWT Proxy 是一款用于服务间请求认证与授权的互补性服务，旨在保障分布式系统中服务间通信的安全性。该镜像包含两个核心组件：

• 正向代理（Forward Proxy）：配置用于签署出站请求（发送至其他服务），为请求附加JWT认证信息。
• 反向代理（Reverse Proxy）：配置用于验证入站请求（来自其他服务），确保请求经过合法签名。

二、核心功能与特性

2.1 JWT 正向代理（Forward Proxy）

用于使用私钥对出站请求进行JWT签名，核心特性包括：

• 自动添加 Authorization 请求头，包含请求源服务标识、目标服务标识等JWT声明。
• 支持自动生成私钥对，并将公钥发布至符合 密钥服务器规范 的服务器。
• 支持使用预共享私钥（适用于高可用场景下的源服务）。
• 通过可配置的证书颁发机构（CA），使用中间人（MITM）SSL机制签署HTTPS请求。

潜在特性（规划中）：

• 支持通过配置添加静态JWT声明。
• 支持从请求头读取动态声明并转换为JWT声明。

限制：

• 启用MITM SSL时，CONNECT 隧道机制仅支持转发HTTPS请求（默认客户端均使用 CONNECT 处理HTTPS请求，完全兼容）。

2.2 JWT 反向代理（Reverse Proxy）

用于验证由正向代理签署的入站请求，核心特性包括：

• 解码并验证入站请求的 Authorization JWT头。
• 基于指定签名密钥，通过 密钥服务器 获取公钥并验证签名。
• 支持通过预共享公钥验证单一签发者（主要用于测试场景）。
• 支持为上游服务执行SSL终止，验证HTTPS请求。
• 提供可插拔的声明验证器接口，内置静态声明验证器实现。

三、使用场景与适用范围

正向代理适用场景

• 服务间通信签名：微服务架构中，源服务通过正向代理对出站请求进行JWT签名，确保目标服务可验证请求合法性。
• 跨服务身份传递：在分布式系统中，通过JWT声明传递服务身份、用户上下文等信息，简化跨服务认证流程。
• 高可用服务部署：结合预共享私钥，支持多实例源服务使用统一密钥签名请求。

反向代理适用场景

• 入站请求验证：目标服务通过反向代理验证入站请求的JWT签名，拒绝未授权或篡改的请求。
• 集中式认证：将JWT验证逻辑下沉至代理层，简化业务服务的认证逻辑。
• SSL终止与解密：作为HTTPS终端节点，解密请求后转发至上游服务，同时验证JWT有效性。

四、使用方法与配置说明

4.1 基本运行命令

通过配置文件启动JWT Proxy：

jwtproxy -config config.yaml

4.2 配置文件结构

配置文件以 jwtproxy 为顶层键，通过 signer_proxy 启用正向代理，通过 verifier_proxies 启用一个或多个反向代理。基本结构如下：

jwtproxy:
  # 正向代理配置（可选，存在则启用正向代理）
  signer_proxy:
    <Signer Config>

  # 反向代理配置（可选，存在则启用反向代理，支持多实例）
  verifier_proxies:
    - <Verifier Config>
    - <Verifier Config>

4.3 详细配置参数

4.3.1 正向代理配置（Signer Config）

用于配置JWT正向代理，示例及参数说明如下：

jwtproxy:
  signer_proxy:
    enabled: <bool>  # 是否启用，默认true
    listen_addr: <string>  # 代理绑定地址，默认":8080"
    shutdown_timeout: <time.Duration>  # 关闭超时，默认"1m"
    
    # MITM SSL配置（可选，用于签署HTTPS请求）
    ca_key_file: <path>  # CA私钥文件路径（必填，否则HTTPS请求将被拒绝）
    ca_crt_file: <path>  # CA证书文件路径（必填，否则HTTPS请求将被拒绝）
    trusted_certificates: <[]string>  # 信任的证书列表，默认使用系统根证书
    insecure_skip_verify: <bool>  # 是否跳过远程服务证书验证，默认false

    signer:
      issuer: <string>  # 签发者标识（必填，如服务名称）
      expiration_time: <time.Duration>  # JWT有效期，默认"5m"
      max_skew: <time.Duration>  # 允许的时间偏差，默认"1m"
      nonce_length: <int>  # 随机数长度，默认32
      
      # 私钥配置（必填，支持自动生成或预共享）
      private_key:
        type: <string>  # 私钥类型："autogenerated"（自动生成）或"preshared"（预共享）
        options: <map[string]interface{}>  # 对应类型的配置选项

私钥配置示例：

• 自动生成私钥（自动生成密钥对并发布公钥至密钥服务器）：

  private_key:
    type: autogenerated
    options:
      rotate_every: <time.Duration>  # 密钥轮换周期，默认"12h"
      key_folder: <string>  # 密钥存储目录，默认"~/.config/jwtproxy/"
      key_server:  # 密钥服务器配置（需符合密钥注册中心规范）
        type: keyregistry
        options:
          registry: <string>  # 密钥服务器基础URL（必填）
  

• 预共享私钥（使用指定的私钥文件）：

  private_key:
    type: preshared
    options:
      key_id: <string>  # 密钥唯一标识（必填）
      private_key_path: <path>  # PEM格式私钥文件路径（必填）
  

4.3.2 反向代理配置（Verifier Config）

用于配置JWT反向代理，示例及参数说明如下：

jwtproxy:
  verifier_proxies:
    - enabled: <bool>  # 是否启用，默认true
      listen_addr: <string>  # 绑定地址（支持HTTP/HTTPS URL或UNIX socket，格式"unix:/path"），默认":8081"
      shutdown_timeout: <time.Duration>  # 关闭超时，默认"1m"
      
      # SSL终止配置（可选，启用HTTPS时必填）
      key_file: <path>  # PEM格式私钥文件路径
      crt_file: <path>  # PEM格式证书文件路径

      verifier:
        upstream: <string>  # 上游服务地址（支持HTTP/HTTPS URL或UNIX socket），必填
        audience: <string>  # JWT受众声明（aud）的预期值（如服务URL），必填
        max_skew: <time.Duration>  # 允许的时间偏差，默认"1m"
        max_ttl: <time.Duration>  # JWT最大生存时间，默认"5m"
        excludes: <[]string>  # 无需认证的路径列表（如"/healthz"），默认nil
        auth_redirect_url: <string>  # 未认证请求重定向URL，默认返回403
        cookies_enabled: <bool>  # 是否从"access_token" cookie提取JWT，默认false
        
        # 公钥获取配置（必填）
        key_server:
          type: <string>  # 密钥服务器类型："keyregistry"（密钥注册中心）或"preshared"（预共享，测试用）
          options: <map[string]interface{}>  # 对应类型的配置选项
        
        # 随机数（nonce）存储配置（必填）
        nonce_storage:
          type: <string>  # 存储类型："local"（内存缓存）或"void"（不验证）
          options: <map[string]interface{}>  # 对应类型的配置选项

密钥服务器配置示例：

• 密钥注册中心（从密钥服务器动态获取公钥）：

  key_server:
    type: keyregistry
    options:
      registry: <string>  # 密钥服务器基础URL，必填
      cache:  # 缓存配置（可选）
        duration: <time.Duration>  # 缓存有效期，默认"10m"
        purge_interval: <time.Duration>  # 缓存清理间隔，默认"1m"
  

• 预共享密钥服务器（测试用，仅支持单个公钥）：

  key_server:
    type: preshared
    options:
      issuer: <string>  # 允许的签发者标识，必填
      key_id: <string>  # 密钥唯一标识，必填
      public_key_path: <path>  # PEM格式公钥文件路径，必填
  

随机数存储配置示例：

• 本地内存缓存（存储并验证nonce，防止重放攻击）：

  nonce_storage:
    type: local
    options:
      purge_interval: <time.Duration>  # 缓存清理间隔，默认0（即时清理）
  

• 空存储（不验证nonce，适用于无需严格唯一性校验场景）：

  nonce_storage:
    type: void
  

4.4 密钥生成

4.4.1 正向代理CA证书与私钥

正向代理签署HTTPS请求时需作为中间人（MITM），需生成CA证书和私钥以伪造目标服务器证书。若未指定，代理将拒绝转发HTTPS请求。

生成有效期1年的CA证书和私钥（无密码）：

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ca.key -out ca.crt

• ca.crt：CA证书，需分发给所有通过正向代理发起请求的客户端并信任。
• ca.key：CA私钥，需保密，通过 ca_key_file 和 ca_crt_file 配置到正向代理。

4.4.2 反向代理密钥对

反向代理启用SSL终止时，需提供服务端证书和私钥（可自签名或由CA签发）。

生成自签名密钥对（有效期1年）：

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout reverseProxy.key -out reverseProxy.crt

• 需确保证书的 Common Name 与反向代理的访问域名一致。
• 通过 key_file 和 crt_file 配置到反向代理。

五、Docker部署方案

5.1 构建Docker镜像

docker build -t jwtproxy .

5.2 运行Docker容器

将本地配置文件挂载至容器，指定配置启动：

docker run -it -v /path/to/local/config:/config jwtproxy -config /config/config.yaml

• /path/to/local/config：本地存放 config.yaml、CA证书、密钥等文件的目录。

5.3 Docker Compose示例

创建 docker-compose.yml：

version: "3"
services:
  jwtproxy:
    build: .
    volumes:
      - ./config:/config  # 挂载本地配置目录
    ports:
      - "8080:8080"  # 正向代理端口（若启用）
      - "8081:8081"  # 反向代理端口（若启用）
    command: -config /config/config.yaml

启动服务：

docker-compose up -d

六、构建与测试

6.1 本地测试

运行项目测试用例：

go test ./...

6.2 本地构建二进制

go build -o jwtproxy cmd/jwtproxy/main.go

运行二进制：

./jwtproxy -config config.yaml