voucher/vouch-proxy

Vouch Proxy

https://goreportcard.com/badge/github.com/vouch/vouch-proxy](https://goreportcard.com/report/github.com/vouch/vouch-proxy)

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

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

• Google
• https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/about-authorization-options-for-oauth-apps/
• GitHub Enterprise
• IndieAuth
• Okta
• https://github.com/vouch/vouch-proxy/pull/68
• https://github.com/vouch/vouch-proxy/issues/290
• https://github.com/vouch/vouch-proxy/issues/344
• https://github.com/vouch/vouch-proxy/issues/105
• https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example_gitea
• Keycloak
• https://github.com/vouch/vouch-proxy/issues/99
• HomeAssistant
• https://github.com/vouch/vouch-proxy/pull/141
• 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）登录并认证（如上述列出的服务）。

!https://github.com/vouch/vouch-proxy/blob/master/examples/nginx-vouch-private_simple.png?raw=true

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

!https://github.com/vouch/vouch-proxy/blob/master/examples/nginx-vouch-private_appA_appB_appC.png?raw=true

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

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

安装与配置

Vouch Proxy 依赖 Vouch Proxy 服务器与受保护应用之间共享 Cookie 的能力。通常通过将 Vouch 部署在子域（如 vouch.yourdomain.com），应用部署在 app1.yourdomain.com 和 app2.yourdomain.com 实现。受保护域为 .yourdomain.com，需通过设置 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example#L23-L33 包含 yourdomain.com，或有时通过设置 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example#L81-L82 为 yourdomain.com，确保 Vouch Proxy Cookie 在此域下设置。

• cp ./config/config.yml_example_$OAUTH_PROVIDER ./config/config.yml
• 在 Google 或 https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/about-authorization-options-for-oauth-apps/ 等平台为 Vouch Proxy 创建 OAuth 凭证
  • 确保将回调 URL 指向 Vouch Proxy 的 /auth 端点
• 配置 Nginx...

以下 Nginx 配置假设：

• Nginx、vouch.yourdomain.com 和 protectedapp.yourdomain.com 运行在同一服务器
• 所有域均通过 https 提供服务并拥有有效证书（若未使用 HTTPS，将 listen 改为 80 并设置 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example#L84-L85 为 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 http://127.0.0.1:9090/validate;
      # 确保传递原始主机头
      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 http://vouch.yourdomain.com/validate;
      # proxy_set_header Host $http_host;
    }

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

    location @error401 {
        # 重定向至 Vouch Proxy 进行登录
        return 302 https://vouch.yourdomain.com/login?url=$scheme://$http_host$request_uri&vouch-failcount=$auth_resp_failcount&X-Vouch-Token=$auth_resp_jwt&error=$auth_resp_err;
        # 通常建议将重定向指向由同一 Nginx 配置保护的 HTTPS 下的 Vouch
        # 但为快速开始，可直接将用户转发至 Vouch 运行的端口
        # return 302 http://vouch.yourdomain.com:9090/login?url=$scheme://$http_host$request_uri&vouch-failcount=$auth_resp_failcount&X-Vouch-Token=$auth_resp_jwt&error=$auth_resp_err;
    }

    location / {
      # 将授权请求转发至受保护服务 protectedapp.yourdomain.com
      proxy_pass http://127.0.0.1:8080;
      # 可能需要按 https://github.com/vouch/vouch-proxy/issues/26#issuecomment-425215810 在该块中设置这些变量
      #    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 反向代理之后（https://github.com/vouch/vouch-proxy/issues/64#issuecomment-461085139%EF%BC%89%EF%BC%8C%E7%A1%AE%E4%BF%9D%E6%AD%A3%E7%A1%AE%E4%BC%A0%E9%80%92 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 http://127.0.0.1:9090;
      # 确保传递原始主机头
      proxy_set_header Host $http_host;
    }
}

更多 Nginx 配置示例可在 https://github.com/vouch/vouch-proxy/tree/master/examples 目录中找到。

使用环境变量配置 Vouch Proxy

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

bash
VOUCH_DOMAINS=yourdomain.com \
  OAUTH_PROVIDER=google \
  OAUTH_CLIENT_ID=1234 \
  OAUTH_CLIENT_SECRET=secretsecret \
  OAUTH_CALLBACK_URL=https://vouch.yourdomain.com/auth \
  ./vouch-proxy

环境变量名称在 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example 中有详细说明。

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

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

高级配置

所有 Vouch Proxy 配置项在 https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example 中有详细说明。

• https://github.com/vouch/vouch-proxy/issues/76#issuecomment-464028743
• https://github.com/vouch/vouch-proxy/issues/216
• https://github.com/vouch/vouch-proxy/pull/205
• https://github.com/vouch/vouch-proxy/pull/247
• https://github.com/vouch/vouch-proxy/pull/263#issuecomment-628297832
• https://github.com/vouch/vouch-proxy/issues/291
• https://github.com/karthikv2k/oauth_reverse_proxy
• https://github.com/vouch/vouch-proxy/pull/332#issue-522612010
• https://github.com/vouch/vouch-proxy/issues/368

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

作用域与声明

通过 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 端点