Set Up GitHub Login

This guide walks through configuring GitHub as an external identity provider so users can sign in with their GitHub accounts.

1. Create a GitHub OAuth App

Go to GitHub Developer Settings

Navigate to GitHub Developer Settings → OAuth Apps → New OAuth App.

Fill in the application details

Field	Value
Application name	Your app name (e.g., "Aero2")
Homepage URL	`https://aero2.dev`
Authorization callback URL	`https://aero2.dev/rp/callback/github`

Save the credentials

After creating the app, copy the Client ID and generate a Client Secret.

2. Configure Aero2

You can configure the GitHub IdP either via environment variables (for the built-in provider) or via the Admin API (for dynamic configuration).

Option A: Admin API

curl -X POST https://aero2.dev/api/idps \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "type": "oauth2",
    "display_name": "GitHub",
    "client_id": "Iv1.your_client_id",
    "client_secret": "your_client_secret",
    "authorization_endpoint": "https://github.com/login/oauth/authorize",
    "token_endpoint": "https://github.com/login/oauth/access_token",
    "userinfo_endpoint": "https://api.github.com/user",
    "scopes": "read:user user:email"
  }'

3. Test It

Visit your Aero2 login page
Click "Sign in with GitHub"
Authorize the application on GitHub
You should be redirected to the dashboard with your GitHub profile

Troubleshooting

Issue	Solution
"Failed to load identity providers"	Check that database migrations have been applied
"Invalid callback URL"	Verify the callback URL matches exactly: `https://aero2.dev/rp/callback/github`
"Error exchanging code"	Check that `GITHUB_CLIENT_SECRET` is correct

GitHub Scopes

Scope	Purpose
`read:user`	Access user profile (name, avatar)
`user:email`	Access user email addresses