Bitnami OAuth2 Proxy 镜像文档

镜像概述和主要用途

OAuth2 Proxy 是一个反向代理和静态文件服务器，通过身份验证提供商（如 Google、GitHub 等）验证用户账户，支持基于电子邮件、域或组的访问控制。Bitnami 提供的此 Helm Chart 用于在 Kubernetes 集群中快速部署 OAuth2 Proxy，支持生产级别的配置管理、资源优化和安全加固，适用于为无身份验证机制的应用添加 OAuth2 认证层。

OAuth2 Proxy 项目概述

商标说明：本软件包由 Bitnami 打包，提及的商标分属各自公司所有，使用不意味着任何关联或背书。

核心功能和特性

• 反向代理与认证集成：作为反向代理，为上游服务提供 OAuth2 认证能力，支持 Google、GitHub 等主流身份提供商
• 细粒度访问控制：可通过电子邮件、域或组限制用户访问
• Kubernetes 原生支持：通过 Helm Chart 实现一键部署，支持 Kubernetes 资源管理（如 Deployment、Service、Ingress）
• 安全配置：支持 TLS 加密、Cookie 安全存储、网络策略隔离
• 灵活扩展：支持资源请求/限制配置、Sidecar 容器集成、Pod 亲和性设置
• 持久化存储：通过 Persistent Volume Claims 保留配置和状态数据

使用场景和适用范围

• 内部服务保护：为 Kubernetes 集群内的内部 Web 服务（如 Dashboard、API 服务）添加 OAuth2 认证
• 遗留应用升级：为无身份验证机制的遗留应用快速集成现代 OAuth2 认证流程
• 开发/测试环境：在开发环境中快速部署临时认证代理，验证 OAuth2 集成逻辑
• 多租户隔离：通过域或组限制，实现多租户环境下的服务访问隔离

前提条件

• Kubernetes 集群版本 1.23+
• Helm 版本 3.8.0+
• 底层基础设施支持 PV 供应（Persistent Volume Provisioner）
• 如需扩展部署，需支持 ReadWriteMany 卷类型

安装方法

Helm 快速部署（TL;DR）

helm install my-release oci://registry-1.docker.io/bitnamicharts/oauth2-proxy

详细安装步骤

1. 添加 Helm 仓库（如未添加）：

   helm repo add bitnami [***]
   helm repo update
   

2. 部署 Helm Chart：

   helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/oauth2-proxy
   

   说明：需替换 REGISTRY_NAME 和 REPOSITORY_NAME。Bitnami 官方仓库示例：REGISTRY_NAME=registry-1.docker.io，REPOSITORY_NAME=bitnamicharts。

3. 验证部署：

   helm list  # 查看 release 状态
   kubectl get pods  # 确认 OAuth2 Proxy Pod 运行正常
   

Docker 直接运行示例

若需在非 Kubernetes 环境中使用，可直接通过 Docker 运行 Bitnami OAuth2 Proxy 镜像：

docker run --name oauth2-proxy -p 4180:4180 \
  -e OAUTH2_PROXY_CLIENT_ID=your-client-id \
  -e OAUTH2_PROXY_CLIENT_SECRET=your-client-secret \
  -e OAUTH2_PROXY_COOKIE_SECRET=your-cookie-secret \
  -e OAUTH2_PROXY_UPSTREAMS=[***] \
  -e OAUTH2_PROXY_PROVIDER=google \
  -e OAUTH2_PROXY_EMAIL_DOMAINS=example.com \
  bitnami/oauth2-proxy:latest

环境变量说明：

• OAUTH2_PROXY_CLIENT_ID：OAuth 提供商的客户端 ID
• OAUTH2_PROXY_CLIENT_SECRET：OAuth 提供商的客户端密钥
• OAUTH2_PROXY_COOKIE_SECRET：用于加密 Cookie 的随机字符串（建议 32 字节）
• OAUTH2_PROXY_UPSTREAMS：需保护的上游服务地址
• OAUTH2_PROXY_PROVIDER：身份提供商（如 google、github、azure 等）
• OAUTH2_PROXY_EMAIL_DOMAINS：允许访问的电子邮件域（如 example.com 或 * 允许所有）

配置说明

核心配置参数

通过 Helm 部署时，可通过 --set 或 values.yaml 文件配置以下关键参数：

OAuth2 Proxy 核心配置

流量暴露配置

资源配置

高级配置

Ingress 集成

启用 Ingress 以通过域名访问 OAuth2 Proxy：

ingress:
  enabled: true
  hostname: oauth2-proxy.example.com
  tls: true
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod

持久化存储

OAuth2 Proxy 数据和配置存储在容器内 /bitnami 路径，可通过 PersistentVolumeClaim 持久化：

persistence:
  enabled: true
  storageClass: "standard"
  size: 1Gi
  accessModes:
    - ReadWriteOnce

Sidecar 容器集成

添加额外 Sidecar 容器（如日志收集器、监控代理）：

sidecars:
  - name: fluent-bit
    image: bitnami/fluent-bit:latest
    imagePullPolicy: Always
    volumeMounts:
      - name: logs
        mountPath: /var/log/oauth2-proxy

Pod 亲和性配置

通过亲和性规则控制 Pod 调度：

podAffinityPreset: soft
podAntiAffinityPreset: soft
nodeAffinityPreset:
  type: soft
  key: workload
  values:
    - auth-proxy

重要注意事项：Bitnami 镜像变更通知

自 2025 年 8 月 28 日起，Bitnami 将升级其公共镜像目录，推出 Bitnami Secure Images 计划，聚焦安全强化镜像：

• 社区用户：首次可访问安全优化版容器镜像，但免费 tier 将逐步弃用非强化的 Debian 基础镜像，仅保留 latest 标签用于开发环境
• 镜像迁移：现有所有容器镜像（包括历史版本标签，如 2.50.0）将在两周内从 docker.io/bitnami 迁移至 docker.io/bitnamilegacy，且不再更新
• 生产环境建议：生产环境需使用 Bitnami Secure Images，包含强化容器、更小攻击面、CVE 透明度（VEX/KEV）、SBOMs 和企业支持

详情参见 Bitnami Secure Images 公告。

参考链接

• OAuth2 Proxy 官方仓库
• Bitnami OAuth2 Proxy Helm Chart 完整文档
• Bitnami 容器镜像仓库