This guide walks you through setting up OAuth authentication with Google and GitHub providers in OpenLIT using NextAuth.js.

​
Overview

OpenLIT supports OAuth authentication through NextAuth.js with these providers:
  • Google OAuth - Sign in with Google accounts
  • GitHub OAuth - Sign in with GitHub accounts
  • Email/Password - Traditional credentials-based authentication
NextAuth.js automatically handles:
  • OAuth 2.0 authorization flow
  • Token management and refresh
  • User session management
  • Security best practices
When users sign in via OAuth, OpenLIT automatically:
  • Creates new user accounts if they don’t exist
  • Links OAuth accounts to existing email-based accounts
  • Syncs profile information (name, profile picture)
  • Runs user setup and database configuration

​
Google OAuth Setup

​
1. Create Google Cloud Project

1

Access Google API Console

Visit the Google API Console to create OAuth 2.0 credentials.
2

Create or Select Project

  • Click on the project dropdown at the top
  • Click “New Project” or select an existing project
  • Give your project a meaningful name like “OpenLIT Authentication”
3

Enable Required APIs

  • Navigate to “APIs & Services” > “Library”
  • Search for and enable “Google+ API” or “People API”
  • This allows access to user profile information
1

Setup Consent Screen

  • Navigate to “APIs & Services” > “OAuth consent screen”
  • Choose “External” for user type (unless you have Google Workspace)
  • Fill in required information:
    • App name: OpenLIT
    • User support email: Your email address
    • Developer contact information: Your email address
2

Add Test Users (Development)

  • For testing, add email addresses that can access your app
  • Production apps will be available to all users once published

​
3. Create OAuth Credentials

1

Create Web Application Credentials

  • Navigate to “APIs & Services” > “Credentials”
  • Click “Create Credentials” > “OAuth client ID”
  • Select “Web application”
2

Configure Redirect URIs

As per NextAuth.js Google provider documentation:
  • Authorized JavaScript origins: 
    http://localhost:3000
https://yourdomain.com
  • Authorized redirect URIs: 
    http://localhost:3000/api/auth/callback/google
https://yourdomain.com/api/auth/callback/google
The redirect URIs must match exactly, including the port number (3000 in your case).
3

Save Credentials

  • Click “Create”
  • Copy the Client ID and Client Secret
  • Store them securely for environment configuration

​
GitHub OAuth Setup

​
1. Create GitHub OAuth App

1

Access GitHub Developer Settings

Go to GitHub Settings > Developer settings > OAuth Apps
2

Register New OAuth Application

Click “New OAuth App” and configure:
  • Application name: OpenLIT
  • Homepage URL: http://localhost:3000 (development) or https://yourdomain.com (production)
  • Authorization callback URL: 
    http://localhost:3000/api/auth/callback/github
As per NextAuth.js GitHub provider documentation, GitHub only allows one callback URL per Client ID/Secret.
3

Generate Client Secret

  • Click “Register application”
  • Copy the Client ID
  • Click “Generate a new client secret”
  • Copy the Client Secret immediately (it won’t be shown again)

​
2. GitHub App Permissions (Optional)

If creating a GitHub App instead of OAuth App, set “Email addresses” permission to read-only to access private email addresses as mentioned in the NextAuth.js documentation.

​
Environment Configuration

# NextAuth Configuration
NEXTAUTH_URL=https://yourdomain.com
NEXTAUTH_SECRET=your-production-secret

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id  
GITHUB_CLIENT_SECRET=your-github-client-secret

​
Production Setup

1

Update OAuth App URLs

Update both Google and GitHub OAuth apps with production URLs:
  • Google: Add https://yourdomain.com to origins and https://yourdomain.com/api/auth/callback/google to redirect URIs
  • GitHub: Update callback URL to https://yourdomain.com/api/auth/callback/github
2

HTTPS Requirement

Ensure your production domain has a valid SSL certificate. OAuth providers require HTTPS in production.

​
Features & Behavior

​
User Management

  • New Users: Automatically created when signing in via OAuth for the first time
  • Existing Users: OAuth accounts are linked to existing email-based accounts
  • Profile Sync: Name and profile picture are synced from OAuth providers
  • Database Setup: New users get proper database configurations and permissions

​
Session Management

NextAuth.js handles all session management including:
  • JWT token creation and validation
  • Session persistence across browser sessions
  • Automatic token refresh when needed
  • Secure cookie configuration

​
Troubleshooting

​
Common Issues

Integrations

Integrate your LLM Stack with OpenLIT

Connections

Connect to your existing Observablity Stack