GitHub OAuth

This guide explains how to set up GitHub OAuth for user authentication in StarterKitPro using Auth.js v5.

Prerequisites

• Database Setup: Ensure you have configured and migrated your database, as Auth.js requires an adapter (like Prisma) to store user and account information. See the Database Setup documentation.

1. Environment Variables

Add the following variables to your .env.local file.

# Auth.js Core Variables (You might already have these)
AUTH_URL=http://localhost:3000 # Or your production URL like https://your-site.com
AUTH_SECRET= # Generate a strong secret: openssl rand -base64 32
 
# GitHub Provider Variables (Use these specific names for auto-configuration)
AUTH_GITHUB_ID=YOUR_GITHUB_CLIENT_ID
AUTH_GITHUB_SECRET=YOUR_GITHUB_CLIENT_SECRET

• AUTH_SECRET: A random string used to encrypt JWTs and session cookies. Use the command openssl rand -base64 32 in your terminal to generate a strong one. Do not commit this file.
• AUTH_URL: Set this to your canonical URL (e.g., http://localhost:3000 for development, https://your-site.com for production).
• Replace the AUTH_GITHUB_ placeholders with the actual credentials obtained from GitHub in the next steps.

2. GitHub OAuth App Setup

You need to register a new OAuth application on GitHub.

1. Navigate to Settings: Go to your GitHub profile settings.
2. Developer Settings: In the left sidebar, click Developer settings.
3. OAuth Apps: In the left sidebar, click OAuth Apps.
4. New OAuth App: Click the [New OAuth App] button.
5. Fill in Application Details:
   • Application name: Enter a name for your application (e.g., "StarterKitPro Dev" or "StarterKitPro Prod").
   • Homepage URL: Enter the URL of your application.
     • Development: http://localhost:3000
     • Production: https://your-domain.com
   • Application description (Optional): Briefly describe your application.
   • Authorization callback URL: This is crucial. It's where GitHub sends the user back after they authorize your application. It must match the pattern /api/auth/callback/[provider].
     • Development: http://localhost:3000/api/auth/callback/github
     • Production: https://your-domain.com/api/auth/callback/github
6. Register Application: Click [Register application].
7. Copy Credentials: On the next page, you'll see your Client ID. Click [Generate a new client secret]. Copy both the Client ID and the newly generated Client Secret. Paste them into your .env.local file as AUTH_GITHUB_ID and AUTH_GITHUB_SECRET.

3. Setup

Server Side

import GitHub from "next-auth/providers/github";
// ... other imports
 
export const authOptions = {
  // ... other options like adapter
  providers: [
    GitHub, // Auto-configured via environment variables
    // Or explicitly if using different ENV VAR names:
    // GitHub({
    //   clientId: process.env.YOUR_CUSTOM_GITHUB_ID_VAR,
    //   clientSecret: process.env.YOUR_CUSTOM_GITHUB_SECRET_VAR,
    // }),
    // ... other providers
  ],
  // ... rest of your config
};

Cient Side

// add this button to auth-form got github
<Button
  variant="outline"
  className="w-full"
  onClick={() => {
    setIsLoading(true);
    signIn("github", {
      redirect: false,
      callbackUrl: appConfig.auth.afterLogin,
    });
  }}
  disabled={isSubmitting || isLoading}
>
  {isLoading && <Loader2 className="animate-spin me-3" />}
  <Icons.github className="mr-2 size-7" />
  {type === "register" ? "Sign Up with Google" : "Login with Google"}
</Button>

4. Testing

• Restart Server: Stop and restart your development server (npm run dev).
• Sign In: Navigate to your application's sign-in page. You should now see a "Sign in with GitHub" option.
• Authorize: Click the button. You'll be redirected to GitHub to authorize the application. After authorization, you should be redirected back to your application, logged in.

Unlike Google, GitHub OAuth apps generally don't require a separate verification process for production use beyond correctly configuring the callback URLs.

You can now use GitHub for authentication in StarterKitPro!