Merge branch 'master' into pr/rhansen/310

Author: bnfinet

.defaults.yml

@@ -15,6 +15,11 @@ vouch:
   # whiteList:
   # teamWhitelist:
 
+  tls:
+    # cert:
+    # key:
+    profile: intermediate
+
   jwt:
     #   secret:
     issuer: Vouch

.dockerignore

@@ -11,3 +11,5 @@ config/config.yml_orig
 .dockerignore
 Dockerfile
 handlers/rice-box.go
+certs
+.cover/*

.gitignore

@@ -9,6 +9,8 @@ config/secret
 !config/testing/*
 pkg/model/storage-test.db
 .vscode/*
+certs/*
 coverage.out
 coverage.html.env_google
 .env*
+.cover

.whitesource

@@ -0,0 +1,12 @@
+{
+  "scanSettings": {
+    "baseBranches": []
+  },
+  "checkRunSettings": {
+    "vulnerableCheckRunConclusionLevel": "failure",
+    "displayMode": "diff"
+  },
+  "issueSettings": {
+    "minSeverityLevel": "LOW"
+  }
+}

Dockerfile

@@ -20,8 +20,8 @@ RUN ./do.sh install
 FROM scratch
 LABEL maintainer="vouch@bnf.net"
 COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
-COPY templates/ templates/
-COPY .defaults.yml .defaults.yml 
+COPY templates /templates
+COPY .defaults.yml /.defaults.yml 
 # see note for /static in main.go
 COPY static /static
 COPY --from=builder /go/bin/vouch-proxy /vouch-proxy

Dockerfile.alpine

@@ -9,22 +9,23 @@ WORKDIR ${GOPATH}/src/github.com/vouch/vouch-proxy
 
 COPY . .
 
-# RUN go-wrapper download  # "go get -d -v ./..."
-# RUN ./do.sh build    # see `do.sh` for vouch build details
-# RUN go-wrapper install # "go install -v ./..."
-
 RUN ./do.sh goget
 RUN ./do.sh gobuildstatic # see `do.sh` for vouch-proxy build details
 RUN ./do.sh install
 
 FROM alpine:latest
 LABEL maintainer="vouch@bnf.net"
+ENV VOUCH_ROOT=/
 COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
-COPY templates/ templates/
-COPY .defaults.yml .defaults.yml 
+COPY templates /templates
+COPY .defaults.yml /.defaults.yml 
 # see note for /static in main.go
 COPY static /static
+
+#  do.sh requires bash
+RUN apk add --no-cache bash
 COPY do.sh /do.sh
+
 COPY --from=builder /go/bin/vouch-proxy /vouch-proxy
 EXPOSE 9090
 ENTRYPOINT ["/vouch-proxy"]

README.md

@@ -8,7 +8,7 @@
 
 An SSO solution for Nginx using the [auth_request](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) module. Vouch Proxy can protect all of your websites at once.
 
-Vouch Proxy supports many OAuth login providers and can enforce authentication to...
+Vouch Proxy supports many OAuth and OIDC login providers and can enforce authentication to...
 
 - Google
 - [GitHub](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/about-authorization-options-for-oauth-apps/)
@@ -30,6 +30,29 @@ Please do let us know when you have deployed Vouch Proxy with your preffered IdP
 
 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...](#what-vouch-proxy-does)
+- [Installation and Configuration](#installation-and-configuration)
+- [Configuring Vouch Proxy using Environmental Variables](#configuring-vouch-proxy-using-environmental-variables)
+- [More advanced configurations](#more-advanced-configurations)
+  - [Scopes and Claims](#scopes-and-claims)
+- [Running from Docker](#running-from-docker)
+- [Kubernetes Nginx Ingress](#kubernetes-nginx-ingress)
+- [Compiling from source and running the binary](#compiling-from-source-and-running-the-binary)
+- [/login and /logout endpoint redirection](#-login-and--logout-endpoint-redirection)
+- [Troubleshooting, Support and Feature Requests](#troubleshooting--support-and-feature-requests--read-this-before-submitting-an-issue-at-github-)
+  (Read this before submitting an issue at GitHub)
+  - [I'm getting an infinite redirect loop which returns me to my IdP (Google/Okta/GitHub/...)](#i-m-getting-an-infinite-redirect-loop-which-returns-me-to-my-idp--google-okta-github--)
+  - [Okay, I looked at the issues and have tried some things with my configs but it's still not working](#okay--i-looked-at-the-issues-and-have-tried-some-things-with-my-configs-but-it-s-still-not-working)
+  - [submitting a Pull Request for a new feature](#submitting-a-pull-request-for-a-new-feature)
+- [Advanced Authorization Using OpenResty](#advanced-authorization-using-openresty)
+- [The flow of login and authentication using Google Oauth](#the-flow-of-login-and-authentication-using-google-oauth)
+
+---
+
 ## What Vouch Proxy Does...
 
 Vouch Proxy (VP) forces visitors to login and authenticate with an [IdP](https://en.wikipedia.org/wiki/Identity_provider) (such as one of the services listed above) before allowing them access to a website.
@@ -173,17 +196,45 @@ The variable `VOUCH_CONFIG` can be used to set an alternate location for the con
 
 ## More advanced configurations
 
+All Vouch Proxy configuration items are documented in [config/config.yml_example](https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example)
+
 - [cacheing of the Vouch Proxy validation response in Nginx](https://github.com/vouch/vouch-proxy/issues/76#issuecomment-464028743)
 - [handleing `OPTIONS` requests when protecting an API with Vouch Proxy](https://github.com/vouch/vouch-proxy/issues/216)
 - [validation by GitHub Team or GitHub Org](https://github.com/vouch/vouch-proxy/pull/205)
 - [running on a Raspberry Pi using the ARM based Docker image](https://github.com/vouch/vouch-proxy/pull/247)
 - [Kubernetes architecture post ingress](https://github.com/vouch/vouch-proxy/pull/263#issuecomment-628297832)
 - [set `HTTP_PROXY` to relay Vouch Proxy IdP requests through an outbound proxy server](https://github.com/vouch/vouch-proxy/issues/291)
 - [Reverse Proxy for Google Cloud Run Services](https://github.com/karthikv2k/oauth_reverse_proxy)
+- [Enable native TLS in Vouch Proxy](https://github.com/vouch/vouch-proxy/pull/332#issue-522612010)
 
 Please do help us to expand this list.
 
-All Vouch Proxy configuration items are documented in [config/config.yml_example](https://github.com/vouch/vouch-proxy/blob/master/config/config.yml_example)
+### 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](http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers) and [proxy_buffer_size](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) for more information.
+
+#### Setup `scopes` and `claims` in Vouch Proxy with Nginx
+
+0. Configure Vouch Proxy for Nginx and your IdP as normal (See: [Installation and Configuration](#installation-and-configuration))
+
+1. Set the necessary `scope`s in the `oauth` section of the vouch-proxy `config.yml` ([example config](config/config.yml_example_scopes_and_claims))
+   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
+2. 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
+3. Use `auth_request_set` after `auth_request` inside the protected location in the nginx [`server.conf`](examples/nginx/nginx_scopes_and_claims.conf)
+4. Consume the claim ([example nginx config](examples/nginx/nginx_scopes_and_claims.conf))
 
 ## Running from Docker
 
@@ -219,7 +270,7 @@ Automated container builds for each Vouch Proxy release are available from [Dock
 
 ## Kubernetes Nginx Ingress
 
-If you are using kubernetes with [nginx-ingress](https://github.com/kubernetes/ingress-nginx), you can configure your ingress with the following annotations (note quoting the auth-signin annotation):
+If you are using kubernetes with [nginx-ingress](https://github.com/kubernetes/ingress-nginx), you can configure your ingress with the following annotations (note quoting the `auth-signin` annotation):
 
 ```bash
     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"
@@ -244,7 +295,7 @@ Helm Charts are maintained by [halkeye](https://github.com/halkeye) and are avai
 
 ## /login and /logout endpoint redirection
 
-As of `v0.11.0` we have put additional checks in place to reduce [the attack surface of url redirection](https://blog.detectify.com/2019/05/16/the-real-impact-of-an-open-redirect/).
+As of `v0.11.0` additional checks are in place to reduce [the attack surface of url redirection](https://blog.detectify.com/2019/05/16/the-real-impact-of-an-open-redirect/).
 
 ### /login?url=POST_LOGIN_URL
 
@@ -320,14 +371,35 @@ If you continue to have trouble, try the following:
 
 Please [submit a new issue](https://github.com/vouch/vouch-proxy/issues) 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 [hasteb.in](https://hasteb.in/), or another **paste service** or a [gist](https://gist.github.com/) 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
+- use a [gist](https://gist.github.com/) or another **paste service** such as [hasteb.in](https://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 [hasteb.in](https://hasteb.in/) or a [gist](https://gist.github.com/)
+- all of those go into a [gist](https://gist.github.com/)
 - then [open a new issue](https://github.com/vouch/vouch-proxy/issues/new) in this repository
 - or visit our IRC channel [#vouch](irc://freenode.net/#vouch) on freenode
 
+A bug report can be generated from a docker environment using the `voucher/vouch-proxy:alpine` image...
+
+```!bash
+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...
@@ -366,21 +438,21 @@ OpenResty and configs for a variety of scenarios are available in the [examples]
       - 401 NotAuthorized then
         - respond to Bob with a 302 redirect to `https://vouch.oursites.com/login?url=https://private.oursites.com`
 
-- vouch `https://vouch.oursites.com/validate`
+- Vouch Proxy `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
+  - 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)
+    - returns `200 OK` 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)
+    - return `401 NotAuthorized` to Nginx (which forwards the request on to login)
 
 - 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.com` from the query string in session variable \$requestedURL
-  - respond to Bob with a 302 redirect to Google's OAuth Login form, including the \$STATE nonce
+  - stores the url `https://private.oursites.com` from 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
 
@@ -389,13 +461,13 @@ OpenResty and configs for a variety of scenarios are available in the [examples]
 
 - 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 bob@oursites.com
+  - make a "third leg" request of Google (server to server) to exchange the OAuth code for Bob's user info including email address bob@oursites.com
   - 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
+    - retrieve the session variable `$requestedURL` and 302 redirect bob back to `https://private.oursites.com`
 
 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.
+The next time Bob is forwarded to google for login, since he has already authorized the Vouch Proxy OAuth app, Google immediately forwards him back and sets the cookie and sends him on his merry way. In some browsers such as Chrome, Bob may not even notice that he logged in using Vouch Proxy.

config/config.yml_example

@@ -57,6 +57,12 @@ vouch:
   # - myOrg
   # - myOrg/myTeam
 
+  tls:
+    # cert: /path/to/signed_cert_plus_intermediates # VOUCH_TLS_CERT
+    # key: /path/to/private_key                     # VOUCH_TLS_KEY
+    # profile - defines the TLS configuration profile (modern, intermediate, old, default)
+    profile: intermediate                           # VOUCH_TLS_PROFILE
+
   jwt:
     # secret - VOUCH_JWT_SECRET
     # a random string used to cryptographically sign the jwt
@@ -88,8 +94,10 @@ vouch:
 
     # httpOnly: true # VOUCH_COOKIE_HTTPONLY
 
-    # Set cookie maxAge to 0 to delete the cookie every time the browser is closed. - VOUCH_COOKIE_MAXAGE
-    maxAge: 14400
+    # Number of minutes until session cookie expires - VOUCH_COOKIE_MAXAGE
+    # Set cookie maxAge to 0 to delete the cookie every time the browser is closed.
+    # Must not be longer than jwt.maxAge
+    maxAge: 240
 
     # Set SameSite attribute to restrict browser behaviour wrt sending the cookie along with cross-site requests. - VOUCH_COOKIE_SAMESITE
     # Possible attribute values lax, strict, none.

config/config.yml_example_scopes_and_claims

@@ -0,0 +1,23 @@
+vouch:
+  # .... domain configuration goes here
+
+  headers:   
+    # The idtoken is used for debugging during configuration
+    # use the idtoken to make sure the oauth provider returns the necessary claims
+    idtoken: X-Vouch-IdP-IdToken
+
+    # make sure to list all the claims you need
+    # Note: they will be stored in the cookie AND header and get sent with each request
+    claims:
+      - sub
+      - name
+      - email
+      - email_verified
+
+oauth:
+  # .... your provider config goes here
+  scopes:
+    # make sure to set the required scopes
+    - openid
+    - email
+    - profile

do.sh

@@ -7,7 +7,9 @@ SCRIPT=$(readlink -f "$0")
 SDIR=$(dirname "$SCRIPT")
 cd $SDIR
 
-export VOUCH_ROOT=${GOPATH}/src/github.com/vouch/vouch-proxy/
+if [ -z "$VOUCH_ROOT" ]; then
+  export VOUCH_ROOT=${GOPATH}/src/github.com/vouch/vouch-proxy/
+fi
 
 IMAGE=voucher/vouch-proxy:latest
 ALPINE=voucher/vouch-proxy:alpine
@@ -119,13 +121,13 @@ EOF
   trap _redact_exit SIGINT
   ./vouch-proxy 2>&1 | _redact
 
-
 }
+
 _redact_exit () {
   echo -e "\n\n-------------------------\n"
   echo -e "redact your nginx config with:\n"
   echo -e "\tcat nginx.conf | sed 's/yourdomain.com/DOMAIN.COM/g'\n"
-  echo -e "Please upload both configs and some logs to https://hastebin.com/ and open an issue on GitHub at https://github.com/vouch/vouch-proxy/issues\n"
+  echo -e "Please upload configs and logs to a gist and open an issue on GitHub at https://github.com/vouch/vouch-proxy/issues\n"
 }
 
 _redact() {
@@ -318,6 +320,17 @@ gosec() {
   # segfault's without exec since it would just call this function infinitely :)
   exec gosec ./...
 }
+
+selfcert() {
+  # https://stackoverflow.com/questions/63588254/how-to-set-up-an-https-server-with-a-self-signed-certificate-in-golang
+  set -e
+  mkdir -p $SDIR/certs
+  # openssl genrsa -out $SDIR/certs/server.key 2048
+  openssl ecparam -genkey -name secp384r1 -out $SDIR/certs/server.key
+  openssl req -new -x509 -sha256 -key $SDIR/certs/server.key -out $SDIR/certs/server.crt -days 3650
+  echo -e "created self signed certs in '$SDIR/certs'\n"  
+}
+
 usage() {
    cat <<EOF
    usage:
@@ -327,6 +340,7 @@ usage() {
      $0 goget                  - get all dependencies
      $0 gofmt                  - gofmt the entire code base
      $0 gosec                  - gosec security audit of the entire code base
+     $0 selfcert               - calls openssl to create a self signed key and cert
      $0 dbuild                 - build docker container
      $0 drun [args]            - run docker container
      $0 dbuildalpine           - build docker container for alpine
@@ -360,6 +374,7 @@ case "$ARG" in
    |'install' \
    |'test' \
    |'goget' \
+   |'selfcert' \
    |'gogo' \
    |'watch' \
    |'gobuildstatic' \