Auth0

This guide walks you through configuring Auth0 as an OpenID Connect provider for LibreChat.

Overview

Auth0 can be used as an OpenID Connect provider for LibreChat. When using Auth0 with token reuse enabled (OPENID_REUSE_TOKENS=true), you must configure the OPENID_AUDIENCE environment variable to prevent authentication issues.

Prerequisites

• An Auth0 account with an active tenant
• Admin access to create applications and APIs in Auth0
• LibreChat instance ready for configuration

Configuration Steps

Step 1: Create an Auth0 Application

1. Go to Auth0 Dashboard → Applications → Applications
2. Click "Create Application"
3. Configure the application:
   • Name: LibreChat (or your preferred name)
   • Application Type: Select "Single Page Application"
4. Click "Create"

Step 2: Configure Application Settings

ngrok http 3080
# This will give you a URL like: https://abc123.ngrok.io

1. In your application's Settings tab:
2. Set Allowed Callback URLs:

   https://your-domain.ngrok.io/oauth/openid/callback

   (Use your ngrok URL for testing, or your production HTTPS URL)
3. Set Allowed Logout URLs (if using end session):

   https://your-domain.ngrok.io

4. Set Allowed Web Origins:

   https://your-domain.ngrok.io

5. Save the changes

Step 3: Create an Auth0 API (Required for Token Reuse)

1. Go to Auth0 Dashboard → Applications → APIs
2. Click "Create API"
3. Configure the API:
   • Name: LibreChat API (or your preferred name)
   • Identifier: https://api.librechat.ai (or your preferred identifier)
     • Note: This is just a unique identifier, not an actual URL. It doesn't need to be accessible.
     • Common patterns: https://api.yourdomain.com, https://librechat.yourdomain.com, etc.
   • Signing Algorithm: RS256 (recommended)
4. Click "Create"

Step 4: Configure Offline Access

1. Go to your API's Settings → Access Settings
2. Enable "Allow Offline Access"
3. Save the changes

Step 5: Gather Configuration Values

In your Auth0 Application's Basic Information section, you'll find:

• Domain: Shows as dev-example.us.auth0.com (you'll need to add https:// prefix)
• Client ID: A long alphanumeric string
• Client Secret: Hidden by default (click to reveal)

Step 6: Configure LibreChat Environment Variables

Add the following environment variables to your .env file:

# OpenID Connect Configuration
# Domain from Basic Information (add https:// prefix)
OPENID_ISSUER=https://dev-abc123.us.auth0.com
 
# Client ID from Basic Information
OPENID_CLIENT_ID=your_long_alphanumeric_client_id
 
# Client Secret from Basic Information (click to reveal)
OPENID_CLIENT_SECRET=your_client_secret_from_basic_information
 
# Callback URL (must match what's configured in Auth0)
OPENID_CALLBACK_URL=/oauth/openid/callback
 
# Token Configuration
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=openid profile email offline_access
 
# IMPORTANT: Your Auth0 API identifier (from Step 3)
OPENID_AUDIENCE=https://api.librechat.ai
 
# Security Settings (recommended)
OPENID_USE_PKCE=true
 
# Session Configuration (generate a secure random string)
OPENID_SESSION_SECRET=your-secure-session-secret-32-chars-or-more
 
# Optional: Custom button appearance
OPENID_BUTTON_LABEL=Continue with Auth0
# OPENID_IMAGE_URL=https://path-to-auth0-logo.png
 
# If using ngrok for testing, also update:
# DOMAIN_CLIENT=https://your-domain.ngrok.io
# DOMAIN_SERVER=https://your-domain.ngrok.io

Understanding OPENID_AUDIENCE

The Problem

When using Auth0 with OPENID_REUSE_TOKENS=true:

• Auth0 returns opaque access tokens (JWE format) by default
• LibreChat expects signed JWT tokens (JWS format) that can be validated
• Without proper configuration, this mismatch causes authentication failures and infinite refresh loops

The Solution

The OPENID_AUDIENCE environment variable:

• Must be set to your Auth0 API identifier (created in Step 3)
• Forces Auth0 to issue signed JWT access tokens instead of opaque tokens
• Enables LibreChat to validate tokens using Auth0's JWKS endpoint

How It Works

When OPENID_AUDIENCE is configured:

1. LibreChat includes the audience parameter in authorization requests
2. Auth0 recognizes the audience as a registered API
3. Auth0 issues JWT access tokens that can be validated
4. LibreChat successfully validates tokens and authentication works properly

Environment Variable Reference

Troubleshooting

Infinite Refresh Loop

Symptoms: Page reloads continuously after clicking "Continue with OpenID"

Solution:

1. Ensure OPENID_AUDIENCE is set to your Auth0 API identifier
2. Verify the API was created in Auth0 and offline access is enabled
3. Check that the audience value matches exactly

Invalid Token Errors

Symptoms: Authentication fails with token validation errors

Solution:

1. Enable debug logging: DEBUG_OPENID_REQUESTS=true
2. Verify Auth0 is returning JWT tokens (not opaque tokens)
3. Check JWKS endpoint is accessible

Missing Refresh Token

Symptoms: No refresh token in authentication response

Solution:

1. Ensure offline_access is included in OPENID_SCOPE
2. Verify "Allow Offline Access" is enabled in your Auth0 API settings

Best Practices

1. Always use HTTPS - Auth0 requires HTTPS for all callback URLs
2. Testing locally - Use ngrok or similar services to create HTTPS tunnels to localhost
3. Secure your session secret - Use a strong, random value for OPENID_SESSION_SECRET
4. Enable PKCE - Set OPENID_USE_PKCE=true for enhanced security
5. Restrict callback URLs - Only allow your actual domain in Auth0 settings
6. Monitor logs - Use DEBUG_OPENID_REQUESTS=true during setup
7. API Identifier - Remember it's just an identifier, not an actual endpoint that needs to exist

Additional Resources

• Auth0 Documentation
• Auth0 Access Tokens
• LibreChat OpenID Token Reuse