GitHub OAuth (sign-in with GitHub)

Lets users register and sign in with their GitHub account via OAuth. Setup is faster than Google's because GitHub doesn't require an OAuth consent flow review.

What you need

• A GitHub account.
• The Formspring server's HTTPS URL (production) and a local dev URL.

* * *

Step 1 - Create an OAuth App

1. Go to https://github.com/settings/developers → OAuth Apps tab → New OAuth App.

   For an organisation-scoped app (so org admins manage it), instead go to Org settings → Developer settings → OAuth Apps → New OAuth App.

2. Fill in:

   • Application name: Formspring.
   • Homepage URL: https://formspring.io.
   • Application description (optional): Form-builder login.
   • Authorisation callback URL: https://formspring.io/oauth/github/callback.

   GitHub allows multiple callback URLs only if you go through GitHub Apps. For OAuth Apps, you get one callback URL per registration. So:

   • Production: https://formspring.io/oauth/github/callback.
   • Dev: register a separate OAuth App with http://pixel-forms.test/oauth/github/callback (or http://localhost:80/oauth/github/callback) and put its credentials in .env.local.

3. Register application.

* * *

Step 2 - Get the credentials

1. On the app page after creation, copy the Client ID (visible in the header).
2. Click Generate a new client secret → copy the secret (shown once - re-generate if you lose it).

* * *

Step 3 - Configure Formspring

In .env:

GITHUB_CLIENT_ID=<client id>
GITHUB_CLIENT_SECRET=<client secret>
GITHUB_REDIRECT_URI=https://formspring.io/oauth/github/callback

For local dev with a separate OAuth App registration:

GITHUB_CLIENT_ID=<dev client id>
GITHUB_CLIENT_SECRET=<dev client secret>
GITHUB_REDIRECT_URI=http://pixel-forms.test/oauth/github/callback

* * *

Step 4 - Verify

1. Restart the app.
2. Visit /login → click GitHub.
3. GitHub asks for permission to share email + profile.
4. You should land on /dashboard (new account creation) or your post-login route.

* * *

Step 5 - Email considerations

GitHub users can have multiple emails + private email addresses. The OAuth callback hits /user and /user/emails to find a verified primary email.

The SocialAuthController::resolveEmail() flow:

1. If GitHub returns an email → use it.
2. If the user has a private email visibility setting → the callback still gets the email via the user:email scope.
3. If neither: rejected with a flash message asking the user to enable email visibility on GitHub.

* * *

Where the credential lives

• Server: .env → config/services.php github.client_id, github.client_secret, github.redirect.
• User-side: users.github_id column.
• Controller: app/Http/Controllers/Auth/SocialAuthController.php.
• Routes: routes/web.php → oauth/github/{redirect,callback,register-intent}.

* * *

Security

• The client secret is critical. Rotate at the app's settings page → Generate a new client secret.
• Old secrets are revoked immediately on rotation; deploy the new env value before clicking Generate, or have a brief outage window.
• GitHub Apps (vs. OAuth Apps) offer fine-grained per-repo permissions and short-lived tokens - overkill for pure auth but worth migrating to if you ever need to read repo data.
• Formspring only requests read:user + user:email scopes - minimal access, never repo content.

* * *

Production checklist

• Production OAuth App registered with the exact callback URL.
• Dev OAuth App registered separately (or skip dev OAuth and stub the GitHub driver in tests as tests/Feature/SocialAuthTest.php does).
• .env.production has GITHUB_* vars set.
• HTTPS in production (GitHub allows http://localhost and http://* but disallows non-localhost HTTP for security).
• users.github_id column exists (migration 2026_05_07_125817_add_oauth_columns_to_users_table.php already adds it).

* * *

Troubleshooting

* * *

Provider docs

• GitHub OAuth Apps: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps
• Authorising OAuth Apps: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps