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

Solutions:
  • Check that environment variables are set correctly
  • Ensure .env file is in the correct directory (src/client/) for development
  • You can create a .env file to in the same directory as the docker-compose.yml file with the creds
Solutions:
  • Verify redirect URIs match exactly in OAuth app settings
  • Check port numbers (3001 vs 3000)
  • Ensure protocol matches (http/https)
Solutions:
  • Verify client credentials are copied correctly
  • Check for extra spaces or characters in environment variables
  • Ensure you’re using credentials from the correct OAuth app
Solutions:
  • Set NEXTAUTH_URL=http://localhost:3000 for development
  • Set NEXTAUTH_URL=https://yourdomain.com for production
  • Ensure the URL matches your actual application URL

Create a dashboard

Create custom visualizations with flexible widgets, queries, and real-time AI monitoring

Manage prompts

Version, deploy, and collaborate on prompts with centralized management and tracking

LLM playground

Compare cost, duration, and response tokens across different LLMs to find the most efficient model
Kubernetes

Running in Kubernetes? Try the OpenLIT Operator

Automatically inject instrumentation into existing workloads without modifying pod specs, container images, or application code.