an SSO solution for Nginx using the auth_request module.
Vouch Proxy supports many OAuth login providers and can enforce authentication to...
- GitHub
- GitHub Enterprise
- IndieAuth
- Okta
- ADFS
- AWS Cognito
- Gitea
- Keycloak
- OAuth2 Server Library for PHP
- HomeAssistant
- OpenStax
- Nextcloud
- most other OpenID Connect (OIDC) providers
Please do let us know when you have deployed Vouch Proxy with your preffered IdP or library so we can update the list.
If Vouch is running on the same host as the Nginx reverse proxy the response time from the /validate endpoint to Nginx should be less than 1ms
Vouch Proxy relies on the ability to share a cookie between the Vouch Proxy server and the application it's protecting. Typically this will be done by running Vouch on a subdomain such as vouch.yourdomain.com with apps running at app1.yourdomain.com and app2.yourdomain.com. The protected domain is .yourdomain.com and the Vouch Proxy cookie must be set in this domain by setting vouch.domains to include yourdomain.com or sometimes by setting vouch.cookie.domain to yourdomain.com.
cp ./config/config.yml_example_$OAUTH_PROVIDER ./config/config.yml- create OAuth credentials for Vouch Proxy at google or github, etc
- be sure to direct the callback URL to the Vouch Proxy
/authendpoint
- be sure to direct the callback URL to the Vouch Proxy
- configure Nginx...
The following Nginx config assumes..
- Nginx,
vouch.yourdomain.comandprotectedapp.yourdomain.comare running on the same server - both domains are served as
httpsand have valid certs (if not, change tolisten 80and set vouch.cookie.domain tofalse)
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;
# send all requests to the `/validate` endpoint for authorization
auth_request /validate;
location = /validate {
# forward the /validate request to Vouch Proxy
proxy_pass http://127.0.0.1:9090/validate;
# be sure to pass the original host header
proxy_set_header Host $http_host;
# Vouch Proxy only acts on the request headers
proxy_pass_request_body off;
proxy_set_header Content-Length "";
# optionally add X-Vouch-User as returned by Vouch Proxy along with the request
auth_request_set $auth_resp_x_vouch_user $upstream_http_x_vouch_user;
# optionally add X-Vouch-IdP-Claims-* custom claims you are tracking
# 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;
# optinally add X-Vouch-IdP-AccessToken or 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;
# these return values are used by the @error401 call
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 can run behind the same Nginx reverse proxy
# may need to comply to "upstream" server naming
# proxy_pass http://vouch.yourdomain.com/validate;
# proxy_set_header Host $http_host;
}
# if validate returns `401 not authorized` then forward the request to the error401block
error_page 401 = @error401;
location @error401 {
# redirect to Vouch Proxy for login
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;
# you usually *want* to redirect to Vouch running behind the same Nginx config proteced by https
# but to get started you can just forward the end user to the port that vouch is running on
# 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 / {
# forward authorized requests to your service protectedapp.yourdomain.com
proxy_pass http://127.0.0.1:8080;
# you may need to set these variables in this block as per 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;
# set user header (usually an email)
proxy_set_header X-Vouch-User $auth_resp_x_vouch_user;
# optionally pass any custom claims you are tracking
# 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;
# optionally pass the accesstoken or 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;
}
}
If Vouch is configured behind the same nginx reverseproxy (perhaps so you can configure ssl) be sure to pass the Host header properly, otherwise the JWT cookie cannot be set into the domain
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;
# be sure to pass the original host header
proxy_set_header Host $http_host;
}
}
Additional Nginx configurations can be found in the examples directory.
Here's a minimal setup using Google OAuth...
VOUCH_DOMAINS=yourdomain.com \
OAUTH_PROVIDER=google \
OAUTH_CLIENT_ID=1234 \
OAUTH_CLIENT_SECRET=secretsecret \
OAUTH_CALLBACK_URL=https://vouch.yourdomain.com/auth \
./vouch-proxyEnvironmental variable names are documented in config/config.yml_example
All lists with multiple values must be comma separated: VOUCH_DOMAINS="yourdomain.com,yourotherdomain.com"
The variable VOUCH_CONFIG can be used to set an alternate location for the configuration file. VOUCH_ROOT can be used to set an alternate root directory for Vouch Proxy to look for support files.
- cacheing of the Vouch Proxy validation response in Nginx
- handleing
OPTIONSrequests when protecting an API with Vouch Proxy - validation by GitHub Team or GitHub Org
- running on a Raspberry Pi using the ARM based Docker image
- Kubernetes architecture post ingress
Please do help us to expand this list.
docker run -d \
-p 9090:9090 \
--name vouch-proxy \
-v ${PWD}/config:/config \
voucher/vouch-proxyor
docker run -d \
-p 9090:9090 \
--name vouch-proxy \
-e VOUCH_DOMAINS=yourdomain.com
-e OAUTH_PROVIDER=google
-e OAUTH_CLIENT_ID=1234
-e OAUTH_CLIENT_SECRET=secretsecret
-e OAUTH_CALLBACK_URL=https://vouch.yourdomain.com/auth
voucher/vouch-proxyAutomated container builds for each Vouch Proxy release are available from Docker Hub. Each release produces..
voucher/vouch-proxy:latestvoucher/vouch-proxy:x.y.zvoucher/vouch-proxy:alpinevoucher/vouch-proxy:alpine-x.y.zvoucher/vouch-proxy:latest-arm
If you are using kubernetes with nginx-ingress, you can configure your ingress with the following annotations (note quoting the auth-signin annotation):
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=$auth_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: |
# these return values are used by the @error401 call
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;Helm Charts are maintained by halkeye and are available at https://github.com/halkeye-helm-charts/vouch / https://halkeye.github.io/helm-charts/
./do.sh goget
./do.sh build
./vouch-proxyAs of v0.11.0 we have put additional checks in place to reduce the attack surface of url redirection.
The passed URL...
- must start with either
httporhttps - must have a domain overlap with either a domain in the
vouch.domainslist or thevouch.cookie.domain(if either of those are configured) - cannot have a parameter which includes a URL to prevent URL chaining attacks
The Vouch Proxy /logout endpoint accepts a url parameter in the query string which can be used to 302 redirect a user to your orignal OAuth provider/IDP/OIDC provider's revocation_endpoint
https://vouch.oursites.com/logout?url=https://oauth2.googleapis.com/revokethis url must be present in the configuration file on the list vouch.post_logout_redirect_uris
# in order to prevent redirection attacks all redirected URLs to /logout must be specified
# the URL must still be passed to Vouch Proxy as https://vouch.yourdomain.com/logout?url=${ONE OF THE URLS BELOW}
post_logout_redirect_uris:
# your apps login page
- http://.yourdomain.com/login
# your IdPs logout enpoint
# from https://accounts.google.com/.well-known/openid-configuration
- https://oauth2.googleapis.com/revoke
# you may be daisy chaining to your IdP
- https://myorg.okta.com/oauth2/123serverid/v1/logout?post_logout_redirect_uri=http://myapp.yourdomain.com/loginNote that your IdP will likely carry their own, separate post_logout_redirect_uri list.
logout resources..
Getting the stars to align between Nginx, Vouch Proxy and your IdP can be tricky. We want to help you get up and running as quickly as possible. The most common problem is..
Double check that you are running Vouch Proxy and your apps on a common domain that can share cookies. For example, vouch.yourdomain.com and app.yourdomain.com can share cookies on the .yourdomain.com domain. (It will not work if you are trying to use vouch.yourdomain.org and app.yourdomain.net.)
You may need to explicitly define the domain that the cookie should be set on. You can do this in the config file by setting the option:
vouch:
cookie:
# force the domain of the cookie to set
domain: yourdomain.comIf you continue to have trouble, try the following:
-
turn on
vouch.testing: true. This will slow down the loop. -
set
vouch.logLevel: debug. -
the
Host:header in the http request, theoauth.callback_urland the configuredvouch.domainsmust all align so that the cookie that carries the JWT can be placed properly into the browser and then returned on each request -
it helps to think like a cookie.
- a cookie is set into a domain. If you have
siteA.yourdomain.comandsiteB.yourdomain.comprotected by Vouch Proxy, you want the Vouch Proxy cookie to be set into.yourdomain.com - if you authenticate to
vouch.yourdomain.comthe cookie will not be able to be seen bydev.anythingelse.com - unless you are using https, you should set
vouch.cookie.secure: false - cookies are available to all ports of a domain
- a cookie is set into a domain. If you have
-
please see the issues which have been closed that mention redirect
Please submit a new issue in the following fashion..
- turn on
vouch.testing: trueand setvouch.logLevel: debug. - use hasteb.in, or another paste service or a gist to provide your logs and config. DO NOT PUT YOUR LOGS AND CONFIG INTO THE GITHUB ISSUE. Using a paste service is important as it will maintain spacing and will provide line numbers and formatting. We are hunting for needles in haystacks with setups with several moving parts, these features help considerably. Paste services save your time and our time and help us to help you quickly. You're more likely to get good support from us in a timely manner by following this advice.
- run
./do.sh bug_report yourdomain.com [yourotherdomain.com]which will create a redacted version of your config and logs- and follow the instructions at the end to redact your Nginx config
- all of those go into hasteb.in or a gist
- then open a new issue in this repository
- or visit our IRC channel #vouch on freenode
I really love Vouch Proxy! I wish it did XXXX...
Please make a proposal before you spend your time and our time integrating a new feature.
Code contributions should..
- include unit tests and in some cases end-to-end tests
- be formatted with
go fmt, checked withgo vetand other common go tools - not break existing setups without a clear reason (usually security related)
- and generally be discussed beforehand in a GitHub issue
For larger contributions or code related to a platform that we don't currently support we will ask you to commit to supporting the feature for an agreed upon period. Invariably someone will pop up here with a question and we want to be able to support these requests.
OpenResty® is a full-fledged web platform that integrates the standard Nginx core, LuaJIT, many carefully written Lua libraries, lots of high quality 3rd-party Nginx modules, and most of their external dependencies.
You can replace nginx with OpenResty fairly easily.
With OpenResty and Lua it is possible to provide customized and advanced authorization on any header or claims vouch passes down.
OpenResty and configs for a variety of scenarios are available in the examples directory.
-
Bob visits
https://private.oursites.com -
the Nginx reverse proxy...
- recieves the request for private.oursites.com from Bob
- uses the
auth_requestmodule configured for the/validatepath /validateis configured toproxy_passrequests to the authentication service athttps://vouch.oursites.com/validate- if
/validatereturns...- 200 OK then SUCCESS allow Bob through
- 401 NotAuthorized then
- respond to Bob with a 302 redirect to
https://vouch.oursites.com/login?url=https://private.oursites.com
- respond to Bob with a 302 redirect to
- if
-
vouch
https://vouch.oursites.com/validate- recieves the request for private.oursites.com from Bob via Nginx
proxy_pass - it looks for a cookie named "oursitesSSO" that contains a JWT
- if the cookie is found, and the JWT is valid
- returns 200 to Nginx, which will allow access (bob notices nothing)
- if the cookie is NOT found, or the JWT is NOT valid
- return 401 NotAuthorized to Nginx (which forwards the request on to login)
- recieves the request for private.oursites.com from Bob via Nginx
-
Bob is first forwarded briefly to
https://vouch.oursites.com/login?url=https://private.oursites.com- clears out the cookie named "oursitesSSO" if it exists
- generates a nonce and stores it in session variable $STATE
- stores the url
https://private.oursites.comfrom the query string in session variable $requestedURL - respond to Bob with a 302 redirect to Google's OAuth Login form, including the $STATE nonce
-
Bob logs into his Google account using Oauth
- after successful login
- Google responds to Bob with a 302 redirect to
https://vouch.oursites.com/auth?state=$STATE
-
Bob is forwarded to
https://vouch.oursites.com/auth?state=$STATE- if the $STATE nonce from the url matches the session variable "state"
- make a "third leg" request of google (server to server) to exchange the OAuth code for Bob's user info including email address [email protected]
- if the email address matches the domain oursites.com (it does)
- issue bob a JWT in the form of a cookie named "oursitesSSO"
- retrieve the session variable $requestedURL and 302 redirect bob back to $requestedURL
Note that outside of some innocuos redirection, Bob only ever sees https://private.oursites.com and the Google Login screen in his browser. While Vouch does interact with Bob's browser several times, it is just to set cookies, and if the 302 redirects work properly Bob will log in quickly.
Once the JWT is set, Bob will be authorized for all other sites which are configured to use https://vouch.oursites.com/validate from the auth_request Nginx module.
The next time Bob is forwarded to google for login, since he has already authorized the Vouch OAuth app, Google immediately forwards him back and sets the cookie and sends him on his merry way. Bob may not even notice that he logged in via Vouch.