All apps · 0 apps

oauth2-proxy

Overview

Puts a login in front of web apps that have none of their own. Your reverse proxy asks this container, on every request, whether the visitor is signed in; if not, the visitor is sent to your identity provider (ZITADEL, Keycloak, Authentik, Authelia, Google, GitHub...) and only comes back once authenticated. Typical use: an Nginx Proxy Manager host with an "auth_request" block in its Advanced tab pointing here, so the app itself is never reachable without a login. One container can protect any number of sites: leave the redirect URL as a path only and it derives the right absolute URL from each request, and a shared cookie domain means one login covers all of them. Every setting below maps to an oauth2-proxy option of the same name. The four you must fill in are the issuer URL, the client ID and secret from your provider, and the cookie secret. The ready-to-paste reverse proxy snippet and a step-by-step walkthrough are in the repository README. IMPORTANT: this container is a gate, not a proxy. It is meant to be used with "Upstreams = static://202", letting your reverse proxy do the actual proxying. Anyone whose e-mail is in the allow-list file gets into everything behind the same instance, so use a separate instance for a different audience.

Readme

View on GitHub

OAuth2 Proxy

OAuth2 Proxy is a flexible, open-source tool that can act as either a standalone reverse proxy or a middleware component integrated into existing reverse proxy or load balancer setups. It provides a simple and secure way to protect your web applications with OAuth2 / OIDC authentication. 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 seamlessly integrated into your existing infrastructure to handle authentication for multiple applications.

OAuth2 Proxy supports a lot of OAuth2 as well as OIDC providers. Either through a generic OIDC client or a specific implementation for Google, Microsoft Entra ID, GitHub, login.gov and others. Through specialised provider implementations OAuth2 Proxy can extract more details about the user like preferred usernames and groups. Those details can then be forwarded as HTTP headers to your upstream applications.

Simplified Architecture

Get Started

OAuth2 Proxy's Installation Docs cover how to install and configure your setup. Additionally you can take a further look at the example setup files.

Releases

Binaries

We publish OAuth2 Proxy as compiled binaries on GitHub for all major architectures as well as more exotic ones like ppc64le as well as s390x.

Check out the latest release.

Images

From v7.6.0 and up the base image has been changed from Alpine to GoogleContainerTools/distroless. This image comes with even fewer installed dependencies and thus should improve security. The image therefore is also slightly smaller than Alpine. For debugging purposes (and those who really need it. e.g. armv6) we still provide images based on Alpine. The tags of these images are suffixed with -alpine.

Since 2023-11-18 we build nightly images directly from the master branch and provide them at quay.io/oauth2-proxy/oauth2-proxy-nightly. These images are considered unstable and therefore should NOT be used for production purposes unless you know what you're doing.

Former Sponsors

Microsoft

Microsoft Azure credits for open source projects

Getting Involved

Join the #oauth2-proxy Slack channel to chat with other users of OAuth2 Proxy or reach out to the maintainers directly. Use the public invite link to get an invite for the CNCF space.

OAuth2 Proxy is a community-driven project. We rely on the contribut️ions of our users to continually improve it. While review times can vary, we appreciate your patience and understanding. As a volunteer-driven project, we strive to keep this project stable and might take longer to merge changes.

If you want to contribute to the project. Please see our Contributing guide.

Thanks to all the people who already contributed ❤

Made with contrib.rocks.

Security

If you believe you have found a vulnerability within OAuth2 Proxy or any of its dependencies, please do NOT open an issue or PR on GitHub, please do NOT post any details publicly.

Security disclosures MUST be done in private. If you have found an issue that you would like to bring to the attention of the maintainers, please compose an email and send it to the list of people listed in our MAINTAINERS.md file.

For more details read our full Security Docs

Security Notice for v6.0.0 and older

If you are running a version older than v6.0.0 we strongly recommend to the current version.

See open redirect vulnerability for details.

Repository History

2018-11-27: This repository was forked from bitly/OAuth2_Proxy. Versions v3.0.0 and up are from this fork and will have diverged from any changes in the original fork. A list of changes can be seen in the CHANGELOG.

2020-03-29: This project was formerly hosted as pusher/oauth2_proxy but has been renamed to oauth2-proxy/oauth2-proxy. Going forward, all images shall be available at quay.io/oauth2-proxy/oauth2-proxy and binaries will be named oauth2-proxy.

Code of Conduct

Participation in the OAuth2 Proxy project is governed by the CNCF Code of Conduct.

License

OAuth2 Proxy is distributed under The MIT License.

Trademarks

OAuth2 Proxy is a Cloud Native Computing Foundation Sandbox project.

The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.

Related apps

Explore more like this

Explore all

Other apps Utilities apps

Links

Projectoauth2-proxy.github.io Supportforums.unraid.net Quayquay.io Templateraw.githubusercontent.com

Details

Repository

quay.io/oauth2-proxy/oauth2-proxy:latest

Registry

https://quay.io/repository/oauth2-proxy/oauth2-proxy

Last Updated2026-10-12

First Seen2020-09-04

Runtime arguments

Network: bridge
Shell: sh
Privileged: false
Extra Params: --restart unless-stopped

Template configuration

WebUI PortPorttcp

Port your reverse proxy will point at. Nothing else should be able to reach it.

