GitHub OAuth

OAuth authentication for Express using GitHub — includes secure JWT issuance and user profile handling with TypeScript support.

authoauthgithubexpressjwttypescript

v2.1.0auth

Overview

A flexible OAuth authentication component for Express.js using GitHub as the provider. It handles the full flow — authorization redirect, token exchange, profile retrieval, and JWT issuance. Ideal for adding “Login with GitHub” functionality to any backend or Next.js app.

Installation

CLI

npx backternity add auth-oauth-github

What This Does

Installs a TypeScript-based GitHub OAuth 2.0 authentication flow with automatic JWT generation and user profile management.

Files & Folders Created

File / Path	Description
/src/routes/oauth.ts	Defines GitHub OAuth endpoints.
/src/controllers/oauthController.ts	Handles GitHub OAuth logic and callback processing.
/src/services/oauthService.ts	Manages token exchange, user retrieval, and JWT creation.
/src/models/OAuthUser.ts	Defines a typed in-memory user model.
/.env.example	Includes JWT, app, and GitHub credentials.

Files to be modified

File / Path	Description
server.ts	Mounts /api/oauth routes.
tsconfig.json	(optional) Ensures module resolution for @/ imports.

Configuration

# JWT Configuration
JWT_SECRET=your-super-secret-key
JWT_EXPIRES_IN=7d

# Application Settings
APP_URL=http://localhost:3000
PORT=3000

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
GITHUB_REDIRECT_URI=http://localhost:3000/api/oauth/github/callback

Frontend Integration

Below is a complete **Next.js** example that demonstrates GitHub OAuth login. After successful authentication, the backend returns a signed JWT and user profile.

GET/api/oauth/github

Redirects the user to GitHub for authorization.

GET/api/oauth/github/callback

Handles GitHub's callback, issues JWT, and returns the user profile.

Example

// app/components/GitHubLogin.jsx
'use client';
import { useState, useEffect } from 'react';

export default function GitHubLogin() {
  const [user, setUser] = useState(null);
  const [message, setMessage] = useState('');

  useEffect(() => {
    // Handle redirect after GitHub callback
    const params = new URLSearchParams(window.location.search);
    const token = params.get('token');
    if (token) {
      localStorage.setItem('accessToken', token);
      fetchUser(token);
    }
  }, []);

  async function fetchUser(token) {
    try {
      const res = await fetch('/api/auth/me', {
        headers: { Authorization: 'Bearer ' + token },
      });
      const data = await res.json();
      setUser(data.user);
    } catch {
      setMessage('Failed to fetch user profile.');
    }
  }

  function handleGitHubLogin() {
    window.location.href = '/api/oauth/github';
  }

  return (
    <div className="max-w-sm mx-auto bg-black/20 border border-white/10 rounded-xl p-6 text-white space-y-4">
      <h2 className="text-xl font-semibold">Login with GitHub</h2>

      {!user && (
        <button
          onClick={handleGitHubLogin}
          className="w-full bg-gray-800 hover:bg-gray-700 text-white font-semibold py-2 rounded-md transition-colors"
        >
          Continue with GitHub
        </button>
      )}

      {user && (
        <div className="p-3 bg-emerald-500/10 rounded-lg border border-emerald-500/20">
          <p className="text-sm text-emerald-300">✅ Logged in as {user.name}</p>
          <p className="text-xs text-white/70 mt-1">{user.email}</p>
          <p className="text-xs text-white/70 mt-1">
            GitHub ID: {user.oauthId}
          </p>
        </div>
      )}

      {message && <p className="text-amber-400 text-sm">{message}</p>}
    </div>
  );
}

Usage

// Example of protecting a route with the returned JWT
import express from 'express';
import jwt from 'jsonwebtoken';

const app = express();

function validateAuth(req, res, next) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer '))
    return res.status(401).json({ error: 'Missing token' });
  try {
    const token = header.split(' ')[1];
    req.user = jwt.verify(token, process.env.JWT_SECRET);
    next();
  } catch {
    res.status(401).json({ error: 'Invalid token' });
  }
}

app.get('/api/protected', validateAuth, (req, res) => {
  res.json({ message: 'Access granted', user: req.user });
});