Skip to content
Get packs

Guide · Open source

How to use oauth2-proxy: setup, providers and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

OAuth2 Proxy is an open-source tool that makes visitors sign in with an identity provider before they can reach your web application. This guide explains what it does, what you need before starting, and how the pieces fit together. After reading it you will know whether OAuth2 Proxy fits your setup and where to find the detailed installation and configuration docs.

OAuth2 Proxyoauth2-proxy/oauth2-proxy · ★ 15.3k · MIT

Quick start

  1. 1Check prerequisites. Make sure you have an account with your identity provider and its OAuth2 or OIDC client credentials.
  2. 2Clone the repository. Run git clone on the oauth2-proxy repository to get the source.
  3. 3Read the installation docs. Follow the Installation Docs at oauth2-proxy.github.io/oauth2-proxy/installation to install and configure your setup.
  4. 4Try the example files. Review the example setup files in contrib/local-environment for a working starting point.
  5. 5Put it in front of your app. Run it as a standalone reverse proxy or as middleware in your existing proxy or load balancer.
  6. 6Pass user details upstream. Configure the provider so user details such as usernames and groups are forwarded as HTTP headers.

What OAuth2 Proxy does

OAuth2 Proxy sits in front of a web application. As a reverse proxy, it intercepts requests to your application and redirects users to an OAuth2 provider for authentication. As a middleware, it can be integrated into an existing reverse proxy or load balancer setup to handle authentication for multiple applications.

Through a generic OIDC client or specific provider implementations, it supports providers such as Google, Microsoft Entra ID, GitHub and login.gov, among others.

  • Standalone reverse proxy or middleware inside an existing proxy or load balancer
  • Sign-in with Google, Microsoft Entra ID, GitHub, login.gov or a generic OpenID Connect service
  • Forwards user details such as preferred usernames and groups to upstream apps as HTTP headers

What you need before you start

You need an account with an identity provider and OAuth2 or OIDC client credentials from that provider. The README does not list other system requirements, so check the installation docs for those details.

Get the source code

The README's install step is to clone the repository. Binaries are also published on GitHub for all major architectures, and the latest release is linked from the project's releases page.

git clone https://github.com/oauth2-proxy/oauth2-proxy

Configure and run it

The project's installation docs cover how to install and configure your setup. The repository also includes example setup files in contrib/local-environment that you can use as a starting point for a local test.

  • Read the Installation Docs at oauth2-proxy.github.io/oauth2-proxy/installation
  • Look at the example files in contrib/local-environment
  • Register your application with your identity provider to get client credentials

Choose an image if you run containers

From v7.6.0 onward the base image is distroless rather than Alpine, which the project says has fewer installed dependencies and is slightly smaller. Alpine-based images are still published for debugging and for cases such as armv6, with tags suffixed -alpine.

Nightly images built from the master branch are at quay.io/oauth2-proxy/oauth2-proxy-nightly. The project says these are unstable and should not be used in production unless you know what you are doing.

Keep it updated

The README includes a security notice that versions older than v6.0.0 should be upgraded, referencing an open redirect vulnerability. Report any security issue privately to the maintainers listed in MAINTAINERS.md rather than opening a public issue.

What people use it for

  • Adding a login screen to an internal web app that has no authentication of its own
  • Adding single sign-on with Google, Microsoft Entra ID or GitHub to an app behind an existing load balancer
  • Forwarding usernames or groups as HTTP headers so an upstream app can see who is signed in
  • Protecting several applications with one authentication layer in a middleware setup

Frequently asked questions

Is OAuth2 Proxy free?

OAuth2 Proxy is distributed under the MIT License, which is an open-source licence. You deploy and maintain it yourself, so your costs are your own hosting and operations.

What do I need to install OAuth2 Proxy?

You need an identity provider account and OAuth2 or OIDC client credentials. The README's install step is to clone the repository from GitHub, and the installation docs explain configuration.

Which identity providers does OAuth2 Proxy support?

It supports a generic OIDC client and specific implementations for Google, Microsoft Entra ID, GitHub, login.gov and others. Specific implementations can extract details such as usernames and groups.

Can OAuth2 Proxy handle authorization inside my app?

The README only describes authentication and passing user details along as HTTP headers. Fine-grained authorization logic inside the application is not described, so your app would need to handle that itself.

How does OAuth2 Proxy compare to Keycloak, Dex, Pomerium or Authelia?

Keycloak, Dex, Pomerium and Authelia are comparable projects in the same general space. The README does not compare them, so review each project's documentation against your needs before choosing.

Is there a hosted version of OAuth2 Proxy?

No. It is software you deploy and maintain yourself, so if you want a hosted login service with no servers to run, it is not the right fit.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OAuth2 Proxy suits teams who run a reverse proxy or load balancer, have internal web apps without login, and want self-hosted MIT-licensed single sign-on with providers like Google, Microsoft Entra ID or GitHub. If you want a hosted login service or fine-grained authorization inside your app, look at other options.

Install options & downloads