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

RP vs Provider

Aero2 serves two distinct roles in the authentication ecosystem. Understanding when it acts as each is key to using it effectively.

Aero2 as Provider (OP)

When your application uses Aero2 to authenticate users, Aero2 acts as the OpenID Connect Provider (OP).

Your app → redirects to Aero2 → Aero2 authenticates the user → returns tokens to your app

Use this when:

  • You're building an app that needs user authentication
  • You want to issue your own access tokens
  • You need OIDC-standard tokens for API authorization
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>

Aero2 as Relying Party (RP)

When a user signs in with GitHub, Google, or another external provider, Aero2 acts as the Relying Party (RP).

User → clicks "Sign in with GitHub" on Aero2 → Aero2 redirects to GitHub → GitHub authenticates → Aero2 creates a local session

Use this when:

  • You want users to sign in with their existing accounts (GitHub, Google, etc.)
  • You're configuring social login for Aero2 itself
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

Both Roles Together

In practice, both roles work together:

  1. User visits your app → Your app redirects to Aero2 (Aero2 = Provider)
  2. User clicks "Sign in with GitHub" → Aero2 redirects to GitHub (Aero2 = Relying Party)
  3. GitHub authenticates the user → GitHub redirects back to Aero2
  4. Aero2 creates a session → Aero2 issues tokens back to your app
Your App → Aero2 (Provider) → GitHub (External IdP)
                                    ↓
Your App ← Aero2 (Provider) ← Aero2 (Relying Party)

API Endpoints by Role

RoleEndpointsPurpose
Provider/oauth2/authorize, /oauth2/token, /oauth2/userinfoIssue tokens for your apps
Relying Party/rp/authorize, /rp/callback/:idpSign in with external IdPs
Both/.well-known/openid-configuration, /oauth2/jwks.jsonDiscovery and key verification