vouch proxy
1.0.0
使用 auth_request 模組的 Nginx SSO 解決方案。 Vouch Proxy 可以同時保護您的所有網站。
Vouch Proxy 支援許多 OAuth 和 OIDC 登入提供程序，並且可以強制執行身份驗證...
GitHub
GitHub 企業版
獨立認證
奧克塔
鬆弛
ADFS
Azure AD
阿里巴巴/阿里雲iDaas
AWS認知
抽搐
不和諧
安全認證
吉泰亞
鑰匙斗篷
PHP 的 OAuth2 伺服器庫
家庭助理
開放斯塔克斯
奧裡九頭蛇
下一個雲
大多數其他 OpenID Connect (OIDC) 供應商
當您使用首選 IdP 或庫部署 Vouch Proxy 時，請告知我們，以便我們更新清單。
如果 Vouch 與 Nginx 反向代理程式在同一台主機上執行，則從/validate端點到 Nginx 的回應時間應小於 1ms 。
憑證代理人的作用是什麼...
安裝與配置
驗證代理“在路徑中”
附加 Nginx 配置
透過環境變數進行配置
提示、技巧和進階配置
範圍和權利要求
從 Docker 運行
Kubernetes Nginx 入口
從原始碼編譯並執行二進位文件
/login 和 /logout 端點重定向
故障排除、支援和功能請求（在 GitHub 提交問題之前請閱讀本文）
我遇到無限重定向循環，該循環將我返回到我的 IdP (Google/Okta/GitHub/...)
好的，我查看了問題並嘗試了一些配置，但仍然無法正常工作
為 Vouch Proxy 做出貢獻
使用 OpenResty 進行進階授權
使用 Google Oauth 的登入和驗證流程
憑證代理程式 (VP) 強制訪客登入並透過 IdP（例如上面列出的服務之一）進行身份驗證，然後才允許他們存取網站。
VP 也可以用作單一登入 (SSO) 解決方案來保護相同網域中的所有 Web 應用程式。
訪客登入後，Vouch Proxy 允許在幾個小時內訪問受保護的網站。每個請求都會由 VP 檢查以確保其有效。
VP 可以將 IdP 提供的訪客的電子郵件、姓名和其他資訊（包括存取權杖）作為 HTTP 標頭髮送到 Web 應用程式。 VP可以用來完全取代應用程式的使用者管理。
Vouch Proxy 依賴在 Vouch Proxy 伺服器與其保護的應用程式之間共用 cookie 的能力。通常，這可以透過在子網域（例如vouch.yourdomain.com上執行 Vouch 來完成，並且應用程式在app1.yourdomain.com和app2.yourdomain.com上運行。受保護的網域是.yourdomain.com ，必須在此網域中設定 Vouch 代理 cookie，方法是將 vouch.domains 設定為包含yourdomain.com ，或有時將 vouch.cookie.domain 設定為yourdomain.com 。
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提供服務並具有有效的憑證（如果沒有，請變更為listen 80並將 vouch.cookie.secure 設定為false ）
伺服器 { 監聽 443 ssl http2; 伺服器名稱 protectedapp.yourdomain.com； 根/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 內容長度 ""; # 可選擇新增 Vouch 代理回傳的 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 反向代理後面運行 # 可能需要遵守“上游”伺服器命名 # proxy_pass http://vouch.yourdomain.com/validate; # proxy_set_header 主機 $http_host;
} # 如果 validate 回傳 `401 notauthorized`，則將請求轉送到 error401 區塊 error_page 401 = @error401; location @error401 { # 重定向到Vouch 代理進行登入return 302 https://vouch.yourdomain.com/login?url=$scheme://$http_host$request_uri&vouch-failcount=$auth_resp_failcount&X-Vouch-Token=$auth_resp_$ $ auth_resp_err； # 你通常*想要*重定向到在受 https 保護的同一個 Nginx 配置後面運行的 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_v_ 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; # 可選地傳遞 accesstoken 或 idtoken # 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;
}
}如果在同一個nginx 反向代理程式後面配置了 Vouch（也許可以設定 ssl），請確保正確傳遞Host標頭，否則無法將 JWT cookie 設定到網域中
伺服器 { 監聽 443 ssl http2; 伺服器名稱 vouch.yourdomain.com； ssl_certificate /etc/letsencrypt/live/vouch.yourdomain.com/fullchain.pem； ssl_certificate_key /etc/letsencrypt/live/vouch.yourdomain.com/privkey.pem； 位置/{ proxy_pass http://127.0.0.1:9090; # 一定要傳入原始主機頭 proxy_set_header Host $http_host;
}
}從v0.33.0開始，可以透過設定vouch.document_root: /vp_in_a_path
這樣就不需要為 Vouch Proxy 設定單獨的網域，例如vouch.yourdomain.com 。例如，VP 登入將從https://protectedapp.yourdomain.com/vp_in_a_path/login提供
伺服器 { 監聽 443 ssl http2; 伺服器名稱 protectedapp.yourdomain.com； ssl_certificate /etc/letsencrypt/live/protectedapp.yourdomain.com/fullchain.pem； ssl_certificate_key /etc/letsencrypt/live/protectedapp.yourdomain.com/privkey.pem； # 此位置為所有 Vouch 代理端點提供 /vp_in_a_path/$uri # 包含 /vp_in_a_path/validate、/vp_in_a_path/login、/vp_in_a_path/logout、/vp_in_a_path/ad、/vp_in_a_path/logout、/vp_in_a_path/acons、/vp_in_a_path/logout、/vp_in_a_path/acon、/vp_in_uth_path/ ://127.0.0.1:9090； #一定不能！ proxy_set_header 末端有一個斜線 Host $http_host; proxy_pass_request_body 關閉； proxy_set_header 內容長度 ""; # 這些回傳值由 @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；
} # 如果 /vp_in_a_path/validate 回傳 `401 notauthorized`，則將請求轉送至 error401 區塊 error_page 401 = @error401; location @error401 { # 重定向到Vouch 代理進行登入return 302 https://protectedapp.yourdomain.com/vp_in_a_path/login?url=$scheme://$http_host$request_uri&vouch-failcount=$auth_resp_failcount&kenp_ auth_resp_jwt&error =$auth_resp_err；
} 位置 / { auth_request /vp_in_a_path/validate; proxy_pass http://127.0.0.1:8080; # 請參閱上面的 Nginx 配置，以了解其他可以從 Vouch Proxy 設定的標頭
}
}其他 Nginx 設定可以在範例目錄中找到。
這是使用 Google 的 OAuth 的最小設定...
VOUCH_DOMAINS=yourdomain.com OAUTH_PROVIDER=谷歌 OAUTH_CLIENT_ID=1234 OAUTH_CLIENT_SECRET=秘密秘密 OAUTH_CALLBACK_URL=https://vouch.yourdomain.com/auth ./憑證代理
環境變數名稱記錄在 config/config.yml_example 中
所有具有多個值的清單都必須以逗號分隔： VOUCH_DOMAINS="yourdomain.com,yourotherdomain.com"
變數VOUCH_CONFIG可用於設定設定檔的備用位置。 VOUCH_ROOT可用於設定 Vouch Proxy 的備用根目錄以尋找支援檔案。
所有 Vouch Proxy 設定項都記錄在 config/config.yml_example 中
在 Nginx 中快取 Vouch 代理/validate回應
使用 Vouch 代理保護 API 時處理OPTIONS請求
由 GitHub 團隊或 GitHub Org 進行驗證
使用基於 ARM 的 Docker 映像在 Raspberry Pi 上執行 VP
Kubernetes 架構後入口
設定HTTP_PROXY以透過出站代理伺服器中繼 Vouch Proxy IdP 請求
Google Cloud Run 服務的反向代理
在 Vouch Proxy 中啟用本機 TLS
FreeBSD 支持
Vouch Proxy 的systemd啟動
使用 Node.js 而不是 Nginx 來路由請求
開發單頁應用程式 (SPA)，同時使用受 VP 保護的 API
將 Vouch Proxy 整合到伺服器端應用程式中以進行使用者 Authn 和 Authz
在 VP 驗證之前使用satisfy any;
請幫助我們擴展此列表。
使用 Vouch Proxy，您可以要求各種scopes （標準和自訂）以獲取有關使用者的更多資訊或存取提供者的 API。在內部，Vouch Proxy 在驗證成功後向user_info_url發起請求。所需的claims從提供者的回應中提取並儲存在 VP cookie 中。
VP cookie 可以分為多個 cookie，以適應瀏覽器 cookie 大小限制。但如果你需要它，你就需要它。大的 cookie 和標頭需要 Nginx 配置更大的緩衝區。有關詳細信息，請參閱 large_client_header_buffers 和 proxy_buffer_size。
scopes和claims正常設定 Nginx 的 Vouch 代理程式和 IdP（請參閱：安裝和設定）
在 vouch-proxy config.yml的oauth部分設定必要的scope （範例設定）
在 vouch-proxy 的config.yml的headers部分設定idtoken: X-Vouch-IdP-IdToken
在現代瀏覽器中登入並呼叫/validate端點
檢查回應標頭中的X-Vouch-IdP-IdToken標頭
將標頭的值複製到 https://jwt.io/ 的調試器中，並確保必要的聲明是 jwt 的一部分
如果不是，您需要調整config.yml的oauth部分中的scopes或重新配置您的 oauth 提供者
在 vouch-proxy config.yml的header部分中設定必要的claims
在現代瀏覽器中登入並呼叫/validate端點
檢查回應標頭中是否存在X-Vouch-IdP-Claims-<ClaimName>形式的標頭
如果它們不存在，請清除您的 cookie 和快取的瀏覽器數據
？如果它們仍然不存在但存在於 jwt 中（尤其是自訂聲明），則可能存在錯誤
如果不需要，請從 vouch-proxy 的config.yml的headers部分中刪除idtoken: X-Vouch-IdP-IdToken
在 nginx server.conf中受保護位置內的auth_request之後使用auth_request_set
使用聲明（範例 nginx 設定）
docker運行-d
-p 9090:9090
--名稱驗證代理
-v ${PWD}/config:/config
quay.io/vouch/vouch-proxy或者
docker運行-d
-p 9090:9090
--名稱驗證代理
-e VOUCH_DOMAINS=yourdomain.com
-e OAUTH_PROVIDER=谷歌
-e OAUTH_CLIENT_ID=1234
-e OAUTH_CLIENT_SECRET=秘密秘密
-e OAUTH_CALLBACK_URL=https://vouch.yourdomain.com/auth
quay.io/vouch/vouch-proxy從v0.36.0開始，容器中的 docker 程序以 UID /config/config.yml和 GID 999 的使用者vouch身分執行/config/secret docker run --user $UID:$GID ...或從原始碼建置 docker 容器並使用 UID 和 GID 的可用 ARG。
quay.io 提供每個 Vouch Proxy 版本的自動化容器建置。每個版本都會產生..
從Dockerfile建置的最小 go 二進位容器
quay.io/vouch/vouch-proxy:latest
quay.io/vouch/vouch-proxy:xyz例如quay.io/vouch/vouch-proxy:0.28.0
從Dockerfile.alpine的基於alpine的容器
quay.io/vouch/vouch-proxy:alpine-latest
quay.io/vouch/vouch-proxy:alpine-xyz
Docker Hub 上提供了 Vouch Proxy arm映像
voucher/vouch-proxy:latest-arm
如果您將 kubernetes 與 nginx-ingress 結合使用，則可以使用下列註解來設定您的 ingress（注意引用auth-signin註解）：
nginx.ingress.kubernetes.io/auth-signin：「https://vouch.yourdomain.com/login?url=$scheme://$http_host$request_uri&vouch-failcount=$auth_resp_failcount&X-Vouch-Token=$a_res_resp_jwt&error=$ auth_resp_err”
nginx.ingress.kubernetes.io/auth-url：https://vouch.yourdomain.com/validate
nginx.ingress.kubernetes.io/auth-response-headers：X-Vouch-User
nginx.ingress.kubernetes.io/auth-snippet：| # 這些回傳值由@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； # 當 VP 託管在 k8s 外部時，請確保 SSL 憑證有效以避免 MITM 風險 # proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; # proxy_ssl_session_reuse 開啟； # proxy_ssl_verify_深度 2; # proxy_ssl_verify 開啟；Helm Charts 由 punkle、martina-if 和 halkeye 維護，可在 https://github.com/vouch/helm-charts 上取得
./do.sh 戈吉特 ./do.sh 構建 ./憑證代理
從v0.29.0開始， .defaults.yml中的所有範本、靜態資源和設定預設值均使用 go:embed 指令建置到靜態二進位檔案中。
從v0.11.0開始，附加檢查已到位，以減少 url 重定向的攻擊面。
傳遞的網址...
必須以http或https開頭
必須與vouch.domains清單或vouch.cookie.domain中的網域重疊（如果配置了其中任何一個）
不能有包含 URL 的參數以防止 URL 連結攻擊
Vouch 代理程式/logout端點接受查詢字串中的url參數，可用於將使用者302重定向到原始 OAuth 提供者/IDP/OIDC 提供者的 revotion_endpoint
https://vouch.oursites.com/logout?url=https://oauth2.googleapis.com/revoke
此 url 必須存在於設定檔清單vouch.post_logout_redirect_uris中
# 為了防止重定向攻擊，必須指定所有重定向到/logout 的URL# 該URL 仍必須以https://vouch.yourdomain.com/logout?url=${ONE OF THE URLS BELOW}post_logout_redirect_uris 形式傳遞到Vouch代理: # 您的應用程式登入頁面
- https://yourdomain.com/login # 您的 IdP 登出點 # 來自 https://accounts.google.com/.well-known/openid-configuration
- https://oauth2.googleapis.com/revoke # 您可能透過菊花鏈連接到您的 IdP
- https://myorg.okta.com/oauth2/123serverid/v1/logout?post_logout_redirect_uri=http://myapp.yourdomain.com/login請注意，您的 IdP 可能會攜帶自己的單獨的post_logout_redirect_uri清單。
註銷資源..
奧克塔
驗證0
讓 Nginx、Vouch Proxy 和 IdP 之間的協調一致可能很棘手。我們希望幫助您盡快啟動並運行。最常見的問題是..
仔細檢查您是否在可以共用 cookie 的公共網域上執行 Vouch Proxy 和您的應用程式。例如， vouch.yourdomain.com和app.yourdomain.com可以共用.yourdomain.com網域上的 Cookie。 （如果您嘗試使用vouch.yourdomain.org和app.yourdomain.net ，它將不起作用。）
您可能需要明確定義應設定 cookie 的網域。您可以透過設定選項在設定檔中執行此操作：
vouch: cookie: # 強制cookie的網域設定domain: yourdomain.com
如果您仍然遇到問題，請嘗試以下操作：
開啟vouch.testing: true 。這會減慢循環速度。
設定vouch.logLevel: debug 。
http 請求中的Host:標頭、 oauth.callback_url和配置的vouch.domains必須全部對齊，以便攜帶 JWT 的 cookie 可以正確放置到瀏覽器中，然後在每個請求中返回
像餅乾一樣思考會很有幫助。
cookie 被設定到網域中。如果您的siteA.yourdomain.com和siteB.yourdomain.com受 Vouch Proxy 保護，您希望將 Vouch Proxy cookie 設定到.yourdomain.com
如果您透過vouch.yourdomain.com進行身份驗證，則dev.anythingelse.com將無法看到 cookie
除非您使用 https，否則應該設定vouch.cookie.secure: false
cookie可用於網域的所有連接埠
請查看已關閉的提及重定向的問題
請按以下方式提交新問題。
總而言之：
設定vouch.testing: true
設定vouch.logLevel: debug
進行兩次完整的往返./vouch-proxy捕獲輸出..
副總裁啟動
/validate
/login - 即使錯誤就在這裡
/auth
/validate - 捕獲一切
將所有日誌和配置放在gist中。
./do.sh bug_report是你的朋友
開啟vouch.testing: true並設定vouch.logLevel: debug 。
使用要點或其他貼上服務，例如 hasteb.in。不要將您的日誌和設定放入 GITHUB 問題中。使用貼上服務很重要，因為它將保持間距並提供行號和格式。我們正在大海撈針，設置有多個移動部件，這些功能有很大幫助。貼上服務可以節省您和我們的時間，並幫助我們快速為您提供協助。遵循此建議，您更有可能及時從我們那裡獲得良好的支援。
運行./do.sh bug_report secretdomain.com secretpass [anothersecret..]這將建立配置的編輯版本並記錄刪除每個字串
並按照最後的說明編輯 Nginx 配置
所有這些都有一個要點
然後在此存儲庫中開啟一個新問題
可以使用quay.io/vouch/vouch-proxy:alpine映像從 docker 環境產生錯誤報告...
docker run --name vouch_proxy -v $PWD/config:/config -v $PWD/certs:/certs -it --rm --entrypoint /do.sh quay.io/vouch/vouch-proxy:alpine bug_report yourdomain.com anotherdomain.com someothersecret我們很樂意您做出貢獻！詳情請參閱我們的貢獻指南。
OpenResty® 是一個成熟的 Web 平台，整合了標準的 Nginx 核心、LuaJIT、許多精心編寫的 Lua 庫、大量高品質的第 3 方 Nginx 模組及其大部分外部依賴項。
您可以相當輕鬆地用 OpenResty 取代 nginx。
透過 OpenResty 和 Lua，可以對任何標頭或聲明憑證傳遞提供客製化和進階授權。
範例目錄中提供了 OpenResty 和各種場景的設定。
鮑伯造訪https://private.oursites.com
Nginx 反向代理...
如果/validate返回...
透過 302 重定向到https://vouch.oursites.com/login?url=https://private.oursites.com來回應 Bob
200 OK then SUCCESS 允許鮑勃通過
401 則未授權
收到 Bob 發送的 private.oursites.com 請求
使用為/validate路徑配置的auth_request模組
/validate配置為將proxy_pass請求傳送至https://vouch.oursites.com/validate的驗證服務
憑證代理https://vouch.oursites.com/validate
返回401 NotAuthorized給 Nginx（將請求轉送至登入）
返回200 OK給 Nginx，這將允許訪問（鮑勃什麼也沒注意到）
透過 Nginx proxy_pass接收來自 Bob 的 private.oursites.com 請求
尋找名為「oursitesSSO」的 cookie，其中包含 JWT
如果找到 cookie，且 JWT 有效
如果找不到 cookie，或 JWT 無效
Bob 先簡短轉寄到https://vouch.oursites.com/login?url=https://private.oursites.com
清除名為“oursitesSSO”的 cookie（如果存在）
產生隨機數字並將其儲存在會話變數 $STATE 中
將查詢字串中的 url https://private.oursites.com儲存在會話變數$requestedURL中
透過 302 重定向到 Google 的 OAuth 登入表單來回應 Bob，包括$STATE隨機數
Bob 使用 Oauth 登入他的 Google 帳戶
登入成功後
Google 透過 302 重定向到https://vouch.oursites.com/auth?state=$STATE來回應 Bob
Bob 轉寄到https://vouch.oursites.com/auth?state=$STATE
以名為「oursitesSSO」的 cookie 形式向 bob 發出 JWT
檢索會話變數$requestedURL並將 bob 302 重新導向回https://private.oursites.com
如果 url 中的 $STATE 隨機數與會話變數「state」匹配
向 Google（伺服器到伺服器）發出「第三條腿」請求，以交換 Bob 的使用者資訊（包括電子郵件地址 [email protected]）的 OAuth 代碼
如果電子郵件地址與 oursites.com 網域相符（確實如此）
請注意，除了一些無害的重定向之外，Bob 只能在瀏覽器中看到https://private.oursites.com和 Google 登入畫面。雖然 Vouch 確實與 Bob 的瀏覽器進行了多次交互，但這只是為了設定 cookie，如果 302 重定向工作正常，Bob 將快速登入。
設定 JWT 後，Bob 將被授權存取配置為使用auth_request Nginx 模組中的https://vouch.oursites.com/validate的所有其他網站。
下次 Bob 被轉發到 google 進行登入時，由於他已經授權了 Vouch Proxy OAuth 應用程序，Google 會立即將他轉發回來並設定 cookie 並讓他繼續他的快樂之路。在某些瀏覽器（例如 Chrome）中，Bob 甚至可能沒有註意到他使用 Vouch Proxy 登入。