Target: 4180
Default: 4180
Value: 4180

DataPathro

Folder holding the allow-list file. Mounted read-only on purpose.

Target: /data
Default: /mnt/user/appdata/oauth2-proxy
Value: /mnt/user/appdata/oauth2-proxy

Listen addressVariable

Address inside the container. Leave as is unless you change the port above too.

Target: OAUTH2_PROXY_HTTP_ADDRESS
Default: 0.0.0.0:4180
Value: 0.0.0.0:4180

ProviderVariable

Keep 'oidc' for any standards-compliant provider (ZITADEL, Keycloak, Authentik, Authelia...). Other values such as google or github are also supported.

Target: OAUTH2_PROXY_PROVIDER
Default: oidc
Value: oidc

Issuer URLVariable

Public HTTPS address of your identity provider, exactly as it appears in the 'issuer' field of its /.well-known/openid-configuration. No trailing slash.

Target: OAUTH2_PROXY_OIDC_ISSUER_URL

Client IDVariable

Client ID of the application you registered at the provider.

Target: OAUTH2_PROXY_CLIENT_ID

Client secretVariable

Client secret of that same application.

Target: OAUTH2_PROXY_CLIENT_SECRET

Redirect URLVariable

Leave it as a path only and the absolute URL is derived from the host of each request, so one container serves many sites. Every one of those sites must be registered as a redirect URI at your provider, as https://site/oauth2/callback.

Target: OAUTH2_PROXY_REDIRECT_URL
Default: /oauth2/callback
Value: /oauth2/callback

Cookie secretVariable

32 random bytes, base64. Generate with: openssl rand -base64 32 . Changing it signs everyone out.

Target: OAUTH2_PROXY_COOKIE_SECRET

Cookie domainsVariable

Domains the session cookie is issued for, comma separated. A leading dot covers subdomains (.example.com), so a single login is shared by every protected site under it.

Target: OAUTH2_PROXY_COOKIE_DOMAINS

Allowed redirect domainsVariable

Domains the proxy may send the visitor back to after login, comma separated. A leading dot allows subdomains. Anything not listed here is refused, which is what stops an open redirect.

Target: OAUTH2_PROXY_WHITELIST_DOMAINS

Secure cookieVariable

Only send the session cookie over HTTPS. Leave true unless you are testing over plain HTTP.

Target: OAUTH2_PROXY_COOKIE_SECURE
Default: true
Value: true

Session lifetimeVariable

How long a login lasts before the visitor has to authenticate again.

Target: OAUTH2_PROXY_COOKIE_EXPIRE
Default: 8h
Value: 8h

E-mail domainsVariable

Accepted e-mail domains. Set to * when you filter with the allow-list file below instead.

Target: OAUTH2_PROXY_EMAIL_DOMAINS
Default: *
Value: *

Allow-list fileVariable

File with one allowed e-mail address per line, inside the Data folder above. The container watches it, so adding someone does not need a restart. Without it, every account at your provider gets in.

Target: OAUTH2_PROXY_AUTHENTICATED_EMAILS_FILE
Default: /data/authenticated-emails.txt
Value: /data/authenticated-emails.txt

UpstreamsVariable

Leave as static://202 when your reverse proxy does the proxying (auth_request). Point it at an app URL only if you want this container to proxy the traffic itself.

Target: OAUTH2_PROXY_UPSTREAMS
Default: static://202
Value: static://202

Behind reverse proxyVariable

Trust X-Forwarded-* headers, but only from the addresses listed below.

Target: OAUTH2_PROXY_REVERSE_PROXY
Default: true
Value: true

Trusted proxy IPsVariable

CIDR of your reverse proxy, for example 192.168.1.10/32. Fill this in: leaving it empty lets any client claim any IP address in the logs and in rate limiting.

Target: OAUTH2_PROXY_TRUSTED_PROXY_IPS

Skip provider buttonVariable

Go straight to the provider instead of showing an extra 'Sign in' page first.

Target: OAUTH2_PROXY_SKIP_PROVIDER_BUTTON
Default: true
Value: true

ScopeVariable

OIDC scopes requested at login.

Target: OAUTH2_PROXY_SCOPE
Default: openid email profile
Value: openid email profile

PKCE methodVariable

Proof Key for Code Exchange. Leave S256 if your provider supports it.

Target: OAUTH2_PROXY_CODE_CHALLENGE_METHOD
Default: S256
Value: S256

Pass auth headersVariable

Return X-Auth-Request-User and X-Auth-Request-Email to the reverse proxy, so a protected app can know who is signed in.

Target: OAUTH2_PROXY_SET_XAUTHREQUEST
Default: true
Value: true

Real client IP headerVariable

Header used to work out the visitor's address for logging.

Target: OAUTH2_PROXY_REAL_CLIENT_IP_HEADER
Default: X-Real-IP
Value: X-Real-IP

Allowed groupsVariable

Optional: restrict logins to members of these groups, as they appear in the groups claim of your provider's token. Leave empty to rely on the allow-list file.

Target: OAUTH2_PROXY_ALLOWED_GROUP

TZVariable

Container time zone, used in the log timestamps.

Default: Europe/Madrid
Value: Europe/Madrid

Library

Curated

Categories