Sign inSign up

voucher/vouch-proxy

By voucher

•Updated 9 months ago

We've moved to https://quay.io/repository/vouch/vouch-proxy soon `arm` will be moved there

Image
11

10M+

voucher/vouch-proxy repository overview

⁠Vouch Proxy

GitHub stars Go Report Card MIT license Docker pulls GitHub version

An SSO solution for Nginx using the auth_request⁠ module. Vouch Proxy can protect all of your websites at once.

Vouch Proxy supports many OAuth and OIDC login providers and can enforce authentication to...

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

⁠Table of Contents

⁠What Vouch Proxy Does...

Vouch Proxy (VP) forces visitors to login and authenticate with an IdP⁠ (such as one of the services listed above) before allowing them access to a website.

Vouch Proxy protects websites

VP can also be used as a Single Sign On (SSO) solution to protect all web applications in the same domain.

Vouch Proxy is a Single Sign On solution

After a visitor logs in Vouch Proxy allows access to the protected websites for several hours. Every request is checked by VP to ensure that it is valid.

VP can send the visitor's email, name and other information which the IdP provides (including access tokens) to the web application as HTTP headers. VP can be used to replace application user management entirely.

⁠Installation and Configuration

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 /auth endpoint
  • configure Nginx...

The following Nginx config assumes..

  • Nginx, vouch.yourdomain.com and protectedapp.yourdomain.com are running on the same server
  • both domains are served as https and have valid certs (if not, change to listen 80 and set vouch.cookie.secure⁠ to 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;

    # 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.

⁠Configuring Vouch Proxy using Environmental Variables

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-proxy

Environmental 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.

⁠More advanced configurations

All Vouch Proxy configuration items are documented in config/config.yml_example⁠

Please do help us to expand this list.

⁠Scopes and Claims

With Vouch Proxy you can request various scopes (standard and custom) to obtain more information about the user or gain access to the provider's APIs. Internally, Vouch Proxy launches a requests to user_info_url after successful authentication. From the provider's response the required claims are extracted and stored in the vouch cookie.

⚠️ Additional claims and tokens will be added to the VP cookie and can make it large

The VP cookie may get split up into several cookies, but if you need it, you need it. Large cookies and headers require Nginx to be configured with larger buffers. See large_client_header_buffers⁠ and proxy_buffer_size⁠ for more information.

⁠Setup scopes and claims in Vouch Proxy with Nginx

  1. Configure Vouch Proxy for Nginx and your IdP as normal (See: Installation and Configuration⁠)

  2. Set the necessary scopes in the oauth section of the vouch-proxy config.yml (example config⁠)

    1. set idtoken: X-Vouch-IdP-IdToken in the headers section of vouch-proxy's config.yml
    2. log in and call the /validate endpoint in a modern browser
    3. check the response header for a X-Vouch-IdP-IdToken header
    4. copy the value of the header into the debugger at https://jwt.io/⁠ and ensure that the necessary claims are part of the jwt
    5. if they are not, you need to adjust the scopes in the oauth section of your config.yml or reconfigure your oauth provider

  3. Set the necessary claims in the header section of the vouch-proxy config.yml

    1. log in and call the /validate endpoint in a modern browser
    2. check the response headers for headers of the form X-Vouch-Idp-Claims-<ClaimName>
    3. If they are not there clear your cookies and cached browser data
    4. 🐞 If they are still not there but exist in the jwt (esp. custom claims) there might be a bug
    5. remove the idtoken: X-Vouch-IdP-IdToken from the headers section of vouch-proxy's config.yml if you don't need it

  4. Use auth_request_set after auth_request inside the protected location in the nginx server.conf⁠

  5. Consume the claim (example nginx config⁠)

⁠Running from Docker

docker run -d \
    -p 9090:9090 \
    --name vouch-proxy \
    -v ${PWD}/config:/config \
    voucher/vouch-proxy

or

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-proxy

Automated container builds for each Vouch Proxy release are available from Docker Hub⁠. Each release produces..

  • voucher/vouch-proxy:latest
  • voucher/vouch-proxy:x.y.z
  • voucher/vouch-proxy:alpine
  • voucher/vouch-proxy:alpine-x.y.z
  • voucher/vouch-proxy:latest-arm

⁠Kubernetes Nginx Ingress

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/⁠

⁠Compiling from source and running the binary

  ./do.sh goget
  ./do.sh build
  ./vouch-proxy

⁠/login and /logout endpoint redirection

As of v0.11.0 additional checks are in place to reduce the attack surface of url redirection⁠.

⁠/login?url=POST_LOGIN_URL

The passed URL...

  • must start with either http or https
  • must have a domain overlap with either a domain in the vouch.domains list or the vouch.cookie.domain (if either of those are configured)
  • cannot have a parameter which includes a URL to prevent URL chaining attacks⁠
⁠/logout?url=NEXT_URL

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/revoke

this 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/login

Note that your IdP will likely carry their own, separate post_logout_redirect_uri list.

logout resources..

⁠Troubleshooting, Support and Feature Requests (Read this before submitting an issue at GitHub)

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..

⁠I'm getting an infinite redirect loop which returns me to my IdP (Google/Okta/GitHub/...)

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.com

If 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, the oauth.callback_url and the configured vouch.domains must 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.com and siteB.yourdomain.com protected by Vouch Proxy, you want the Vouch Proxy cookie to be set into .yourdomain.com
    • if you authenticate to vouch.yourdomain.com the cookie will not be able to be seen by dev.anythingelse.com
    • unless you are using https, you should set vouch.cookie.secure: false
    • cookies are available to all ports of a domain

  • please see the issues which have been closed that mention redirect⁠

⁠Okay, I looked at the issues and have tried some things with my configs but it's still not working

Please submit a new issue⁠ in the following fashion..

TLDR:

  • set vouch.testing: true
  • set vouch.logLevel: debug
  • conduct a full round trip of ./vouch-proxy capturing the output..
    • VP startup
    • /validate
    • /login - even if the error is here
    • /auth
    • /validate - capture everything
  • put all your logs and config in a gist.
  • ./do.sh bug_report is your friend
⁠But read this anyways because we'll ask you to read it if you don't follow these instruction. :)
  • turn on vouch.testing: true and set vouch.logLevel: debug.
  • use a gist⁠ or another paste service such as hasteb.in⁠. 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 secretdomain.com secretpass [anothersecret..] which will create a redacted version of your config and logs removing each of those strings
    • and follow the instructions at the end to redact your Nginx config
  • all of those go into a gist⁠
  • then open a new issue⁠ in this repository
  • or visit our IRC channel #vouch⁠ on libera.chat

A bug report can be generated from a docker environment using the voucher/vouch-proxy:alpine image...

docker run --name vouch_proxy -v $PWD/config:/config -v $PWD/certs:/certs -it --rm --entrypoint /do.sh voucher/vouch-proxy:alpine bug_report yourdomain.com anotherdomain.com someothersecret
⁠submitting a Pull Request for a new feature

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 with go vet and 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.

⁠Advanced Authorization Using OpenResty

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.

⁠The flow of login and authentication using Google Oauth

  • Bob visits https://private.oursites.com

  • the Nginx reverse proxy...

Tag summary

Content type

Image

Digest

sha256:a0f7638af…

Size

7.6 MB

Last updated

9 months ago

docker pull voucher/vouch-proxy:latest-arm