Document Shortest Possible 😎 Path for Noobs

[johnboxall]

oauth2_proxy offers a number of configuration options.

For folks looking to get up and running, quickly, it would be awesome to add a 15 minute "Quickstart" guide.

This right place for this may be a separate repo containing the compiled binaries, and an app.json file to power a "Deploy to Heroku" button.

For others looking to get started quickly, here is how I typically do it using the Google Apps provider and an upstream application which requires a secret HTTP Basic Auth password to access:

1. Create a new repo.
2. Put the latest binaries from the releases pages into your repo.

3. Create an oauth2_proxy.cfg file. Here are the minimal options you'll need:

   # Restrict access to folks with this Google Apps domain.
   email_domains = ["$YOUR_GOOGLE_APPS_DOMAIN"]
   
   # Send the HTTP Basic Auth password `PASSWORD` to all upstreams for all users.
   basic_auth_password = "PASSWORD"
   pass_basic_auth = true
   
   # Rather than forwarding the `Host` header of the client to the upstream, use
   # the host defined in the upstream configuration.
   pass_host_header = false
   
   # The application that you're providing authentication for.
   upstreams = ["https://$YOUR_UPSTREAM_APP.herokuapp.com/"]

4. Create a Heroku app using the binary builtpack:

   heroku create oauth2_proxy_test
   heroku buildpacks:set https://github.com/ph3nx/heroku-binary-buildpack

5. Create a Procfile to run the binary with your config:

   web: bin/oauth2_proxy-2.0.1.linux-amd64.go1.5.1/oauth2_proxy -http-address="0.0.0.0:$PORT" -config='oauth2_proxy.cfg'

6. Follow the Google Auth Provider instructions. Set the required environment config variables on Heroku:

   heroku config:set \
      OAUTH2_PROXY_CLIENT_ID="..." \
      OAUTH2_PROXY_CLIENT_SECRET="..." \
      OAUTH2_PROXY_COOKIE_SECRET="$(cat /dev/urandom | env LC_CTYPE=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)"

7. Deploy your app to Heroku and rejoice.

For those looking to test locally using HTTP, make sure to toggle these settings:

• Set cookie_secure=false. This avoids responding with a secure cookie on HTTP, which the browser will discard.
• Set redirect_url="http://127.0.0.1.xip.io:4180/oauth2/callback". By default the server will attempt to set cookies on the same domain as the request – this will fail for localhost and 127.0.0.1 (as well as any IP based domain.

:heart:

[cpliakas]

@johnboxall Thanks for this. The cookie-secure tip and note about localhost / 127.0.0.1 unblocked me and saved what little hair I have left. One additional thing that I learned (which is really web 101 stuff) is that the domain must have at least one dot (.) in it otherwise the browser will reject it as an invalid domain and the cookie won't be set.

Without doing these things, the proxy keeps on redirecting to the sign-in page and the logs show Cookie "_oauth2_proxy" not present.

[johnboxall]

One quick way to get noobs up and running may be through a Deploy to Heroku button.

This PR #150 shows an example of how that might work.

[hulbert]

@johnboxall can you clarify the need for basic auth here? Is the case that you'd run two separate heroku apps?

[johnboxall]

@hulbert the upstream apps we're looking to add authentication to are available on the public internet.

Typically we protect them by using a shared secret over HTTP Basic Auth – this way you can't drive by access them on the web, but if you know the secret, you can still access them to check that they work.

We set them here, so that they are sent upstream by oauth2_proxy, causing the app to successfully respond.

Example:

https://private.example.com is available on the public internet and protected by basic auth.

https://x:secret@private.example.com allows you to access the app.

https://oauth2proxy.example.com/ is configured to provide authorization for private.example.com. For it to work, it needs to send x:secret upstream when making a request.