> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openlit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

> Configure Google and GitHub OAuth authentication for OpenLIT using NextAuth.js

This guide walks you through setting up OAuth authentication with Google and GitHub providers in OpenLIT using [NextAuth.js](https://next-auth.js.org/).

## 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

<Steps>
  <Step title="Access Google API console">
    Visit the [Google API Console](https://console.cloud.google.com/) to create OAuth 2.0 credentials.
  </Step>

  <Step title="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"
  </Step>

  <Step title="Enable required APIs">
    * Navigate to "APIs & Services" > "Library"
    * Search for and enable "Google+ API" or "People API"
    * This allows access to user profile information
  </Step>
</Steps>

### 2. Configure OAuth consent screen

<Steps>
  <Step title="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
  </Step>

  <Step title="Add test users (Development)">
    * For testing, add email addresses that can access your app
    * Production apps will be available to all users once published
  </Step>
</Steps>

### 3. Create OAuth credentials

<Steps>
  <Step title="Create Web Application Credentials">
    * Navigate to "APIs & Services" > "Credentials"
    * Click "Create Credentials" > "OAuth client ID"
    * Select "Web application"
  </Step>

  <Step title="Configure redirect URIs">
    As per [NextAuth.js Google provider documentation](https://next-auth.js.org/providers/google):

    * **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
      ```

    <Warning>
      The redirect URIs must match exactly, including the port number (3000 in your case).
    </Warning>
  </Step>

  <Step title="Save credentials">
    * Click "Create"
    * Copy the **Client ID** and **Client Secret**
    * Store them securely for environment configuration
  </Step>
</Steps>

## GitHub OAuth setup

### 1. Create GitHub OAuth app

<Steps>
  <Step title="Access GitHub Developer Settings">
    Go to [GitHub Settings](https://github.com/settings/apps) > Developer settings > OAuth Apps
  </Step>

  <Step title="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
      ```

    <Note>
      As per [NextAuth.js GitHub provider documentation](https://next-auth.js.org/providers/github), GitHub only allows one callback URL per Client ID/Secret.
    </Note>
  </Step>

  <Step title="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)
  </Step>
</Steps>

### 2. GitHub app permissions (Optional)

<Note>
  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](https://next-auth.js.org/providers/github).
</Note>

## Environment Configuration

```.env.production theme={null}
# 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

<Steps>
  <Step title="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`
  </Step>

  <Step title="HTTPS requirement">
    Ensure your production domain has a valid SSL certificate. OAuth providers require HTTPS in production.
  </Step>
</Steps>

## 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

<AccordionGroup>
  <Accordion title="OAuth button not appearing">
    **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
  </Accordion>

  <Accordion title="Redirect URI mismatch error">
    **Solutions**:

    * Verify redirect URIs match exactly in OAuth app settings
    * Check port numbers (3001 vs 3000)
    * Ensure protocol matches (http/https)
  </Accordion>

  <Accordion title="Invalid client error">
    **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
  </Accordion>

  <Accordion title="NEXTAUTH_URL mismatch">
    **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
  </Accordion>
</AccordionGroup>

***

<CardGroup cols={3}>
  <Card title="Create a dashboard" href="/latest/openlit/dashboards/overview" icon="grid">
    Create custom visualizations with flexible widgets, queries, and real-time AI monitoring
  </Card>

  <Card title="Manage prompts" href="/latest/openlit/prompts-experiments/prompt-hub" icon="message">
    Version, deploy, and collaborate on prompts with centralized management and tracking
  </Card>

  <Card title="LLM playground" href="/latest/openlit/prompts-experiments/openground" icon="flask">
    Compare cost, duration, and response tokens across different LLMs to find the most efficient model
  </Card>
</CardGroup>

<Card title="Zero-code observability with the OpenLIT Controller" icon="tower-broadcast" href="/latest/controller/overview">
  Discover and instrument LLM traffic across Kubernetes, Docker, and Linux using eBPF — no code changes required.
</Card>