Wiederverwendung von OpenID Connect-Tokens

LibreChat unterstützt die Wiederverwendung von Zugriffs- und Aktualisierungs-Tokens (Access und Refresh Tokens), die von Ihrem OpenID Connect-Anbieter (wie Azure Entra ID oder Auth0) ausgestellt wurden, um den Authentifizierungsstatus der Benutzer zu verwalten. Wenn diese Funktion aktiv ist, wird das an den Benutzer als Cookie übergebene Refresh Token von Ihrem OpenID-Anbieter anstelle von LibreChat ausgestellt, wodurch LibreChat-Server es aktualisieren und Zugriffs-Tokens von Ihrem Anbieter anfordern können.

Voraussetzungen

• Ein konfigurierter OpenID Connect-Anbieter (wie Azure Entra ID, Auth0, etc.)
• Grundlegende OpenID Connect-Einrichtung abgeschlossen

Konfigurationsschritte

1. Setze OPENID_REUSE_TOKENS=true in deinen Umgebungsvariablen.

Anbieter-spezifische Konfiguration

Auth0-Konfiguration

Für Auth0 müssen Sie:

1. Erstellen Sie eine API in Auth0 (erforderlich für JWT-Zugriffstokens):

   • Gehen Sie zu Auth0 Dashboard → Applications → APIs
   • Klicken Sie auf "Create API"
   • Legen Sie einen Identifier fest (z. B. https://api.librechat.com)
   • Aktivieren Sie "Allow Offline Access" in den API-Einstellungen

2. Legen Sie die erforderlichen Umgebungsvariablen fest:

   # Required for Auth0
   OPENID_AUDIENCE=https://api.librechat.com  # Your API identifier from Auth0
   OPENID_SCOPE=openid profile email offline_access

Für eine detaillierte Auth0-Konfiguration siehe: Auth0 OpenID Connect Configuration

Azure Entra ID Konfiguration

2. Konfigurieren Sie Ihren OpenID-Anbieter (unter Verwendung von Azure Entra ID als Beispiel):
   • Gehen Sie zum Azure Portal und navigieren Sie zu Ihrer App-Registrierung
   • Klicken Sie im linken Menü auf "Expose API"
   • Klicken Sie neben „Application ID URI“ auf „Add“
   • Geben Sie Ihren API-URI ein (z. B. "api://librechat") und speichern Sie ihn.

3. Erstellen Sie einen API-Scope:
   • Klicken Sie im Abschnitt "Expose API" auf "Add a scope"
   • Konfigurieren Sie den Bereich mit den entsprechenden Berechtigungen
   • Speichern Sie die Bereichskonfiguration

4. API-Berechtigungen konfigurieren:
   • Gehe im linken Menü zu "API permissions"
   • Klicke auf „Add a permission“
   • Suchen Sie unter „APIs my organization uses“ nach Ihrer App
   • Wählen Sie „Delegated permissions“ und wählen Sie den entsprechenden Bereich (z. B. „access_user“) aus.

5. Legen Sie den erforderlichen Scope in Ihrer Umgebung fest:

   OPENID_SCOPE=api://librechat/.default openid profile email offline_access

   Hinweis: Der offline_access Scope ist erforderlich, um ein Refresh Token zur Wiederverwendung zu erhalten.

6. Administrator-Zustimmung erteilen:

   • Gehe zu Enterprise Applications im Azure Portal
   • Finden Sie Ihre LibreChat-Anwendung
   • Navigieren Sie zu Security > Permissions
   • Klicken Sie auf "Grant admin consent"

7. Akzeptieren Sie die angeforderten Berechtigungen im Popup

8. Leeren Sie den LibreChat-Cache und starten Sie den Dienst neu.

Umgebungsvariablen

# OpenID Token Reuse Configuration
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=api://librechat/.default openid profile email offline_access
OPENID_REUSE_MAX_SESSION_AGE_MS=900000  # 15 minutes in milliseconds
 
# Required for Auth0 (use your API identifier)
# OPENID_AUDIENCE=https://api.librechat.com
 
# Caching Configuration
OPENID_JWKS_URL_CACHE_ENABLED=true
OPENID_JWKS_URL_CACHE_TIME=600000  # 10 minutes in milliseconds
 
# Azure-specific Configuration
OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE=user.read
 
# Logout Configuration
OPENID_USE_END_SESSION_ENDPOINT=true

Zusätzliche Konfigurationsoptionen

• OPENID_AUDIENCE: Audience-Wert für JWT-Validierung und Autorisierungsanfragen. Erforderlich für Auth0, um JWT-Zugriffstoken anstelle von opaken Token zu erhalten. Kommagetrennte Werte werden für die JWT-Validierung akzeptiert; Autorisierungsanfragen verwenden den ersten nicht leeren Wert.
• OPENID_REUSE_MAX_SESSION_AGE_MS: Maximales Alter eines wiederverwendeten OpenID-Sitzungstokens, bevor LibreChat eine IdP-Aktualisierung erzwingt (Standard: 900000 ms / 15 Minuten). Akzeptiert arithmetische Ausdrücke wie 60 * 60 * 24 * 1000. Erhöhen Sie diesen Wert in Richtung der Lebensdauer Ihres IdP-Zugriffstokens, falls Ihr Anbieter das vorherige Zugriffstoken bei jeder Aktualisierung widerruft.
• OPENID_JWKS_URL_CACHE_ENABLED: Aktiviert das Caching der Ergebnisse der Signaturschlüssel-Verifizierung, um übermäßige HTTP-Anfragen an den JWKS-endpoint zu verhindern
• OPENID_JWKS_URL_CACHE_TIME: Cache-Dauer in Millisekunden (Standard: 600000 ms / 10 Minuten)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: Aktiviert den On-Behalf-Of-Flow für Benutzerinformationen (Azure-spezifisch)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: Scope für Benutzerinformationen im On-Behalf-Of-Flow (Azure-spezifisch)
• OPENID_USE_END_SESSION_ENDPOINT: Aktiviert die Verwendung des End-Session-endpoint für die Abmeldung

Sicherheitsaspekte

• Stellen Sie eine ordnungsgemäße Speicherung und Handhabung von Token sicher
• Implementieren Sie geeignete Mechanismen zur Token-Aktualisierung
• Überwachen Sie die Token-Nutzung und implementieren Sie bei Bedarf ein Rate Limiting.
• Regelmäßig Client-Secrets rotieren
• Verwenden Sie sichere Cookie-Einstellungen für die Token-Speicherung

Fehlerbehebung

Falls Probleme bei der Token-Wiederverwendung auftreten:

1. Überprüfen Sie, ob alle erforderlichen Scopes ordnungsgemäß konfiguriert sind
2. Überprüfen Sie, ob die Administratorzustimmung erteilt wurde
3. Stellen Sie sicher, dass die API-Berechtigungen korrekt eingerichtet sind
4. Überprüfen Sie, ob der Token-Cache wie erwartet funktioniert
5. Überprüfen Sie die Anwendungsprotokolle auf Authentifizierungsfehler.
6. Aktivieren Sie die detaillierte Protokollierung der OpenID-Anfrage-Header, indem Sie DEBUG_OPENID_REQUESTS=true in Ihren Umgebungsvariablen setzen, um zusätzlich zu den URLs auch die Anfrage-Header zu sehen (wobei sensible Daten maskiert werden).