Project: GitHub OAuth Gateway Setup

In this project, we will build a GitHub OAuth authentication gateway. We will implement token intercepts using Auth.js callbacks to map GitHub profile metadata to the application session payload.

1. Gateway Architecture Flow

graph TD
    A[User clicks GitHub Login] --> B[Redirects to GitHub OAuth page]
    B --> C[User approves permissions]
    C --> D[Auth.js Webhook intercept]
    D --> E[Execute JWT Callback]
    E --> F[Inject user metadata to Session]

2. Configuration Setup with Callbacks

Create your unified auth.ts setup defining provider options and intercept callbacks:

// auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    GitHub({
      clientId: process.env.AUTH_GITHUB_ID,
      clientSecret: process.env.AUTH_GITHUB_SECRET,
    }),
  ],
  callbacks: {
    // 1. Intercept JSON Web Token generation to save custom metadata
    async jwt({ token, profile }) {
      if (profile) {
        // Fetch properties from the social provider metadata
        token.githubId = profile.id;
        token.avatar_url = profile.avatar_url;
      }
      return token;
    },
    // 2. Make custom attributes accessible to the frontend components
    async session({ session, token }) {
      if (session.user) {
        session.user.githubId = token.githubId as number;
        session.user.image = token.avatar_url as string;
      }
      return session;
    },
  },
});

3. Frontend Trigger Component

Create a client-side button to launch the OAuth login gateway:

// app/login/page.tsx
"use client";

import React from "react";
import { signIn } from "next-auth/react";

export default function LoginPage() {
  return (
    <div className="max-w-md mx-auto p-8 border rounded-3xl bg-white shadow-sm mt-20 text-center">
      <h2 className="text-xl font-bold text-gray-950">Access Platform</h2>
      <p className="text-gray-400 text-xs mt-1">Connect your GitHub developer account to authenticate.</p>

      <button
        onClick={() => signIn("github", { redirectTo: "/dashboard" })}
        className="w-full bg-gray-950 text-white font-semibold py-3 rounded-lg text-sm mt-8 flex justify-center items-center gap-2"
      >
        Continue with GitHub
      </button>
    </div>
  );
}