voucher/vouch-proxy Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

Vouch Proxy

![GitHub stars]([] ![Go Report Card]([] ![MIT license]([] ![Docker pulls]([] ![GitHub version]([***]

基于 auth_request 模块的 Nginx 单点登录（SSO）解决方案。Vouch Proxy 可一次性保护您所有的网站。

Vouch Proxy 支持多种 OAuth 和 OIDC 登录提供商，并可强制通过以下身份提供商进行身份验证：

• Google
• GitHub
• GitHub Enterprise
• IndieAuth
• Okta
• ADFS
• Azure AD
• 阿里云 iDaas
• AWS Cognito
• Gitea
• Keycloak
• PHP OAuth2 服务器库
• HomeAssistant
• OpenStax
• Nextcloud
• 大多数其他 OpenID Connect（OIDC）提供商

如果您已使用偏好的身份提供商（IdP）或库部署了 Vouch Proxy，请告知我们，以便我们更新列表。

若 Vouch 与 Nginx 反向代理运行在同一主机上，从 /validate 端点到 Nginx 的响应时间应小于 1ms。

目录

• Vouch Proxy 功能概述
• 安装与配置
• 使用环境变量配置 Vouch Proxy
• 高级配置
  • 作用域与声明
• 通过 Docker 运行
• Kubernetes Nginx Ingress
• 从源码编译并运行二进制文件
• /login 和 /logout 端点重定向
• 故障排除、支持与功能请求 （提交 GitHub 问题前请阅读）
  • 遇到无限重定向循环并返回身份提供商（Google/Okta/GitHub/...）
  • 已查看问题并尝试配置但仍无法解决
  • 提交新功能的 Pull Request
• 使用 OpenResty 实现高级授权
• 使用 Google OAuth 的登录与认证流程

Vouch Proxy 功能概述

Vouch Proxy（VP）强制访问者在访问网站前通过身份提供商（IdP）登录并认证（如上述列出的服务）。

!Vouch Proxy 保护网站

VP 也可用作单点登录（SSO）解决方案，保护同一域下的所有 Web 应用。

!Vouch Proxy 作为单点登录解决方案

访问者登录后，Vouch Proxy 在数小时内允许其访问受保护网站。每个请求都会被 VP 检查以确保有效性。

VP 可将身份提供商提供的访问者***、姓名及其他信息（包括访问令牌）通过 HTTP 头发送给 Web 应用，完全替代应用的用户管理功能。

安装与配置

Vouch Proxy 依赖 Vouch Proxy 服务器与受保护应用之间共享 Cookie 的能力。通常通过将 Vouch 部署在子域（如 vouch.yourdomain.com），应用部署在 app1.yourdomain.com 和 app2.yourdomain.com 实现。受保护域为 .yourdomain.com，需通过设置 vouch.domains 包含 yourdomain.com，或有时通过设置 vouch.cookie.domain 为 yourdomain.com，确保 Vouch Proxy Cookie 在此域下设置。

• cp ./config/config.yml_example_$OAUTH_PROVIDER ./config/config.yml
• 在 Google 或 GitHub 等平台为 Vouch Proxy 创建 OAuth 凭证
  • 确保将回调 URL 指向 Vouch Proxy 的 /auth 端点
• 配置 Nginx...

以下 Nginx 配置假设：

• Nginx、vouch.yourdomain.com 和 protectedapp.yourdomain.com 运行在同一服务器
• 所有域均通过 https 提供服务并拥有有效证书（若未使用 HTTPS，将 listen 改为 80 并设置 vouch.cookie.secure 为 false）

server {
    listen 443 ssl http2;
    server_name protectedapp.yourdomain.com;
    root /var/www/html/;

    ssl_certificate /etc/letsencrypt/live/protectedapp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/protectedapp.yourdomain.com/privkey.pem;

    # 将所有请求发送至 `/validate` 端点进行授权
    auth_request /validate;

    location = /validate {
      # 将 /validate 请求转发至 Vouch Proxy
      proxy_pass [***]
      # 确保传递原始主机头
      proxy_set_header Host $http_host;

      # Vouch Proxy 仅作用于请求头
      proxy_pass_request_body off;
      proxy_set_header Content-Length "";

      # 可选：添加 Vouch Proxy 返回的 X-Vouch-User 至请求
      auth_request_set $auth_resp_x_vouch_user $upstream_http_x_vouch_user;

      # 可选：添加自定义声明（如 X-Vouch-IdP-Claims-*）
      #    auth_request_set $auth_resp_x_vouch_idp_claims_groups $upstream_http_x_vouch_idp_claims_groups;
      #    auth_request_set $auth_resp_x_vouch_idp_claims_given_name $upstream_http_x_vouch_idp_claims_given_name;
      # 可选：添加 X-Vouch-IdP-AccessToken 或 X-Vouch-IdP-IdToken
      #    auth_request_set $auth_resp_x_vouch_idp_accesstoken $upstream_http_x_vouch_idp_accesstoken;
      #    auth_request_set $auth_resp_x_vouch_idp_idtoken $upstream_http_x_vouch_idp_idtoken;

      # 这些返回值供 @error401 调用使用
      auth_request_set $auth_resp_jwt $upstream_http_x_vouch_jwt;
      auth_request_set $auth_resp_err $upstream_http_x_vouch_err;
      auth_request_set $auth_resp_failcount $upstream_http_x_vouch_failcount;

      # Vouch Proxy 可运行在同一 Nginx 反向代理之后
      # 可能需要符合 "upstream" 服务器命名
      # proxy_pass [***]
      # proxy_set_header Host $http_host;
    }

    # 若 validate 返回 `401 未授权`，则将请求转发至 error401block
    error_page 401 = @error401;

    location @error401 {
        # 重定向至 Vouch Proxy 进行登录
        return 302 [***]
        # 通常建议将重定向指向由同一 Nginx 配置保护的 HTTPS 下的 Vouch
        # 但为快速开始，可直接将用户转发至 Vouch 运行的端口
        # return 302 [***]
    }

    location / {
      # 将授权请求转发至受保护服务 protectedapp.yourdomain.com
      proxy_pass [***]
      # 可能需要按 [***] 在该块中设置这些变量
      #    auth_request_set $auth_resp_x_vouch_user $upstream_http_x_vouch_user
      #    auth_request_set $auth_resp_x_vouch_idp_claims_groups $upstream_http_x_vouch_idp_claims_groups;
      #    auth_request_set $auth_resp_x_vouch_idp_claims_given_name $upstream_http_x_vouch_idp_claims_given_name;

      # 设置用户头（通常为***）
      proxy_set_header X-Vouch-User $auth_resp_x_vouch_user;
      # 可选：传递自定义声明
      #     proxy_set_header X-Vouch-IdP-Claims-Groups $auth_resp_x_vouch_idp_claims_groups;
      #     proxy_set_header X-Vouch-IdP-Claims-Given_Name $auth_resp_x_vouch_idp_claims_given_name;
      # 可选：传递访问令牌或 ID 令牌
      #     proxy_set_header X-Vouch-IdP-AccessToken $auth_resp_x_vouch_idp_accesstoken;
      #     proxy_set_header X-Vouch-IdP-IdToken $auth_resp_x_vouch_idp_idtoken;
    }
}

若 Vouch 配置在同一 Nginx 反向代理之后（可能用于配置 SSL），确保正确传递 Host 头，否则 JWT Cookie 无法正确设置到域中：

server {
    listen 443 ssl http2;
    server_name vouch.yourdomain.com;
    ssl_certificate /etc/letsencrypt/live/vouch.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vouch.yourdomain.com/privkey.pem;

    location / {
      proxy_pass [***]
      # 确保传递原始主机头
      proxy_set_header Host $http_host;
    }
}

更多 Nginx 配置示例可在 examples 目录中找到。

使用环境变量配置 Vouch Proxy

以下是使用 Google OAuth 的最小化配置：

bash
VOUCH_DOMAINS=yourdomain.com \
  OAUTH_PROVIDER=google \
  OAUTH_CLIENT_ID=1234 \
  OAUTH_CLIENT_SECRET=secretsecret \
  OAUTH_CALLBACK_URL=[***] \
  ./vouch-proxy

环境变量名称在 config/config.yml_example 中有详细说明。

所有多值列表必须用逗号分隔：VOUCH_DOMAINS="yourdomain.com,yourotherdomain.com"

变量 VOUCH_CONFIG 可用于指定配置文件的替代路径。VOUCH_ROOT 可用于设置 Vouch Proxy 查找支持文件的替代根目录。

高级配置

所有 Vouch Proxy 配置项在 config/config.yml_example 中有详细说明。

• 在 Nginx 中缓存 Vouch Proxy 验证响应
• 使用 Vouch Proxy 保护 API 时处理 OPTIONS 请求
• 通过 GitHub 团队或组织进行验证
• 使用基于 ARM 的 Docker 镜像在树莓派上运行
• Kubernetes Ingress 架构
• 设置 HTTP_PROXY 通过出站代理服务器中继 Vouch Proxy IdP 请求
• Google Cloud Run 服务的反向代理
• 在 Vouch Proxy 中启用原生 TLS
• FreeBSD 支持

欢迎帮助我们扩展此列表。

作用域与声明

通过 Vouch Proxy，您可以请求各种 作用域（标准和自定义）以获取用户更多信息或访问提供商 API。Vouch Proxy 在成功认证后会向 user_info_url 发送请求，从提供商响应中提取所需 声明 并存储在 Vouch Cookie 中。

⚠️ 额外声明和令牌将添加到 VP Cookie 中，可能导致 Cookie 过大

VP Cookie 可能会被分割为多个 Cookie，但如果确实需要这些信息，则不可避免。大 Cookie 和头信息需要 Nginx 配置更大的缓冲区。详见 large_client_header_buffers 和 proxy_buffer_size。

在 Vouch Proxy 和 Nginx 中设置 作用域 和 声明

0. 按常规配置 Vouch Proxy 以用于 Nginx 和您的 IdP（参见：安装与配置）

1. 在 Vouch Proxy config.yml 的 oauth 部分设置必要的 作用域（示例配置）

   1. 在 Vouch Proxy config.yml 的 headers 部分设置 idtoken: X-Vouch-IdP-IdToken
   2. 登录并在现代浏览器中调用 /validate 端点
   3. 检查响应头中的 X-Vouch-IdP-IdToken 头
   4. 将头值复制到 [***] 调试器，确保包含必要声明
   5. 若不存在，调整 config.yml 中 oauth 部分的 作用域 或重新配置 OAuth 提供商

2. 在 Vouch Proxy config.yml 的 header 部分设置必要的 声明

   1. 登录并在现代浏览器中调用 /validate 端点