Add GitHub Sign-In to Your App

Enable "Sign in with GitHub" for your application's users through OAuth42's social authentication feature.

What You'll Build

In this tutorial, you'll configure GitHub as a social identity provider for your OAuth42 application. Your users will be able to click "Sign in with GitHub" and authenticate using their GitHub account.

How it works:

  • User clicks "Sign in with GitHub" in your app
  • OAuth42 redirects to GitHub for authentication
  • GitHub authenticates the user and returns to OAuth42
  • OAuth42 creates/links the user account and issues tokens to your app
  • Your app receives the tokens and the user is logged in

Great for developer-focused apps: GitHub is the go-to choice for developer tools, open source projects, and technical applications. Users trust GitHub and appreciate the quick sign-in experience.

Prerequisites

Step 1: Create a GitHub OAuth App

  1. Go to GitHub Developer Settings
  2. Click OAuth Apps in the sidebar
  3. Click New OAuth App
  4. Fill in the required fields:
    • Application name: Your application name (shown to users during authorization)
    • Homepage URL: Your application's homepage (e.g., https://yourapp.com)
    • Application description: A brief description of your app (optional)
    • Authorization callback URL: Set this to the OAuth42 callback URL (see below)
  5. Click Register application

Organization Apps: You can also create OAuth Apps under a GitHub Organization. Go to your organization's Settings → Developer settings → OAuth Apps.

Step 2: Set the Authorization Callback URL

GitHub needs to know where to redirect users after they authorize your app. Use the OAuth42 callback URL:

  • Production: https://api.oauth42.com/api/social-auth/callback
  • Development: https://localhost:8443/api/social-auth/callback

Single Callback URL: GitHub only allows one callback URL per OAuth App. If you need both development and production, create separate OAuth Apps for each environment.

Step 3: Get Client Credentials

  1. After creating the app, you'll be taken to the app settings page
  2. Copy the Client ID (displayed on the page)
  3. Click Generate a new client secret
  4. Copy the Client secret immediately (you won't be able to see it again)

Copy the secret now! GitHub only shows the client secret once. If you lose it, you'll need to generate a new one.

Step 4: Configure GitHub in OAuth42 Portal

Now configure GitHub as a social provider in your OAuth42 application:

  1. Log in to the OAuth42 Portal
  2. Navigate to Applications and select your application
  3. Click the Social Providers tab
  4. Click Add Provider
  5. Select GitHub from the dropdown
  6. Enter the Client ID you copied from GitHub
  7. Enter the Client Secret you copied from GitHub
  8. Click Add Provider to save

Secure Storage: Your GitHub Client Secret is automatically encrypted with AES-256 before being stored. It's never logged or exposed in plain text.

Step 5: Add GitHub Sign-In Button to Your App

If you're using OAuth42's hosted auth pages, the GitHub Sign-In button appears automatically when you enable the provider. No code changes needed!

For custom login pages, add a GitHub Sign-In button that initiates the social auth flow:

"use client"

import { useState } from 'react'

export default function LoginPage() {
  const [isLoading, setIsLoading] = useState(false)

  const handleGitHubSignIn = async () => {
    setIsLoading(true)

    // Call OAuth42's social auth init endpoint
    const response = await fetch('/api/auth/social/github', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        provider: 'github',
        client_id: process.env.NEXT_PUBLIC_OAUTH42_CLIENT_ID,
        is_signup: true, // Allow account creation
      }),
    })

    const data = await response.json()

    if (data.authorization_url) {
      // Redirect to GitHub
      window.location.href = data.authorization_url
    }
  }

  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-100">
      <div className="max-w-md w-full space-y-6 p-8 bg-white rounded-lg shadow">
        <h1 className="text-2xl font-bold text-center">Sign In</h1>

        <button
          onClick={handleGitHubSignIn}
          disabled={isLoading}
          className="w-full flex items-center justify-center gap-3 py-3 px-4 bg-[#24292e] text-white rounded-lg hover:bg-[#1b1f23] transition-colors"
        >
          <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
            <path d="M12 0C5.374 0 0 5.373 0 12c0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23A11.509 11.509 0 0112 5.803c1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576C20.566 21.797 24 17.3 24 12c0-6.627-5.373-12-12-12z"/>
          </svg>
          {isLoading ? 'Redirecting...' : 'Continue with GitHub'}
        </button>

        <div className="relative">
          <div className="absolute inset-0 flex items-center">
            <div className="w-full border-t border-gray-300" />
          </div>
          <div className="relative flex justify-center text-sm">
            <span className="px-2 bg-white text-gray-500">or</span>
          </div>
        </div>

        {/* Your regular email/password login form */}
        <form className="space-y-4">
          <input
            type="email"
            placeholder="Email"
            className="w-full px-4 py-3 border border-gray-300 rounded-lg"
          />
          <input
            type="password"
            placeholder="Password"
            className="w-full px-4 py-3 border border-gray-300 rounded-lg"
          />
          <button
            type="submit"
            className="w-full py-3 px-4 bg-indigo-600 text-white rounded-lg hover:bg-indigo-700"
          >
            Sign In
          </button>
        </form>
      </div>
    </div>
  )
}

