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.
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:
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:
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.
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
For example, the
/app/bin/boot as entrypoint. Given that,
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
oauth2_proxy and to route any incoming
The following environment variables are required:
OAUTH2_PROXY_PROVIDER: The provider to use. Something like
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
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.
Copy the snippet above into CLI.