Skip to main content
This guide walks you through setting up sign-in with Google, GitHub, Microsoft, and Okta in OpenLIT using NextAuth.js.

​
Overview

OpenLIT supports these sign-in methods:
  • Google - Sign in with Google accounts
  • GitHub - Sign in with GitHub accounts
  • Microsoft - Sign in with Microsoft Entra ID (work, school, or personal Microsoft accounts)
  • Okta - Sign in through your Okta organisation
  • Email/Password - Traditional credentials-based authentication
Each provider is configured with environment variables, in both the community edition and OpenLIT Enterprise. A provider’s button appears on the sign-in page only when all of its required values are set. Prefix each redirect URI with your OpenLIT URL, for example https://openlit.example.com/api/auth/callback/okta.
In OpenLIT Enterprise, the instance admin can also set and test these values from Instance admin → Auth without redeploying. See Instance admin.
NextAuth.js automatically handles:
  • OAuth 2.0 authorization flow
  • Token management and refresh
  • User session management
  • Security best practices
When users sign in with a provider, OpenLIT automatically:
  • Creates new user accounts if they don’t exist
  • Links the provider to an existing account with the same email, when the provider has verified that email (see Account linking)
  • 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:
  • Authorized redirect URIs:
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:
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.

​
Microsoft setup

1

Register an application

In the Microsoft Entra admin center, go to Identity > Applications > App registrations and select New registration.
  • Name: OpenLIT
  • Supported account types: choose Accounts in this organizational directory only to limit sign-in to your organisation, or a multi-tenant option to accept other directories
  • Redirect URI: select Web and enter https://yourdomain.com/api/auth/callback/azure-ad (use http://localhost:3000/api/auth/callback/azure-ad for local development)
2

Copy the IDs

On the app’s Overview page, copy the Application (client) ID for AZURE_AD_CLIENT_ID, and the Directory (tenant) ID for AZURE_AD_TENANT_ID.
3

Create a client secret

Go to Certificates & secrets > Client secrets > New client secret. Copy the secret Value (not the secret ID) for AZURE_AD_CLIENT_SECRET. It’s shown only once.
4

Choose the tenant

  • Set AZURE_AD_TENANT_ID to your directory ID or a verified domain to accept only your organisation. This is recommended.
  • Leave it unset (or set common) to accept any Microsoft account. organizations accepts any work or school account, and consumers accepts only personal Microsoft accounts.
With common, organizations, or consumers, anyone with a Microsoft account can create an OpenLIT account. OpenLIT doesn’t trust the email from these sign-ins to link to an existing account, because the admin of any directory can set it. Set a single directory if your users already have OpenLIT accounts and should be able to sign in with Microsoft.

​
Okta setup

1

Create an app integration

In the Okta Admin Console, go to Applications > Applications > Create App Integration. Select OIDC - OpenID Connect and Web Application.
2

Configure the redirect URI

  • Sign-in redirect URIs: https://yourdomain.com/api/auth/callback/okta (use http://localhost:3000/api/auth/callback/okta for local development)
  • Assignments: assign the users or groups who should be able to sign in to OpenLIT
3

Copy the credentials

From the app’s General tab, copy the Client ID for OKTA_CLIENT_ID and the Client secret for OKTA_CLIENT_SECRET. Keep Client authentication set to Client secret.
4

Find the issuer

Go to Security > API > Authorization Servers and copy the Issuer URI of the server you use, for example https://your-domain.okta.com/oauth2/default. Set it as OKTA_ISSUER. The issuer must be a public https URL.

​
Environment Configuration

​
Production Setup

1

Update OAuth app URLs

Update each provider’s app 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
  • Microsoft: Add https://yourdomain.com/api/auth/callback/azure-ad as a Web redirect URI
  • Okta: Add https://yourdomain.com/api/auth/callback/okta as a sign-in redirect URI
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 with a provider for the first time
  • Existing Users: A provider is linked to an existing account with the same email when the provider has verified the email (see below)
  • Profile Sync: Name and profile picture are synced from the provider when the account doesn’t have them yet
  • Database Setup: New users get proper database configurations and permissions

​
Account linking

When someone signs in with a provider and an OpenLIT account already uses that email, OpenLIT links the provider to that account only when the provider vouches for the email: Otherwise the sign-in is refused and the user sees a message to sign in with the method they used originally. A provider identity that is already linked to the account can always sign in. If a provider reports an email as unverified, the sign-in is refused even when no account uses that email.

​
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 every required variable for the provider is set. For example, Okta needs OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, and OKTA_ISSUER
  • Check that environment variables are set correctly
  • In OpenLIT Enterprise, open Instance admin → Auth: each provider shows Shown on sign-in, Incomplete (with the missing fields), or Not configured
  • 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:
  • In OpenLIT Enterprise, use Test credentials on Instance admin → Auth to check the values with the provider
  • For Microsoft, use the client secret Value, not the secret ID, and check that the secret hasn’t expired
  • 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:
  • The provider didn’t verify the email, so OpenLIT won’t link it to the existing account. See Account linking
  • For Microsoft, set AZURE_AD_TENANT_ID to your directory instead of common
  • Sign in with the method the account used originally (for example, email and password)
Solutions:
  • Use the full issuer URI from Security > API > Authorization Servers, such as https://your-domain.okta.com/oauth2/default
  • The issuer must use https and a public hostname. IP addresses, localhost, and private network addresses are rejected
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