LibreChat is joining ClickHouse to power the open-source Agentic Data Stack 🎉 Learn more
LibreChat

Auth0

Konfigurieren von Auth0 als OpenID Connect-Anbieter für LibreChat

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 der Anwendung:
    • Name: LibreChat (oder Ihr bevorzugter Name)
    • Anwendungstyp: Wählen Sie "Single Page Application"
  4. Klicken Sie auf "Create"

Schritt 2: Anwendungseinstellungen konfigurieren

HTTPS erforderlich

Auth0 erlaubt keine http://localhost-URLs in Produktionsanwendungen. Für die lokale Entwicklung/Tests müssen Sie HTTPS verwenden. Sie können Dienste nutzen wie:

  • ngrok: ngrok http 3080 (stellt einen HTTPS-Tunnel zu localhost bereit)
  • Caddy: Lokaler HTTPS-Proxy-Server
  • localtunnel: Ähnlich wie ngrok

Beispiel mit ngrok:

ngrok http 3080
# This will give you a URL like: https://abc123.ngrok.io
  1. In der Einstellungen-Registerkarte Ihrer Anwendung:
  2. Legen Sie die 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)

Wichtig für die Token-Wiederverwendung

Dieser Schritt ist erforderlich, wenn OPENID_REUSE_TOKENS=true verwendet wird. Ohne diesen Schritt gibt Auth0 opake Tokens zurück, die von LibreChat nicht validiert werden können, was zu endlosen Refresh-Schleifen führt.

  1. Gehe zum Auth0 Dashboard → Applications → APIs
  2. Klicken Sie auf "Create API"
  3. Konfigurieren der API:
    • Name: LibreChat API (oder Ihr bevorzugter Name)
    • Identifier: https://api.librechat.ai (oder Ihr bevorzugter Identifier)
      • Hinweis: Dies ist lediglich ein eindeutiger Bezeichner, keine tatsächliche URL. Er 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 sammeln

Im Abschnitt Basisinformationen 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)

Wichtig

Die in Auth0 angezeigte Domain enthält nicht das Präfix https://. Sie müssen es hinzufügen, wenn Sie OPENID_ISSUER konfigurieren.

Beispiel: Wenn Auth0 dev-abc123.us.auth0.com anzeigt, verwenden Sie https://dev-abc123.us.auth0.com

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

Verständnis von OPENID_AUDIENCE

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

KeyTypeDescriptionExample
OPENID_AUDIENCEstringDer Bezeichner Ihrer Auth0 API. Erforderlich bei der Verwendung von OPENID_REUSE_TOKENS=true mit Auth0, um Probleme mit opaken Tokens zu vermeiden. Kommagetrennte Werte werden für die JWT-Validierung akzeptiert; Autorisierungsanfragen verwenden den ersten nicht leeren Wert.OPENID_AUDIENCE=https://api.librechat.ai

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 Ihre Auth0-API-Kennung 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-Protokollierung 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

Wie finden Sie diese Anleitung?

Auf GitHub bearbeiten