Auth0

Diese Anleitung führt Sie durch die Konfiguration von Auth0 als OpenID Connect-Anbieter für LibreChat.

Übersicht

Auth0 kann als OpenID Connect-Anbieter für LibreChat verwendet werden. Wenn Sie Auth0 mit aktivierter Token-Wiederverwendung (OPENID_REUSE_TOKENS=true) nutzen, müssen Sie die Umgebungsvariable OPENID_AUDIENCE konfigurieren, um Authentifizierungsprobleme zu vermeiden.

Voraussetzungen

• Ein Auth0-Konto mit einem aktiven Tenant
• Administratorzugriff zum Erstellen von Anwendungen und APIs in Auth0
• LibreChat Instanz bereit für die Konfiguration

Konfigurationsschritte

Schritt 1: Erstellen einer Auth0-Anwendung

1. Gehe zu Auth0 Dashboard → Applications → Applications
2. Klicken Sie auf "Create Application"
3. Konfigurieren Sie die Anwendung:
   • Name: LibreChat (oder Ihr bevorzugter Name)
   • Anwendungstyp: Wählen Sie "Single Page Application"
4. Klicken Sie auf "Create"

Schritt 2: Anwendungseinstellungen konfigurieren

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

1. Auf dem Einstellungen-Tab Ihrer Anwendung:
2. Legen Sie Allowed Callback URLs fest:

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

   (Verwenden Sie Ihre ngrok-URL zum Testen oder Ihre produktive HTTPS-URL)
3. Legen Sie Allowed Logout URLs fest (falls Sie die Sitzungsbeendigung verwenden):

   https://your-domain.ngrok.io

4. Legen Sie Allowed Web Origins fest:

   https://your-domain.ngrok.io

5. Speichere die Änderungen

Schritt 3: Erstellen einer Auth0-API (Erforderlich für die Token-Wiederverwendung)

1. Gehe zum Auth0 Dashboard → Applications → APIs
2. Klicken Sie auf „Create API“
3. API konfigurieren:
   • Name: LibreChat API (oder Ihr bevorzugter Name)
   • Identifier: https://api.librechat.ai (oder Ihr bevorzugter Identifier)
     • Hinweis: Dies ist lediglich eine eindeutige Kennung, keine tatsächliche URL. Sie muss nicht aufrufbar sein.
     • Gängige Muster: https://api.yourdomain.com, https://librechat.yourdomain.com usw.
   • Signaturalgorithmus: RS256 (empfohlen)
4. Klicken Sie auf „Create“

Schritt 4: Offline-Zugriff konfigurieren

1. Gehen Sie zu den Einstellungen Ihrer API → Zugriffseinstellungen
2. Aktivieren Sie "Allow Offline Access"
3. Speichere die Änderungen

Schritt 5: Konfigurationswerte zusammenstellen

Im Bereich Basic Information Ihrer Auth0-Anwendung finden Sie:

• Domain: Wird als dev-example.us.auth0.com angezeigt (Sie müssen das Präfix https:// hinzufügen)
• Client ID: Eine lange alphanumerische Zeichenfolge
• Client Secret: Standardmäßig ausgeblendet (zum Anzeigen klicken)

Schritt 6: Konfigurieren der LibreChat Umgebungsvariablen

Fügen Sie die folgenden Umgebungsvariablen zu Ihrer .env Datei hinzu:

# 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

# Maximum logout URL length before using logout_hint instead of id_token_hint (default: 2000)
# OPENID_MAX_LOGOUT_URL_LENGTH=2000

# 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

OPENID_AUDIENCE verstehen

Das Problem

Bei der Verwendung von Auth0 mit OPENID_REUSE_TOKENS=true:

• Auth0 gibt standardmäßig opaque access tokens (JWE-Format) zurück
• LibreChat erwartet signierte JWT-Tokens (JWS-Format), die validiert werden können
• Ohne ordnungsgemäße Konfiguration führt diese Diskrepanz zu Authentifizierungsfehlern und Endlosschleifen bei der Aktualisierung.

Die Lösung

Die OPENID_AUDIENCE Umgebungsvariable:

• Muss auf Ihren Auth0 API-Identifier (erstellt in Schritt 3) gesetzt werden
• Erzwingt, dass Auth0 signierte JWT-Zugriffstoken anstelle von opaken Token ausstellt
• Ermöglicht es LibreChat, Tokens mithilfe des JWKS-Endpunkts von Auth0 zu validieren
• Kann durch Kommas getrennte Zielgruppen für die JWT-Validierung enthalten; Auth0-Autorisierungsanfragen verwenden den ersten nicht leeren Wert

Funktionsweise

Wenn OPENID_AUDIENCE konfiguriert ist:

1. LibreChat enthält den audience-Parameter in Autorisierungsanfragen und verwendet den ersten nicht leeren Wert, wenn mehrere durch Kommas getrennte Audiences konfiguriert sind.
2. Auth0 erkennt die Audience als registrierte API an
3. Auth0 stellt JWT-Zugriffstoken aus, die validiert werden können
4. LibreChat validiert Token erfolgreich und die Authentifizierung funktioniert ordnungsgemäß

Referenz der Umgebungsvariablen

Fehlerbehebung

Endlose Aktualisierungsschleife

Symptome: Die Seite wird nach dem Klicken auf „Continue with OpenID“ kontinuierlich neu geladen

Lösung:

1. Stellen Sie sicher, dass OPENID_AUDIENCE auf Ihren Auth0 API-Identifier gesetzt ist.
2. Überprüfen Sie, ob die API in Auth0 erstellt wurde und der Offline-Zugriff aktiviert ist.
3. Überprüfen Sie, dass der audience-Wert exakt übereinstimmt

Fehler bei ungültigen Tokens

Symptome: Authentifizierung schlägt aufgrund von Token-Validierungsfehlern fehl

Lösung:

1. Debug-Logging aktivieren: DEBUG_OPENID_REQUESTS=true
2. Stellen Sie sicher, dass Auth0 JWT-Tokens (keine opaken Tokens) zurückgibt
3. Überprüfen, ob der JWKS endpoint erreichbar ist

Fehlendes Refresh Token

Symptome: Kein Refresh-Token in der Authentifizierungsantwort

Lösung:

1. Stellen Sie sicher, dass offline_access in OPENID_SCOPE enthalten ist.
2. Stellen Sie sicher, dass "Allow Offline Access" in Ihren Auth0 API-Einstellungen aktiviert ist.

Best Practices

1. Immer HTTPS verwenden – Auth0 erfordert HTTPS für alle Callback-URLs
2. Lokal testen - Verwenden Sie ngrok oder ähnliche Dienste, um HTTPS-Tunnel zu localhost zu erstellen
3. Sichern Sie Ihr Session-Secret - Verwenden Sie einen starken, zufälligen Wert für OPENID_SESSION_SECRET
4. PKCE aktivieren - Setzen Sie OPENID_USE_PKCE=true für erhöhte Sicherheit
5. Callback-URLs einschränken - Erlauben Sie in den Auth0-Einstellungen nur Ihre tatsächliche Domain
6. Logs überwachen - Verwenden Sie DEBUG_OPENID_REQUESTS=true während der Einrichtung
7. API-Bezeichner – Denken Sie daran, dass es sich nur um einen Bezeichner handelt, nicht um einen tatsächlichen endpoint, der existieren muss.

Zusätzliche Ressourcen

• Auth0-Dokumentation
• Auth0 Access Tokens
• LibreChat OpenID Token-Wiederverwendung