GitHub Social Login

This guide will walk you through setting up GitHub authentication for your application. GitHub OAuth allows users to sign in using their GitHub accounts.

Prerequisites

Step 1: Create a GitHub OAuth App

  1. Go to GitHub Developer Settings
  2. Click OAuth Apps in the left sidebar
  3. Click New OAuth App
  4. Fill in the application details:
    • Application name: Your application name (e.g., "My App")
    • Homepage URL: Your application URL (e.g., http://localhost:8000 for local development or https://yourdomain.com for production)
    • Authorization callback URL: http://localhost:8000/auth/github/callback (for local development) or https://yourdomain.com/auth/github/callback (for production)
  5. Click Register application
  6. On the next page, you'll see your Client ID
  7. Click Generate a new client secret to create your client secret
  8. Copy both the Client ID and Client Secret (you won't be able to see the secret again)
  9. Once you have set the Client ID and Client Secret, navigate to Permissions & events in the OAuth App settings
  10. Under Account permissions, add Email address with Read-only access

Step 2: Configure Environment Variables

Add your GitHub OAuth credentials to your .env file:

GITHUB_CLIENT_ID=your-client-id-here
GITHUB_CLIENT_SECRET=your-client-secret-here
GITHUB_REDIRECT_URI=http://localhost/auth/github/callback

Note: For production, update GITHUB_REDIRECT_URI to match your production domain.

Step 3: Verify Configuration

The configuration is already set up in config/services.php:

'github' => [
    'client_id'     => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect'      => env('GITHUB_REDIRECT_URI'),
],

Make sure your .env values are correctly set and match the callback URL you configured in GitHub.

Step 4: Routes

The routes are already configured in routes/web.php:

Route::get('/auth/github/redirect', [SocialAuthController::class, 'redirectToGithub'])
    ->name('auth.github.redirect');

Route::get('/auth/github/callback', [SocialAuthController::class, 'handleGithubCallback'])
    ->name('auth.github.callback');

Step 5: Using the Social Login Button

The social login button component is already included in the login and registration pages. To add it to other pages, use:

<x-blocks.auth.social-login provider="github" />

This will render a button that redirects users to GitHub's authentication page.

GitHub Email Requirements

Important: GitHub requires special handling for email addresses:

  • Users must have a public email address, OR
  • Users must grant the user:email scope to your application

By default, Laravel Socialite requests the user:email scope, which allows access to the user's email even if it's private. However, if a user doesn't grant this permission or doesn't have an email set up, authentication will fail with an error message.

Common Issues

Redirect URI Mismatch

Error: "redirect_uri_mismatch" or "The redirect_uri MUST match the registered callback URL"

Solution: Ensure the callback URL in your GitHub OAuth App settings exactly matches the one in your .env file, including the protocol (http/https) and no trailing slashes.

Invalid Client

Error: "invalid_client"

Solution: Verify that your GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are correct. If you regenerated the client secret, make sure to update your .env file.

Email Not Available

Error: "Unable to log in with GitHub. Your account must have an email address."

Solution: This occurs when GitHub doesn't return an email address. Users need to:

  • Have a public email address on their GitHub profile, OR
  • Grant the user:email scope when authorizing the application
Make sure users understand they need to grant email access for authentication to work.

trong>Solution: Check your GitHub OAuth App settings. The application may have been suspended due to policy violations. Contact GitHub support if needed.

Production Checklist

  • ✅ Update GITHUB_REDIRECT_URI to your production domain
  • ✅ Update the callback URL in GitHub OAuth App settings to production URL
  • ✅ Test the authentication flow on production
  • ✅ Ensure HTTPS is enabled (required for production OAuth)
  • ✅ Verify that users can successfully authenticate with email access granted

Additional Resources