Step 6: Create API Route for Social Auth (Custom Login Only)

If using a custom login page, create an API route to initiate the social auth flow:

mkdir -p app/api/auth/social/github
touch app/api/auth/social/github/route.ts

Add the following code to app/api/auth/social/github/route.ts:

import { NextRequest, NextResponse } from 'next/server'

const API_BASE_URL = process.env.OAUTH42_ISSUER || 'https://api.oauth42.com'

export async function POST(request: NextRequest) {
  try {
    const body = await request.json()

    const response = await fetch(`${API_BASE_URL}/api/social-auth/init`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        provider: 'github',
        client_id: body.client_id,
        is_signup: body.is_signup || true,
        state: body.state,
      }),
    })

    const data = await response.json()

    if (!response.ok) {
      return NextResponse.json(data, { status: response.status })
    }

    return NextResponse.json(data)
  } catch (error) {
    console.error('[Social Auth] Error:', error)
    return NextResponse.json(
      { error: 'Failed to initiate social auth' },
      { status: 500 }
    )
  }
}

Using Hosted Auth? Skip this step! OAuth42's hosted auth pages automatically include the GitHub Sign-In button when you enable the provider.

Step 7: Test GitHub Sign-In

  1. Start your application
  2. Navigate to your login page
  3. Click "Continue with GitHub"
  4. You'll be redirected to GitHub's authorization page
  5. Sign in and authorize the application
  6. GitHub redirects back to OAuth42
  7. OAuth42 creates/links your user and redirects to your app
  8. You're now logged in!

Success! Your users can now sign in with their GitHub accounts.

Understanding GitHub Email Access

GitHub has specific rules about email access that OAuth42 handles automatically:

Public Email

If the user has a public email set in their GitHub profile, OAuth42 uses that directly.

Private Email

If the email is private, OAuth42 uses the user:email scope to fetch the user's verified primary email from GitHub's email endpoint.

Verified Emails Only

OAuth42 only accepts verified email addresses from GitHub, ensuring account security.

How Account Linking Works

OAuth42 intelligently handles user accounts based on their GitHub profile:

New User (Signup)

A new user account is created with their GitHub profile info (name, email, avatar). The email is verified by GitHub.

Existing GitHub User (Login)

If the GitHub account ID is already linked to a user, they're logged into that existing account.

Existing Email User

If a user with the same email already exists (from email/password signup or another provider), the GitHub account is linked to that existing account.

Multiple Social Providers

Users can link multiple social providers (Google, Apple, GitHub, LinkedIn, X) to the same account, giving them flexibility in how they sign in.

Security Considerations

  • OAuth 2.0: GitHub uses standard OAuth 2.0, providing secure and reliable authentication
  • State Parameter: CSRF protection via cryptographically random state tokens
  • Encrypted Storage: GitHub client secrets are encrypted at rest using AES-256
  • Verified Emails: OAuth42 only accepts verified email addresses from GitHub
  • HTTPS Required: GitHub requires HTTPS for callback URLs (except localhost for development)

Troubleshooting

"Redirect URI mismatch" error

The callback URL doesn't match. Make sure you've set the exact OAuth42 callback URL in GitHub's OAuth App settings: https://api.oauth42.com/api/social-auth/callback

"GitHub social login not configured" error

The GitHub OAuth credentials are not configured for this application. Go to the OAuth42 Portal → Applications → Your App → Social Providers tab and verify that GitHub is configured with valid credentials.

"Failed to authenticate with GitHub" error

This usually means the Client ID or Client Secret is incorrect. Double-check your credentials in both the GitHub Developer Settings and OAuth42 Portal.

"No verified email" error

The user doesn't have a verified email on their GitHub account. They need to verify at least one email address in their GitHub settings.

Next Steps

Need Help?

Having trouble with GitHub Sign-In? Check our documentation or reach out to support.

Documentation →Discord →