Vouch Proxy

Vouch Proxy 是什么?

Vouch Proxy 是 Nginx 的 OIDC/OAuth2 单点登录代理，使用 auth_request 模块。它在请求到达应用程序之前验证每个请求，并通过您选择的身份提供商处理身份验证。Vouch Proxy 和 Authelia 互斥；只能安装其中一个。

支持的身份提供商

Vouch Proxy 支持许多身份提供商，包括：

Okta
Google
GitHub（和 GitHub Enterprise）
Azure AD
Keycloak
Gitea
Nextcloud
任何通用的 OIDC 提供商（Ping Identity、Auth0 等）

工作原理

用户访问您的受保护应用程序
Nginx 将请求转发到 Vouch Proxy 的 /validate 端点
如果存在有效的 JWT cookie → 请求通过（HTTP 200）
如果没有有效的 cookie → 重定向到 IdP 登录（HTTP 401）
用户在其 IdP 登录
Vouch Proxy 收到授权并设置 JWT cookie
Cookie 在所有受保护的子域中有效

前置要求

在安装 Vouch Proxy 之前，您需要：

向您选择的身份提供商注册 OAuth2/OIDC 应用程序
获取这些凭证:
- 客户端 ID
- 客户端密钥
- 授权 URL（授权端点）
- 令牌 URL
- 用户信息 URL
设置回调 URL 为: https://YOUR_DOMAIN/vouch/auth

查找 IdP 端点

大多数 OIDC 提供商在以下位置发布其端点：

https://YOUR_IDP/.well-known/openid-configuration

例如，Okta 在以下位置发布其端点：

https://myorg.okta.com/.well-known/openid-configuration

安装

基本安装

box install vouchproxy \
  --auth-url URL \
  --token-url URL \
  --userinfo-url URL \
  --client-id ID \
  --client-secret SECRET \
  --domain example.com

使用 Okta 安装（示例）

box install vouchproxy \
  --auth-url https://myorg.okta.com/oauth2/v1/authorize \
  --token-url https://myorg.okta.com/oauth2/v1/token \
  --userinfo-url https://myorg.okta.com/oauth2/v1/userinfo \
  --client-id 0oa1234567abcdefgh \
  --client-secret your_client_secret \
  --domain example.com

可选标志

--end-session-endpoint URL - IdP 登出/撤销端点以支持登出
--email-domains CSV - 将登录限制为特定的电子邮件域（逗号分隔）
--oidc-user USER - 允许访问本地管理员的 OIDC 用户名（默认：本地管理员用户名）
--oidc-map CSV - 将 OIDC 用户名映射到本地管理员（逗号分隔）

管理

更新: box update vouchproxy
删除: box remove vouchproxy

身份验证迁移

如果您从另一个身份验证提供商迁移：

qbAuthMigrate --provider vouch

此命令处理感知提供商的 Nginx 身份验证迁移并保留现有配置。

限制

qbAuthMigrate 只能从基本身份验证或存储身份验证迁移到基本身份验证。它无法直接转换现有的 Authelia 或 Vouch Proxy 配置。

要求

必须安装 Docker
Vouch Proxy 的有效 HTTPS 域
来自身份提供商的 OAuth2/OIDC 凭证
对 IdP 端点的网络访问权限

Vouch Proxy 是什么?​

支持的身份提供商​

工作原理​

前置要求​

查找 IdP 端点​

安装​

基本安装​

使用 Okta 安装（示例）​

可选标志​

管理​

身份验证迁移​

要求​