heroku-buildpack-oauth2-proxy

This buildpack adds authentication against an OAuth2 provider such as GitHub or Google to your Heroku application.

Authentication is provided by putting pusher/oauth2_proxy in front of your application as a reverse proxy, allowing you to authenticate users using OAuth2 without actually implementing OAuth2 in your applications codebase.

One usecase is to ensure only users from your organization will be able to access static files served with Heroku.

The following section guides you through the process of creating such a setup using heroku-buildpack-static and this buildpack.

If you'd rather use this buildpack to secure a different application, it might still be useful to walk through this example once to get familiar with the setup procedure. However, you might also skip ahead to the usage section.

Getting Started

First, clone the example branch and switch into it:

git clone https://github.com/cfra/heroku-buildpack-oauth2-proxy -b example-static oauth2-example
cd oauth2-example

Then, create a new Heroku application and set the buildpacks:

heroku create
heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git
heroku buildpacks:add cfra/oauth2-proxy

You need an account for the proxy so that it can interface with your OAuth2 provider. For this example, we will be using GitHub as OAuth2 provider.

Create a new OAuth2 app in the GitHub developer settings. Ensure that the "Authorization callback URL" is set correctly. For example, if you are using herokuapp.com and your application is called ancient-woodland-33672, you should set the callback URL to: https://ancient-woodland-33672.herokuapp.com/oauth2/callback.

After having created the OAuth2 app successfully, you will be shown a Client ID and a Client Secret, which you need to configure on the Heroku app:

heroku config:set OAUTH2_PROXY_CLIENT_ID=0123456789abcdef1234
heroku config:set OAUTH2_PROXY_CLIENT_SECRET=0123456789abcdef0123456789abcdef01234567

Furthermore, you need to specify that GitHub should be used as authentication provider and provide a secret key for encrypting the session cookies:

heroku config:set OAUTH2_PROXY_PROVIDER=github
heroku config:set OAUTH2_PROXY_COOKIE_SECRET=$(python -c \
    'from secrets import token_urlsafe; print(token_urlsafe(32)[:32])' \
)

Now, you are all set and can start the first deployment of your example application:

git push heroku HEAD:master

You will see the buildlog for your application, followed by a message about successful deployment.

After this, navigate to your application:

heroku apps:open

You will be prompted to log-in with GitHub.

After successful authentication, GitHub will redirect you back to your application and a success page will be shown.

For futher steps, you might want to have a look in the configuration Section to learn about configuration options for finer grained authentication, e.g. allowing only members of a particular GitHub organization.

Usage With Other Applications

For using this buildpack with your application, you need to do two things:

On the one hand, you need to set up the configuration for oauth2_proxy. The getting started section describes this process for GitHub. For other providers, a look at the configuration Section and at the OAuth2 Provider Configuration documentation of oauth2_proxy will provide you with the necessary information.

On the other hand, you need to ensure that oauth2_proxy is run as a reverse proxy in front of your actual application worker.

For that purpose, this buildpack installs a script start_with_oauth2_proxy.sh. This script can be used as the web process and will pass any requests to the backend process specified as its arguments.

For example, the heroku-buildpack-static has /app/bin/boot as entrypoint. Given that, a usable Procfile to run it with the proxy looks as following:

web: /app/bin/start_with_oauth2_proxy.sh /app/bin/boot

This will take care to start both /app/bin/boot and oauth2_proxy and to route any incoming requests correctly.

Configuration

The following environment variables are required:

• OAUTH2_PROXY_PROVIDER: The provider to use. Something like github, google or facebook
• OAUTH2_PROXY_CLIENT_ID: The OAuth2 client id (generated by OAuth2 provider)
• OAUTH2_PROXY_CLIENT_SECRET: The OAuth2 client secret (generated by OAuth2 provider)
• OAUTH2_PROXY_COOKIE_SECRET: Secret key to encrypt oauth2_proxy's session cookies. This string needs to be 32 characters long.

Optionally, you can provide the following:

• OAUTH2_GITHUB_ORG: Only allow login for members of the given GitHub organization
• OAUTH2_EMAIL_DOMAIN: Only allow login for users with emails from this domain

Contributing

Should you encounter any issues while using this buildpack or discover any bugs, I would be glad if you file an issue with this GitHub project.

Also, the current configuration options are quite limited and specific to GitHub. If you need support for configuration of other authentication providers, feel free to open a pull request or file an enhancement proposal.