OAuth2 Proxy: put an OIDC login in front of any application

OAuth2 Proxy is an open-source reverse proxy that puts an OpenID Connect login in front of an application that has none. The user hits the proxy, signs in through your identity provider, and only then is the request forwarded to the app. The app itself never changes: no SDK, no OIDC library, no session code.

Short answer: deploy oauth2-proxy next to any internal tool, dashboard, wiki or legacy app that cannot do SSO on its own, point it at Casdoor as the OIDC provider, and protect the app with a proxy in front.

How it works

1. A user opens the protected URL.
2. oauth2-proxy sees no session cookie and redirects the browser to the identity provider.
3. The user signs in at the provider, which redirects back to /oauth2/callback on the proxy.
4. The proxy exchanges the authorization code for tokens, validates the ID token, sets an encrypted session cookie and forwards the request to the upstream application.
5. On later requests the cookie is checked locally; the app receives the request as if the user had always been allowed in.

The proxy can also pass the user's identity to the app in headers, which is useful when the app needs to know who is logged in.

A working configuration with Casdoor

Create an application in Casdoor with the OpenID Connect type. Set its redirect URL to:

https://app.example.com/oauth2/callback

Copy the client ID and client secret, then start the proxy:

oauth2-proxy \
  --provider=oidc \
  --oidc-issuer-url=https://door.example.com \
  --client-id=<client ID> \
  --client-secret=<client secret> \
  --cookie-secret=<32-byte secret> \
  --email-domain=* \
  --upstream=http://127.0.0.1:3000/ \
  --redirect-url=https://app.example.com/oauth2/callback \
  --http-address=0.0.0.0:4180

The flags can also be set as environment variables or in a config file. --oidc-issuer-url is the Casdoor base URL; the proxy reads /.well-known/openid-configuration from it to find the authorization and token endpoints.

Generate the cookie secret with a random 32-byte value, as the project documents:

openssl rand -base64 32 | tr -- '+/' '-_'

Passing identity to the application

By default the upstream app only sees an authenticated request. Two flags change that:

• --set-xauthrequest adds X-Auth-Request-User, X-Auth-Request-Email, X-Auth-Request-Groups and X-Auth-Request-Preferred-Username response headers.
• --pass-access-token adds X-Auth-Request-Access-Token.

Only trust these headers from the proxy. If the app is reachable directly, anyone can forge them, so bind the upstream to localhost or a private network and firewall the app port.

Nginx auth_request mode

Instead of proxying every byte, oauth2-proxy can act as an authentication service for Nginx's auth_request directive. Nginx forwards each request's headers to the proxy, which returns 202 for an authenticated session or 401 to trigger the login redirect. This is useful when Nginx already terminates TLS and routes the application.

Common errors

When not to use it

If the application supports OIDC or SAML natively, configure it directly; a proxy adds a hop and a second place to manage sessions. If you need per-user authorization inside the application rather than a gate in front of it, the app needs its own integration.

For everything else, a proxy is the fastest way to put SSO in front of tools that will never support it. Casdoor provides the OIDC side, with MFA, passkeys, organizations and social login included. Self-host Casdoor for free, or use Casdoor Cloud from $6.67/month billed yearly and point the proxy at your instance.

FAQ

What is oauth2-proxy used for? It adds OAuth 2.0 or OpenID Connect authentication to applications that do not support it, by acting as a reverse proxy in front of them.

Does oauth2-proxy work with any identity provider? It works with any provider that supports OpenID Connect discovery, including Casdoor, Keycloak, Entra ID, Okta, Google and Auth0.

Where is the callback URL configured? In the identity provider's application settings, and in the proxy with --redirect-url. The path is normally /oauth2/callback.

Can oauth2-proxy pass the user's groups to the app? Yes, with --set-xauthrequest, which adds X-Auth-Request-Groups from the groups claim in the ID token.

Is oauth2-proxy a replacement for an identity provider? No. It is a client of an identity provider: the provider authenticates users and issues tokens; the proxy enforces the login in front of an app.