🔐 OAuth2 Proxy

OAuth2 Proxy is an open‑source authentication and authorization gateway designed to sit in front of applications and enforce identity verification using modern OAuth2 and OIDC providers. It acts as a lightweight security layer that handles login redirects, token validation, session management, and identity header injection—allowing upstream services to remain simple and authentication‑agnostic.

In the homelab environment, OAuth2 Proxy integrates tightly with Microsoft Entra ID and the Nginx reverse‑proxy layer to provide consistent, centralized Single Sign‑On (SSO) across internal applications.

🔗 Official Documentation

For full upstream reference material, see:

🧭 Purpose in the Homelab

OAuth2 Proxy provides:

Authentication Gateway for the Homelab Reverse‑Proxy Layer

It does not replace Entra ID or Nginx. Instead, it acts as the authentication engine that Nginx delegates to.

🏗️ Architectural Role

Client → Nginx Reverse Proxy → OAuth2 Proxy → Entra ID
                                   ↓
                              Upstream App

Flow Summary

  1. User requests a protected URL.
  2. Nginx calls /oauth2/auth to check authentication.
  3. OAuth2 Proxy redirects the user to Entra ID (/oauth2/start).
  4. After login, Entra ID returns the user to /oauth2/callback.
  5. OAuth2 Proxy validates the token and stores the session in Redis.
  6. Nginx forwards the request to the upstream service with identity attached.

🧩 Redis Session Storage

OAuth2 is configured to use Redis as the session backend. This provides:

While OAuth2 Proxy supports encrypted cookie‑based sessions, Redis is preferred because:

ℹ️ NOTE While using OAuth2 with EntraID, a warning in the OAuth2 logs stating, Multiple cookies are required for this session as it exceeds the 4kb cookie limit. Please use server side session storage (eg. Redis) instead was shown. Using Redis with OAuth2 removed this warning.

Redis Configuration

Redis must be installed before OAuth2 Proxy. The redis_setup role handles installation, and oauth2_proxy_setup configures OAuth2 Proxy to use it with the following configuration settings.

For a comprehensive documentation on OAuth2 proxy configuration settings,

👉 See: OAuth2 Proxy Configuration File Documentation

📦 Installation & Management (Ansible Role)

The oauth2_proxy_setup role handles:

This role consumes outputs from the Entra ID OAuth2 Provisioning Ansible Role, ensuring the OAuth2 Proxy instance is always aligned with the correct application registration. It also requires that Redis is pre-installed.

⚙️ Configuration Overview

Key Endpoints

OAuth2 Proxy exposes:

Identity Headers Forwarded

Typical headers forwarded to upstream apps:

Your Nginx site definitions determine which headers are passed through.

Session Handling with Redis

OAuth2 Proxy stores session data in Redis, including:

This allows OAuth2 Proxy to remain stateless and restart‑safe.

🔑 Microsoft Entra ID Integration

OAuth2 Proxy uses Entra ID as its OIDC provider.
Your provisioning role creates:

OAuth2 Proxy consumes these values to authenticate users and extract identity information.

For a more detailed documentation on OAuth2 Proxy’s integration with Entra ID,

👉 see: OAuth2 Proxy Integration with Entra ID

🧩 Integration with Nginx Reverse Proxy

Each protected site defined in the rproxy_setup_sites inventory entry can enable OAuth2 authentication.

Nginx uses:

auth_request /oauth2/auth;
error_page 401 = /oauth2/start;

OAuth2 Proxy then validates the session (via Redis) and returns identity headers for Nginx to forward upstream.

This pattern ensures:

For a more detailed documentation on OAuth2 integration with Nginx proxy,

👉 see: Reverse-Proxy with OAuth2 Integration

🔗 Related Pages