Self-host OAuth2 Proxy
updated Oct 2026deployed by usprices checked · Jul 2026Install verified on Ubuntu 26.04 · Oct 2026 · how we test
We earn commissions when you shop through the links below. Full disclosure →
A reverse proxy and middleware that puts OAuth2 and OIDC sign-in in front of applications that have no login of their own: a generic OIDC client plus provider implementations for Google, Microsoft Entra ID, GitHub, login.gov and others. Runs as a standalone proxy or as an `auth_request` target behind an existing proxy. MIT-licensed Go, stateless with cookie sessions.
Key facts
CategorySSO & Identity
LicenseMIT
StackGo
Min RAM128 MB
Official imageyes
Measured idle RAM4 MB
Last commitOctober 1, 2026
Last releasev7.15.5, October 1, 2026
CheckedGitHub, October 25, 2026
Difficulty
Runs on a VPS from $4/mo (Kamatera 1GB, 1 GB RAM) · prices checked Sep 2026
Our recommendation
Pick OAuth2 Proxy when you already have an identity you trust (a GitHub organisation, Google Workspace, Entra ID, a Keycloak or other OIDC server) and just want to gate an app behind it. It holds no users and no passwords: it redirects to the provider, checks who comes back and sets a cookie, and your reverse proxy asks it on every request whether to let the visitor through. That is its difference from the catalog's Tinyauth and Authelia, which ship their own login portal and user store, and from Pocket ID or Keycloak, which are identity providers themselves. It is MIT-licensed Go and ships as a small container. Our snippet is a GitHub-provider example in Compose form with the cookie secret generated for you and the image pinned to a release tag. We did not find an upstream RAM minimum, so our 128 MB floor is an estimate.
What you need
- Any VPS with at least 128 MB of RAM
- A domain you control — most self-hosted setups need HTTPS in front of them
- Under an hour if you've used Docker before
Where to host itaffiliate disclosure
Hetzner Cloudrun it on
From $23.59/mo · 2 vCPU / 4 GB / 80 GB · EU + USKamaterafree trial
From $4/mo · 1 vCPU / 1 GB / 20 GB · US + EU + AsiaDigitalOceanalso works on
From $6/mo · 1 vCPU / 1 GB / 25 GB · US + EU + AsiaPaid link — we earn a commission if you shop through it.
Install
Run these commands on your server:
# OAuth2 Proxy — OAuth2/OIDC sign-in in front of apps with no login — GitHub provider example, pinned to v7.15.5
cat > docker-compose.yml <<'EOF'
services:
oauth2-proxy:
image: quay.io/oauth2-proxy/oauth2-proxy:v7.15.5
restart: unless-stopped
environment:
OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
OAUTH2_PROXY_PROVIDER: github
OAUTH2_PROXY_CLIENT_ID: ${GITHUB_CLIENT_ID}
OAUTH2_PROXY_CLIENT_SECRET: ${GITHUB_CLIENT_SECRET}
OAUTH2_PROXY_COOKIE_SECRET: ${COOKIE_SECRET}
OAUTH2_PROXY_COOKIE_SECURE: "false"
OAUTH2_PROXY_EMAIL_DOMAINS: "*"
OAUTH2_PROXY_UPSTREAMS: static://202
OAUTH2_PROXY_REDIRECT_URL: http://SERVER_IP:4180/oauth2/callback
ports:
- 4180:4180
EOF
echo "GITHUB_CLIENT_ID=replace-with-your-client-id" > .env
echo "GITHUB_CLIENT_SECRET=replace-with-your-client-secret" >> .env
echo "COOKIE_SECRET=$(openssl rand -base64 32 | tr -- '+/' '-_')" >> .env
docker compose up -d
timeout 60 bash -c 'until curl -fsS http://localhost:4180/ping >/dev/null; do sleep 3; done'
# → http://SERVER_IP:4180/ping — replace the client ID and secret in .env with a real GitHub OAuth app before signing inWhat you take on
OAuth2 Proxy's configuration docs flag these before you protect anything with it:
non-negotiableThe snippet starts the proxy and answers /ping, but signing in needs a real OAuth app: create one with your provider, set its callback to http://SERVER_IP:4180/oauth2/callback (the redirect_url in the compose file) and put its client ID and secret in .env. The placeholders in .env are not credentials, so the sign-in redirect will fail until you replace them. Until you sign in, / answers with the Sign In page and an HTTP 403, which is how our check saw it; /ping is the health endpoint.
non-negotiableOAUTH2_PROXY_EMAIL_DOMAINS: "*" lets any account at the provider through, which is only there so the container starts. Restrict it before use, with allowed email domains or, for the GitHub provider, an organisation, team or user list. OAUTH2_PROXY_UPSTREAMS: static://202 makes the proxy answer 202 once a visitor is authenticated, the setup used when another proxy asks it to authorise requests; to proxy a real app, point UPSTREAMS at it instead.
non-negotiableThe cookie secret must be 16, 24 or 32 bytes, optionally base64-encoded; our snippet generates 32 random bytes into .env. COOKIE_SECURE: "false" is there only because the example is plain HTTP; leave it at its default (true) behind TLS, which is how it should run.
non-negotiableBehind another reverse proxy, the docs say to enable --reverse-proxy and set --trusted-proxy-ip to the proxies allowed to send X-Forwarded-* headers; leave it unset and every source IP is currently trusted for backwards compatibility. Never use --trusted-ip as a list of proxies: the docs call it an authentication bypass.
More in SSO & Identity
SSO & Identity
Authelia
Go
moderateRead guide →
SSO & Identity
authentik
PythonGoTypeScript
moderateRead guide →
SSO & Identity
Casdoor
GoReact
easyRead guide →
SSO & Identity
Keycloak
JavaQuarkus
hardRead guide →