A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others) to validate accounts by email, domain or group.


Download Prebuilt Binary (current release is v2.2) or build with $ go get github.com/bitly/oauth2_proxy which will put the binary in $GOROOT/bin Prebuilt binaries can be validated by extracting the file and verifying it against the sha256sum.txt checksum file provided for each release starting with version v2.3.

  • sha256sum -c sha256sum.txt 2>&1 | grep OK
  • oauth2_proxy-2.3.linux-amd64: OK
  • Select a Provider and Register an OAuth Application with a Provider
  • Configure OAuth2 Proxy using config file, command line options, or environment variables
  • Configure SSL or Deploy behind a SSL endpoint (example provided for Nginx)

OAuth Provider Configuration

You will need to register an OAuth application with a Provider (Google, GitHub or another provider), and configure it with Redirect URI(s) for the domain you intend to run oauth2_proxy on.

Valid providers are :

  • Google default
  • Azure
  • Facebook
  • GitHub
  • GitLab
  • LinkedIn

The provider can be selected using the provider configuration value.

Google Auth Provider

For Google, the registration steps are:

  • Create a new project: https://console.developers.google.com/project
  • Choose the new project from the top right project dropdown (only if another project is selected)
  • In the project Dashboard center pane, choose “API Manager”
  • In the left Nav pane, choose “Credentials”
  • In the center pane, choose “OAuth consent screen” tab. Fill in “Product name shown to users” and hit save.
  • In the center pane, choose “Credentials” tab.
  • Open the “New credentials” drop down
  • Choose “OAuth client ID”
  • Choose “Web application”
  • Application name is freeform, choose something appropriate
  • Authorized JavaScript origins is your domain ex: https://internal.yourcompany.com
  • Authorized redirect URIs is the location of oauth2/callback ex: https://internal.yourcompany.com/oauth2/callback
  • Choose “Create”
  • Take note of the Client ID and Client Secret
  • It’s recommended to refresh sessions on a short interval (1h) with cookie-refresh setting which validates that the account is still authorized.
  • Restrict auth to specific Google groups on your domain. (optional)
  • Create a service account: https://developers.google.com/identity/protocols/OAuth2ServiceAccount and make sure to download the json file.
  • Make note of the Client ID for a future step.
  • Under “APIs & Auth”, choose APIs.
  • Click on Admin SDK and then Enable API.

Follow the steps on https://developers.google.com/admin-sdk/directory/v1/guides/delegation#delegate_domain-wide_authority_to_your_service_account and give the client id from step 2 the following oauth scopes:

  • https://www.googleapis.com/auth/admin.directory.group.readonly
  • https://www.googleapis.com/auth/admin.directory.user.readonly

Follow the steps on https://support.google.com/a/answer/60757 to enable Admin API access.

  • Create or choose an existing administrative email address on the Gmail domain to assign to the google-admin-email flag. This email will be impersonated by this client to make calls to the Admin SDK. See the note on the link from step 5 for the reason why.
  • Create or choose an existing email group and set that email to the google-group flag. You can pass multiple instances of this flag with different groups and the user will be checked against all the provided groups.
  • Lock down the permissions on the json file downloaded from step 1 so only oauth2_proxy is able to read the file and set the path to the file in the google-service-account-json flag.
  • Restart oauth2_proxy.

Note: The user is checked against the group members list on initial authentication and every time the token is refreshed ( about once an hour ).

Azure Auth Provider

  • Add an application to your Azure Active Directory tenant.
  • On the App properties page provide the correct Sign-On URL ie https://internal.yourcompany.com/oauth2/callback
  • If applicable take note of your TenantID and provide it via the –azure-tenant=<YOUR TENANT ID> commandline option. Default the common tenant is used.
  • The Azure AD auth provider uses openid as it default scope. It uses https://graph.windows.net as a default protected resource. It call to https://graph.windows.net/me to get the email address of the user that logs in.

Facebook Auth Provider

  • Create a new FB App from https://developers.facebook.com/
  • Under FB Login, set your Valid OAuth redirect URIs to https://internal.yourcompany.com/oauth2/callback

GitHub Auth Provider

  • Create a new project: https://github.com/settings/developers
  • Under Authorization callback URL enter the correct url ie https://internal.yourcompany.com/oauth2/callback
  • The GitHub auth provider supports two additional parameters to restrict authentication to Organization or Team level access. Restricting by org and team is normally accompanied with –email-domain=*
  • -github-org=””: restrict logins to members of this organisation
  • -github-team=””: restrict logins to members of any of these teams (slug), separated by a comma
  • If you are using GitHub enterprise, make sure you set the following to the appropriate url:
  • -login-url=”http(s)://<enterprise github host>/login/oauth/authorize”
  • -redeem-url=”http(s)://<enterprise github host>/login/oauth/access_token”
  • -validate-url=”http(s)://<enterprise github host>/api/v3″

GitLab Auth Provider

Whether you are using GitLab.com or self-hosting GitLab, follow these steps to add an application

If you are using self-hosted GitLab, make sure you set the following to the appropriate URL:

  • -login-url=”<your gitlab url>/oauth/authorize”
  • -redeem-url=”<your gitlab url>/oauth/token”
  • -validate-url=”<your gitlab url>/api/v4/user”

LinkedIn Auth Provider

For LinkedIn, the registration steps are:

  • Create a new project: https://www.linkedin.com/secure/developer
  • In the OAuth User Agreement section:
  • In default scope, select r_basicprofile and r_emailaddress
    In “OAuth 2.0 Redirect URLs”, enter https://internal.yourcompany.com/oauth2/callback
  • Fill in the remaining required fields and Save.
  • Take note of the Consumer Key / API Key and Consumer Secret / Secret Key

Microsoft Azure AD Provider

For adding an application to the Microsoft Azure AD follow these steps to add an application.

  • Take note of your TenantId if applicable for your situation. The TenantId can be used to override the default common authorization server with a tenant specific server.
  • OpenID Connect Provider
  • OpenID Connect is a spec for OAUTH 2.0 + identity that is implemented by many major providers and several open source projects. This provider was originally built against CoreOS Dex and we will use it as an example.
  • Launch a Dex instance using the getting started guide.
  • Setup oauth2_proxy with the correct provider and using the default ports and callbacks.

Login with the fixture use in the dex guide and run the oauth2_proxy with the following args:

  • -provider oidc -client-id oauth2_proxy -client-secret proxy -redirect-url -oidc-issuer-url -cookie-secure=false -email-domain example.com

Email Authentication

To authorize by email domain use –email-domain=yourcompany.com. To authorize individual email addresses use –authenticated-emails-file=/path/to/file with one email per line. To authorize all email addresses use –email-domain=*.

Tell us about a new Kubernetes application


Never miss a thing! Sign up for our newsletter to stay updated.


Discover and learn about everything Kubernetes