Ponowne wykorzystanie tokena OpenID Connect

LibreChat obsługuje ponowne wykorzystywanie tokenów dostępu i odświeżania wydanych przez Twojego dostawcę OpenID Connect (takiego jak Azure Entra ID lub Auth0) w celu zarządzania stanem uwierzytelniania użytkownika. Gdy ta funkcja jest aktywna, token odświeżania przekazywany użytkownikowi jako plik cookie jest wydawany przez Twojego dostawcę OpenID zamiast przez LibreChat, co pozwala serwerom LibreChat na jego odświeżanie i żądanie tokenów dostępu od Twojego dostawcy.

Wymagania wstępne

• Skonfigurowany dostawca OpenID Connect (taki jak Azure Entra ID, Auth0 itp.)
• Podstawowa konfiguracja OpenID Connect zakończona

Kroki konfiguracji

1. Ustaw OPENID_REUSE_TOKENS=true w swoich zmiennych środowiskowych.

Konfiguracja specyficzna dla dostawcy

Konfiguracja Auth0

Dla Auth0 musisz:

1. Utwórz API w Auth0 (wymagane dla tokenów dostępu JWT):

   • Przejdź do Auth0 Dashboard → Applications → APIs
   • Kliknij "Create API"
   • Ustaw Identyfikator (np. https://api.librechat.com)
   • Włącz "Allow Offline Access" w ustawieniach API

2. Ustaw wymagane zmienne środowiskowe:

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

Aby uzyskać szczegółowe informacje na temat konfiguracji Auth0, zobacz: Auth0 OpenID Connect Configuration

Konfiguracja Azure Entra ID

2. Skonfiguruj swojego dostawcę OpenID (używając Azure Entra ID jako przykładu):
   • Przejdź do Azure Portal i przejdź do rejestracji swojej aplikacji
   • Kliknij „Expose API” w lewym menu
   • Kliknij "Add" obok "Application ID URI"
   • Wprowadź swój API URI (np. "api://librechat") i zapisz

3. Utwórz zakres API:
   • W sekcji "Expose API" kliknij "Add a scope"
   • Skonfiguruj zakres z odpowiednimi uprawnieniami
   • Zapisz konfigurację zakresu

4. Skonfiguruj uprawnienia API:
   • Przejdź do "API permissions" w menu po lewej stronie
   • Kliknij "Add a permission"
   • W sekcji "APIs my organization uses" wyszukaj swoją aplikację
   • Wybierz "Delegated permissions" i wybierz odpowiedni zakres (np. "access_user")

5. Ustaw wymagany zakres w swoim środowisku:

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

   Uwaga: Zakres offline_access jest wymagany do uzyskania tokena odświeżania w celu ponownego użycia.

6. Udziel zgody administratora:

   • Przejdź do Enterprise Applications w Azure Portal
   • Znajdź swoją aplikację LibreChat
   • Przejdź do Security > Permissions
   • Kliknij "Grant admin consent"

7. Zaakceptuj wymagane uprawnienia w wyskakującym okienku

8. Wyczyść pamięć podręczną LibreChat i zrestartuj usługę.

Zmienne środowiskowe

# 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

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

Dodatkowe opcje konfiguracji

• OPENID_AUDIENCE: Wartość odbiorcy (audience) dla walidacji JWT i żądań autoryzacji. Wymagane dla Auth0, aby otrzymywać tokeny dostępu JWT zamiast nieprzejrzystych tokenów (opaque tokens). W przypadku walidacji JWT akceptowane są wartości rozdzielone przecinkami; żądania autoryzacji używają pierwszej niepustej wartości.
• OPENID_REUSE_MAX_SESSION_AGE_MS: Maksymalny czas, po którym ponownie użyty token sesji OpenID jest serwowany, zanim LibreChat wymusi odświeżenie przez IdP (domyślnie: 900000 ms / 15 minut). Akceptuje wyrażenia arytmetyczne, takie jak 60 * 60 * 24 * 1000. Zwiększ tę wartość w kierunku czasu życia tokena dostępu swojego IdP, jeśli dostawca unieważnia poprzedni token dostępu przy każdym odświeżeniu.
• OPENID_JWKS_URL_CACHE_ENABLED: Włącza buforowanie wyników weryfikacji klucza podpisywania, aby zapobiec nadmiernej liczbie żądań HTTP do endpoint JWKS
• OPENID_JWKS_URL_CACHE_TIME: Czas trwania pamięci podręcznej w milisekundach (domyślnie: 600000 ms / 10 minut)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: Włącza przepływ on-behalf-of dla informacji o użytkowniku (specyficzne dla Azure)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: Zakres (scope) dla informacji o użytkowniku w przepływie on-behalf-of (specyficzne dla Azure)
• OPENID_USE_END_SESSION_ENDPOINT: Włącza użycie endpointu zakończenia sesji (end session endpoint) do wylogowania
• OPENID_MAX_LOGOUT_URL_LENGTH: Maksymalna długość adresu URL przed użyciem logout_hint zamiast id_token_hint, aby zapobiec błędom zbyt długiego URI (domyślnie: 2000)

Kwestie bezpieczeństwa

• Zapewnij odpowiednie przechowywanie i obsługę tokenów
• Wdróż odpowiednie mechanizmy odświeżania tokenów
• Monitoruj zużycie tokenów i w razie potrzeby wprowadź limity szybkości (rate limiting)
• Regularnie zmieniaj klucze tajne klienta (client secrets)
• Użyj bezpiecznych ustawień plików cookie do przechowywania tokenów

Rozwiązywanie problemów

Jeśli napotkasz problemy z ponownym użyciem tokenów:

1. Zweryfikuj, czy wszystkie wymagane zakresy (scopes) są poprawnie skonfigurowane
2. Sprawdź, czy udzielono zgody administratora
3. Upewnij się, że uprawnienia API są poprawnie skonfigurowane
4. Zweryfikuj, czy pamięć podręczna tokenów działa zgodnie z oczekiwaniami
5. Sprawdź logi aplikacji pod kątem błędów uwierzytelniania
6. Włącz szczegółowe logowanie nagłówków żądań OpenID, ustawiając DEBUG_OPENID_REQUESTS=true w swoich zmiennych środowiskowych, aby zobaczyć nagłówki żądań oprócz adresów URL (z zamaskowanymi danymi wrażliwymi).