Relying Party

When Aero2 acts as a Relying Party (RP), it lets users sign in with external identity providers like GitHub or Google. These endpoints handle the OAuth2 flow with external IdPs.

See RP vs Provider for when Aero2 uses each role.

GET/rp/authorizeNo Auth

Initiates the OAuth2 flow with an external identity provider (e.g., GitHub). Generates state, stores it in the database, and redirects to the external IdP.

Parameter	Type	Description
idp* query	string	The identity provider name (e.g., "github")
redirect_uri query	string	Where to redirect after login (defaults to /dashboard)

Response

HTTP 302 → https://github.com/login/oauth/authorize?client_id=...&state=...

GET/rp/callback/:idpNo Auth

Handles the OAuth callback from an external IdP. Validates state (cookie + DB), exchanges code for token, fetches user info, creates/links local user, and establishes a session.

Parameter	Type	Description
idp* path	string	The identity provider name (e.g., "github")
code* query	string	Authorization code from the external IdP
state* query	string	State parameter for CSRF validation

Response

HTTP 302 → /dashboard (with session cookie set)

GET/rp/userinfoSession

Returns profile information for the currently authenticated user (via session cookie).

Response

{
  "id": "user-uuid",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "picture": "https://avatars.githubusercontent.com/u/12345",
  "roles": [
    "user"
  ]
}

Flow

User visits /rp/authorize?idp=github
Aero2 redirects to GitHub's authorization page
GitHub redirects back to /rp/callback/github with a code
Aero2 exchanges the code, fetches user info, and creates a local session
User is redirected to the dashboard (or specified redirect_uri)