Understanding OAuth2 and OpenID Connect for Self-Hosted Apps

OAuth2 and OpenID Connect (OIDC) are the standard protocols for authorization and authentication in modern web applications. Understanding these protocols helps you implement secure authentication for self-hosted applications and integrate with identity providers.

OAuth2 vs OpenID Connect

• OAuth2 — Authorization protocol. Grants access to resources (APIs) without sharing credentials. Answers: "What can this app do?"
• OpenID Connect (OIDC) — Authentication layer built on OAuth2. Verifies user identity. Answers: "Who is this user?"

OAuth2 Grant Types

# 1. Authorization Code (most secure for web apps)
# User redirected to auth server -> logs in -> redirected back with code
# App exchanges code for tokens server-side
# Use this for: Server-rendered web applications

# 2. Authorization Code with PKCE (for SPAs and mobile apps)
# Like Authorization Code but with Proof Key for Code Exchange
# Prevents authorization code interception
# Use this for: Single Page Applications, mobile apps

# 3. Client Credentials (machine-to-machine)
# App authenticates directly with client ID and secret
# No user involved
# Use this for: Backend services, cron jobs, APIs

# 4. Refresh Token
# Exchange a refresh token for a new access token
# Avoids re-authentication

Self-Hosted Identity Providers

# Keycloak (most popular self-hosted IdP)
docker run -d --name keycloak -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest start-dev

# Authentik (modern alternative)
# Full-featured IdP with beautiful UI
# Supports OIDC, SAML, LDAP, and SCIM

# Authelia (lightweight 2FA proxy)
# Adds authentication to any application via reverse proxy
# Supports OIDC provider mode

Implementing OIDC in Your Application

# Key endpoints your app needs to know:
# Authorization: /auth/realms/{realm}/protocol/openid-connect/auth
# Token: /auth/realms/{realm}/protocol/openid-connect/token
# UserInfo: /auth/realms/{realm}/protocol/openid-connect/userinfo
# JWKS: /auth/realms/{realm}/protocol/openid-connect/certs

# Discovery endpoint (auto-configures everything):
# https://idp.example.com/.well-known/openid-configuration

Token Types

# ID Token (OIDC) — Contains user identity claims
# - JWT format, signed by the IdP
# - Contains: sub (user ID), name, email, iss (issuer), exp (expiry)
# - Verify signature using JWKS endpoint

# Access Token — Grants API access
# - Can be JWT or opaque string
# - Short-lived (5-60 minutes)
# - Sent in Authorization: Bearer header

# Refresh Token — Used to get new access tokens
# - Long-lived (days to months)
# - Stored securely server-side
# - Never expose to the browser

Security Best Practices

1. Always use HTTPS for all OAuth2/OIDC communication
2. Use Authorization Code + PKCE (never use Implicit flow)
3. Validate ID tokens by verifying the JWT signature
4. Check the issuer (iss) and audience (aud) claims
5. Use short-lived access tokens with refresh tokens
6. Store tokens securely (httpOnly cookies, not localStorage)
7. Implement token revocation for logout
8. Use state parameter to prevent CSRF attacks