OIDC & OAuth2 Overview

OAuth2

OAuth2 is an authorization framework that lets applications access resources on behalf of a user without knowing their password. Instead of sharing credentials, the user authorizes the application, which receives a time-limited access token.

Key concepts:

Resource Owner — The user
Client — The application requesting access
Authorization Server — Issues tokens (Aero2)
Resource Server — The API being accessed

OpenID Connect (OIDC)

OpenID Connect is a layer on top of OAuth2 that adds authentication. While OAuth2 answers "what can this app access?", OIDC answers "who is this user?"

OIDC adds:

ID tokens — JWTs containing user identity claims
UserInfo endpoint — API to fetch user profile data
Discovery — Standard endpoint to find provider capabilities
Standard scopes — openid, profile, email

How Aero2 Uses These

Aero2 implements both protocols:

Role	Protocol	What it does
OIDC Provider	OAuth2 + OIDC	Issues tokens for your apps
Relying Party	OAuth2	Signs users in with GitHub, Google, etc.

As Provider

Your application redirects users to Aero2, which authenticates them and returns tokens:

Browser

Your App

Aero2

1
Browser → Your App
User clicks Login
2
Your App
Generate PKCE code_verifier + code_challenge
crypto.getRandomValues() + SHA-256
3
Your App → Aero2
Redirect to /oauth2/authorize
?client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256&response_type=code&scope=openid+profile+email
4
Aero2 → Browser
Show login page
User authenticates with identity provider
5
Aero2 → Your App
Redirect to redirect_uri with code
?code=abc123&state=xyz
6
Your App → Aero2
Exchange code for tokens
POST /oauth2/token grant_type=authorization_code&code=...&code_verifier=...
7
Aero2 → Your App
Return access_token, id_token, refresh_token
RS256-signed JWTs
8
Your App → Aero2
Fetch user info (optional)
GET /oauth2/userinfo Authorization: Bearer <access_token>

As Relying Party

Aero2 redirects users to external providers, then creates local accounts:

Browser

Aero2

External IdP

1
Browser → Aero2
User clicks Login with GitHub
GET /rp/authorize?idp=github&redirect_uri=/dashboard
2
Aero2
Generate state, store in DB
10-minute expiry, set HttpOnly cookie
3
Aero2 → External IdP
Redirect to GitHub authorize URL
?client_id=...&redirect_uri=/rp/callback/github&state=...
4
External IdP → Browser
User authenticates with GitHub
5
External IdP → Aero2
Redirect back with code
GET /rp/callback/github?code=...&state=...
6
Aero2
Validate state (cookie + DB)
Atomic DELETE with RETURNING prevents replay
7
Aero2 → External IdP
Exchange code for access token
POST to GitHub token endpoint
8
Aero2 → External IdP
Fetch user info from GitHub
GET /user with access token
9
Aero2
Create/link local user, create session
10
Aero2 → Browser
Set session cookie, redirect to dashboard
HttpOnly, Secure, SameSite=Lax

Key Differences from Other Providers

Feature	Aero2	Auth0 / Okta
Hosting	Self-hosted, your infrastructure	SaaS
Multi-tenant	Built-in application isolation	Per-tenant pricing
Customization	Full source code access	Limited
PKCE	Required (S256 only)	Optional