搬瓦工 VPS OAuth2 Proxy 认证代理配置教程

OAuth2 Proxy 是一款开源的反向代理工具，可以为任何没有内置认证功能的 Web 应用添加 OAuth2 认证层。它支持 GitHub、Google、GitLab、Azure AD 等多种 OAuth2/OIDC 提供商，非常适合为内部工具和管理面板增加访问控制。本文将详细介绍如何在搬瓦工 VPS 上部署 OAuth2 Proxy，为你的应用穿上认证外衣。

一、OAuth2 Proxy 工作原理

OAuth2 Proxy 充当用户与后端应用之间的中间层。用户访问受保护的应用时，OAuth2 Proxy 会检查是否已通过认证：

未认证的用户会被重定向到 OAuth2 提供商的登录页面。
用户在提供商处完成登录后，OAuth2 Proxy 验证令牌并设置会话 Cookie。
后续请求通过 Cookie 验证身份，无需重复登录。
可以通过邮箱域名、GitHub 组织等维度控制访问权限。

二、准备工作

2.1 注册 GitHub OAuth App

以 GitHub 为例，在 GitHub Settings > Developer settings > OAuth Apps 中创建新应用：

Application name：你的应用名称
Homepage URL：https://app.example.com
Authorization callback URL：https://app.example.com/oauth2/callback

记录下 Client ID 和 Client Secret。

2.2 生成 Cookie Secret

openssl rand -base64 32 | tr -- '+/' '-_'

三、使用 Docker 部署

3.1 创建配置文件

mkdir -p /opt/oauth2-proxy
cat > /opt/oauth2-proxy/docker-compose.yml <<'EOF'
version: '3.8'

services:
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:latest
    container_name: oauth2-proxy
    restart: always
    ports:
      - "4180:4180"
    environment:
      OAUTH2_PROXY_PROVIDER: github
      OAUTH2_PROXY_CLIENT_ID: your_github_client_id
      OAUTH2_PROXY_CLIENT_SECRET: your_github_client_secret
      OAUTH2_PROXY_COOKIE_SECRET: your_cookie_secret_here
      OAUTH2_PROXY_COOKIE_SECURE: "true"
      OAUTH2_PROXY_COOKIE_DOMAINS: ".example.com"
      OAUTH2_PROXY_EMAIL_DOMAINS: "*"
      OAUTH2_PROXY_UPSTREAMS: "http://backend:8080"
      OAUTH2_PROXY_HTTP_ADDRESS: "0.0.0.0:4180"
      OAUTH2_PROXY_REDIRECT_URL: "https://app.example.com/oauth2/callback"
      OAUTH2_PROXY_SET_XAUTHREQUEST: "true"
      OAUTH2_PROXY_PASS_ACCESS_TOKEN: "true"
      OAUTH2_PROXY_GITHUB_ORG: "your-org"
    networks:
      - proxy-net

  backend:
    image: your-backend-app:latest
    container_name: backend
    restart: always
    networks:
      - proxy-net

networks:
  proxy-net:
EOF

3.2 启动服务

cd /opt/oauth2-proxy
docker compose up -d

四、配置 Nginx 反向代理

4.1 auth_request 模式

这种模式允许 Nginx 将认证请求转发给 OAuth2 Proxy，是最灵活的集成方式：

server {
    listen 443 ssl http2;
    server_name app.example.com;

    ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;

    location /oauth2/ {
        proxy_pass http://127.0.0.1:4180;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Auth-Request-Redirect $request_uri;
    }

    location = /oauth2/auth {
        proxy_pass http://127.0.0.1:4180;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header Content-Length "";
        proxy_pass_request_body off;
    }

    location / {
        auth_request /oauth2/auth;
        error_page 401 = /oauth2/sign_in;

        auth_request_set $user   $upstream_http_x_auth_request_user;
        auth_request_set $email  $upstream_http_x_auth_request_email;
        proxy_set_header X-User  $user;
        proxy_set_header X-Email $email;

        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

五、使用 Google OAuth 提供商

OAUTH2_PROXY_PROVIDER=google
OAUTH2_PROXY_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
OAUTH2_PROXY_CLIENT_SECRET=your_google_client_secret
OAUTH2_PROXY_EMAIL_DOMAINS=your-company.com
OAUTH2_PROXY_COOKIE_SECRET=your_cookie_secret

六、使用 Keycloak 作为 OIDC 提供商

如果已经搭建了 Keycloak，可以使用 OIDC 协议集成：

OAUTH2_PROXY_PROVIDER=oidc
OAUTH2_PROXY_OIDC_ISSUER_URL=https://keycloak.example.com/realms/myrealm
OAUTH2_PROXY_CLIENT_ID=oauth2-proxy
OAUTH2_PROXY_CLIENT_SECRET=your_keycloak_client_secret
OAUTH2_PROXY_EMAIL_DOMAINS=*
OAUTH2_PROXY_COOKIE_SECRET=your_cookie_secret
OAUTH2_PROXY_ALLOWED_GROUPS=/admin,/developers

七、高级配置

7.1 基于邮箱白名单

# 创建白名单文件
cat > /opt/oauth2-proxy/authenticated-emails.txt <<EOF
admin@example.com
developer@example.com
EOF

# 添加环境变量
OAUTH2_PROXY_AUTHENTICATED_EMAILS_FILE=/config/authenticated-emails.txt

7.2 跳过特定路径的认证

OAUTH2_PROXY_SKIP_AUTH_ROUTES="^/health$|^/api/public/.*"

7.3 会话存储使用 Redis

OAUTH2_PROXY_SESSION_STORE_TYPE=redis
OAUTH2_PROXY_REDIS_CONNECTION_URL=redis://redis:6379

八、验证与测试

# 检查 OAuth2 Proxy 是否运行正常
curl -I http://127.0.0.1:4180/ping

# 查看日志
docker logs oauth2-proxy

# 测试认证流程
# 使用浏览器访问 https://app.example.com，应被重定向到 GitHub 登录页

总结

OAuth2 Proxy 是为无认证功能的 Web 应用快速添加安全防护的利器，配合 GitHub、Google 或 Keycloak 等认证提供商，可以零代码改动实现应用的访问控制。搭建在搬瓦工 VPS 上的各种管理面板和内部工具都推荐使用 OAuth2 Proxy 进行保护。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，通过 bwh81.net 进入官网购买。