GitHub SSO¶
Enable “Sign in with GitHub” for your Gatekeeper instance.
Overview¶
GitHub SSO allows users to sign in using their GitHub account. Gatekeeper checks all verified emails linked to the GitHub account, so users don’t need to set their work email as their primary GitHub email.
Setup¶
1. Create a GitHub OAuth App¶
Click OAuth Apps → New OAuth App
Fill in the details:
Field |
Value |
|---|---|
Application name |
Your app name (e.g., “Gatekeeper”) |
Homepage URL |
|
Authorization callback URL |
|
Click Register application
Copy the Client ID
Click Generate a new client secret and copy it
2. Configure Gatekeeper¶
Add to your .env:
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
Restart Gatekeeper. The GitHub sign-in button will appear automatically.
How it works¶
User clicks “Sign in with GitHub”
GitHub asks user to authorize Gatekeeper
Gatekeeper receives all verified emails from the user’s GitHub account
If any email matches an approved domain → user is auto-approved
If no match → user sees an error asking them to link their org email or use email/passkey
Multiple emails¶
GitHub users often have multiple emails linked:
Personal email (primary)
Work email (secondary)
Old university email
Gatekeeper checks all verified emails, not just the primary. If a user has work@company.com linked to their GitHub (even as secondary), and company.com is an approved domain, they’ll be auto-approved.
Troubleshooting¶
“No approved email found” error
The user’s GitHub account doesn’t have any email from an approved domain. They should:
Add their work email to GitHub: Settings → Emails → Add email
Verify the email
Try signing in again
Or use email OTP / passkey instead.
OAuth errors
Verify the callback URL matches exactly:
https://your-domain/api/v1/auth/github/callbackCheck that client ID and secret are correct
Ensure the OAuth app is not suspended