monostream/glass

透明认证代理镜像文档

镜像概述与主要用途

本镜像是一个透明认证代理解决方案，旨在为后端服务提供无需修改代码的认证集成能力。通过透明代理模式拦截请求并处理认证流程，同时支持高级访问配置功能，可实现细粒度的权限控制和动态访问策略管理。适用于需要统一认证入口、保护内部服务或实现动态权限调整的场景。

核心功能与特性

• 透明代理模式：无需修改后端服务代码，即可集成认证功能，降低系统改造复杂度
• 多认证协议支持：兼容 OAuth2.0、OpenID Connect、SAML 2.0、LDAP 等主流认证协议
• 高级访问配置：支持基于角色(RBAC)、属性(ABAC)的细粒度访问控制，动态调整访问策略
• 流量透传：保持原始请求上下文（客户端IP、Headers等），确保后端服务正常工作
• 审计与监控：提供详细的认证日志和访问审计记录，支持 Prometheus 监控指标集成
• 高可用设计：支持集群部署模式，确保认证服务无单点故障风险

使用场景与适用范围

典型应用场景

• 企业内部服务认证：为内部Web应用、API服务提供统一认证入口，简化多系统登录流程
• API网关前置认证：作为API网关的认证层，保护后端微服务集群，实现统一安全控制
• 多租户权限隔离：在SaaS平台中实现租户间资源隔离和差异化权限管理
• 动态权限调整：需要根据业务规则实时更新访问策略的业务系统
• 合规审计需求：满足***、***等行业对访问日志留存和安全审计的合规要求

适用范围

• 中小型企业内部系统认证集成
• 微服务架构中的统一认证层
• 需要快速实现认证功能的遗留系统改造
• 对访问控制粒度有较高要求的业务系统

使用方法与配置说明

快速启动命令（docker run）

bash
docker run -d \
  --name transparent-auth-proxy \
  -p 8080:8080 \
  -e BACKEND_SERVICE_URL=http://backend-service:8080 \
  -e AUTH_PROVIDER=oauth2 \
  -e OAUTH2_CLIENT_ID=your-client-id \
  -e OAUTH2_CLIENT_SECRET=your-client-secret \
  -e OAUTH2_REDIRECT_URI=http://localhost:8080/callback \
  -e OAUTH2_AUTH_URL=https://auth-provider.com/auth \
  -e OAUTH2_TOKEN_URL=https://auth-provider.com/token \
  -v ./access-policies:/etc/auth-proxy/policies \
  -v ./logs:/var/log/auth-proxy \
  transparent-auth-proxy:latest

Docker Compose 配置示例

yaml
version: '3.8'
services:
  auth-proxy:
    image: transparent-auth-proxy:latest
    container_name: transparent-auth-proxy
    restart: always
    ports:
      - "8080:8080"
    environment:
      # 基础配置
      - BACKEND_SERVICE_URL=http://backend-app:8080  # 后端服务地址
      - LISTEN_PORT=8080                             # 代理服务监听端口
      - LOG_LEVEL=info                               # 日志级别(debug/info/warn/error)
      - TRANSPARENT_MODE=true                        # 启用透明模式
      
      # 认证提供商配置(OAuth2示例)
      - AUTH_PROVIDER=oauth2
      - OAUTH2_CLIENT_ID=your-client-id
      - OAUTH2_CLIENT_SECRET=your-client-secret
      - OAUTH2_AUTH_URL=https://auth.example.com/oauth/authorize
      - OAUTH2_TOKEN_URL=https://auth.example.com/oauth/token
      - OAUTH2_REDIRECT_URI=http://localhost:8080/callback
      - OAUTH2_SCOPE=openid profile email
      
      # 访问策略配置
      - ACCESS_POLICY_PATH=/etc/auth-proxy/policies
    volumes:
      - ./access-policies:/etc/auth-proxy/policies  # 挂载访问策略配置目录
      - ./logs:/var/log/auth-proxy                  # 挂载日志目录
    depends_on:
      - backend-app

  backend-app:
    image: your-backend-application:latest
    container_name: backend-service
    ports:
      - "8081:8080"

核心环境变量配置说明

访问策略配置示例

访问策略通过JSON格式文件定义，放置在ACCESS_POLICY_PATH目录下，支持多文件配置。策略文件示例(default-policy.json)：

json
{
  "policies": [
    {
      "name": "admin-api-access",
      "path": "/api/admin/*",
      "methods": ["GET", "POST", "PUT", "DELETE"],
      "roles": ["admin", "super-admin"],
      "action": "allow",
      "priority": 100
    },
    {
      "name": "user-read-access",
      "path": "/api/data/*",
      "methods": ["GET"],
      "roles": ["user", "admin"],
      "action": "allow",
      "priority": 50
    },
    {
      "name": "deny-all-others",
      "path": "/*",
      "methods": ["*"],
      "roles": ["*"],
      "action": "deny",
      "priority": 10
    }
  ]
}

卷挂载说明

注意事项

1. 首次启动前需确保后端服务可访问，BACKEND_SERVICE_URL配置正确
2. 策略文件修改后无需重启容器，代理每30秒自动扫描更新策略配置
3. 生产环境建议启用HTTPS，可通过挂载证书目录并配置ENABLE_HTTPS=true实现
4. 敏感配置（如客户端密钥、LDAP密码）建议使用Docker Secrets或环境变量注入，避免明文存储
5. 高并发场景下建议调整容器资源限制（--memory、--cpus参数）并启用集群部署