Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

How Authentication Works

This page explains how Aero2 authenticates users at a high level. Aero2 implements the industry-standard OAuth 2.0 and OpenID Connect (OIDC) protocols, so your application never handles passwords directly.

The Authorization Code Flow

The primary way users authenticate with Aero2 is through the Authorization Code flow with PKCE:

  1. Your application redirects the user to Aero2's authorization endpoint.
  2. The user authenticates (enters credentials, uses social login, etc.).
  3. Aero2 redirects back to your application with an authorization code.
  4. Your application exchanges the code for tokens (access token, ID token, refresh token).
  5. Your application uses the access token to make authenticated API calls.
Browser
Your App
Aero2
  1. 1
    Browser → Your App
    User clicks Login
  2. 2
    Your App
    Generate PKCE code_verifier + code_challenge
    crypto.getRandomValues() + SHA-256
  3. 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. 4
    Aero2 → Browser
    Show login page
    User authenticates with identity provider
  5. 5
    Aero2 → Your App
    Redirect to redirect_uri with code
    ?code=abc123&state=xyz
  6. 6
    Your App → Aero2
    Exchange code for tokens
    POST /oauth2/token grant_type=authorization_code&code=...&code_verifier=...
  7. 7
    Aero2 → Your App
    Return access_token, id_token, refresh_token
    RS256-signed JWTs
  8. 8
    Your App → Aero2
    Fetch user info (optional)
    GET /oauth2/userinfo Authorization: Bearer <access_token>

PKCE (Proof Key for Code Exchange) is required for all authorization requests. It protects the flow from code interception attacks by binding the token exchange to the original authorization request.

The Relying Party Flow (Social Login)

When a user chooses to sign in with an external provider like GitHub or Google, Aero2 acts as a relying party — it delegates authentication to the external provider:

  1. The user clicks "Sign in with GitHub" in your application.
  2. Your application redirects to Aero2, which redirects to GitHub.
  3. The user authenticates with GitHub.
  4. GitHub redirects back to Aero2 with the user's identity.
  5. Aero2 creates or links a local user account and establishes a session.
  6. Aero2 redirects back to your application with an authorization code.
  7. Your application exchanges the code for tokens, just like the standard flow.
Browser
Aero2
External IdP
  1. 1
    Browser → Aero2
    User clicks Login with GitHub
    GET /rp/authorize?idp=github&redirect_uri=/dashboard
  2. 2
    Aero2
    Generate state, store in DB
    10-minute expiry, set HttpOnly cookie
  3. 3
    Aero2 → External IdP
    Redirect to GitHub authorize URL
    ?client_id=...&redirect_uri=/rp/callback/github&state=...
  4. 4
    External IdP → Browser
    User authenticates with GitHub
  5. 5
    External IdP → Aero2
    Redirect back with code
    GET /rp/callback/github?code=...&state=...
  6. 6
    Aero2
    Validate state (cookie + DB)
    Atomic DELETE with RETURNING prevents replay
  7. 7
    Aero2 → External IdP
    Exchange code for access token
    POST to GitHub token endpoint
  8. 8
    Aero2 → External IdP
    Fetch user info from GitHub
    GET /user with access token
  9. 9
    Aero2
    Create/link local user, create session
  10. 10
    Aero2 → Browser
    Set session cookie, redirect to dashboard
    HttpOnly, Secure, SameSite=Lax

From your application's perspective, the flow is the same regardless of whether the user signs in with a password or a social provider. Aero2 handles all the provider-specific logic.

Tokens

Aero2 issues several types of JWT tokens:

  • Access tokens — Short-lived tokens used to authenticate API requests. Verified using the JWKS endpoint.
  • ID tokens — Contain user identity claims (name, email). Used by your frontend to display user info.
  • Refresh tokens — Long-lived tokens used to obtain new access tokens without re-authentication. Subject to rotation.

All tokens are signed with RS256 and can be verified using the public keys available at the JWKS endpoint.

What's Next?