Auth0

Ten przewodnik przeprowadzi Cię przez proces konfiguracji Auth0 jako dostawcy OpenID Connect dla LibreChat.

Przegląd

Auth0 może być używany jako dostawca OpenID Connect dla LibreChat. W przypadku korzystania z Auth0 z włączoną funkcją ponownego użycia tokenów (OPENID_REUSE_TOKENS=true), należy skonfigurować zmienną środowiskową OPENID_AUDIENCE, aby zapobiec problemom z uwierzytelnianiem.

Wymagania wstępne

• Konto Auth0 z aktywnym dzierżawcą (tenant)
• Dostęp administratora do tworzenia aplikacji i API w Auth0
• Instancja LibreChat gotowa do konfiguracji

Kroki konfiguracji

Krok 1: Utwórz aplikację Auth0

1. Przejdź do Auth0 Dashboard → Applications → Applications
2. Kliknij "Create Application"
3. Skonfiguruj aplikację:
   • Nazwa: LibreChat (lub preferowana przez Ciebie nazwa)
   • Typ aplikacji: Wybierz "Single Page Application"
4. Kliknij "Create"

Krok 2: Konfiguracja ustawień aplikacji

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

1. W zakładce Settings swojej aplikacji:
2. Ustaw Allowed Callback URLs:

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

   (Użyj swojego adresu URL ngrok do testowania lub produkcyjnego adresu URL HTTPS)
3. Ustaw Allowed Logout URLs (jeśli używasz zakończenia sesji):

   https://your-domain.ngrok.io

4. Ustaw Allowed Web Origins:

   https://your-domain.ngrok.io

5. Zapisz zmiany

Krok 3: Utwórz API w Auth0 (Wymagane do ponownego użycia tokena)

1. Przejdź do Auth0 Dashboard → Applications → APIs
2. Kliknij "Create API"
3. Skonfiguruj API:
   • Nazwa: LibreChat API (lub preferowana przez Ciebie nazwa)
   • Identyfikator: https://api.librechat.ai (lub preferowany przez Ciebie identyfikator)
     • Uwaga: Jest to tylko unikalny identyfikator, a nie rzeczywisty URL. Nie musi on być dostępny.
     • Typowe wzorce: https://api.yourdomain.com, https://librechat.yourdomain.com itp.
   • Algorytm podpisywania: RS256 (zalecany)
4. Kliknij "Create"

Krok 4: Konfiguracja dostępu offline

1. Przejdź do ustawień swojego API → Ustawienia dostępu
2. Włącz "Allow Offline Access"
3. Zapisz zmiany

Krok 5: Zbierz wartości konfiguracyjne

W sekcji Basic Information swojej aplikacji Auth0 znajdziesz:

• Domain: Wyświetla się jako dev-example.us.auth0.com (będziesz musiał dodać prefiks https://)
• Client ID: Długi ciąg alfanumeryczny
• Client Secret: Ukryty domyślnie (kliknij, aby odkryć)

Krok 6: Konfiguracja zmiennych środowiskowych LibreChat

Dodaj następujące zmienne środowiskowe do swojego pliku .env:

# 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

Zrozumienie OPENID_AUDIENCE

Problem

Podczas korzystania z Auth0 z OPENID_REUSE_TOKENS=true:

• Auth0 domyślnie zwraca nieprzezroczyste tokeny dostępu (format JWE)
• LibreChat oczekuje podpisanych tokenów JWT (w formacie JWS), które można zweryfikować
• Bez odpowiedniej konfiguracji, ta niezgodność powoduje błędy uwierzytelniania i nieskończone pętle odświeżania.

Rozwiązanie

Zmienna środowiskowa OPENID_AUDIENCE:

• Musi być ustawione na twój identyfikator API Auth0 (utworzony w kroku 3)
• Wymusza na Auth0 wydawanie podpisanych tokenów dostępu JWT zamiast tokenów nieprzejrzystych (opaque tokens)
• Umożliwia LibreChat weryfikację tokenów przy użyciu punktu końcowego JWKS usługi Auth0
• Może zawierać oddzielone przecinkami grupy odbiorców (audiences) do walidacji JWT; żądania autoryzacji Auth0 używają pierwszej niepustej wartości

Jak to działa

Gdy OPENID_AUDIENCE jest skonfigurowane:

1. LibreChat uwzględnia parametr audience w żądaniach autoryzacji, używając pierwszej niepustej wartości, gdy skonfigurowano wiele odbiorców oddzielonych przecinkami.
2. Auth0 rozpoznaje odbiorcę (audience) jako zarejestrowane API
3. Auth0 wydaje tokeny dostępu JWT, które można zweryfikować
4. LibreChat pomyślnie weryfikuje tokeny, a uwierzytelnianie działa poprawnie

Referencja zmiennych środowiskowych

Rozwiązywanie problemów

Nieskończona pętla odświeżania

Objawy: Strona przeładowuje się w nieskończoność po kliknięciu "Continue with OpenID"

Rozwiązanie:

1. Upewnij się, że OPENID_AUDIENCE jest ustawione na identyfikator Twojego API Auth0
2. Zweryfikuj, czy API zostało utworzone w Auth0 oraz czy włączono dostęp offline (offline access).
3. Sprawdź, czy wartość audience zgadza się dokładnie

Błędy nieprawidłowego tokena

Objawy: Uwierzytelnianie kończy się niepowodzeniem z powodu błędów walidacji tokena

Rozwiązanie:

1. Włącz logowanie debugowania: DEBUG_OPENID_REQUESTS=true
2. Zweryfikuj, czy Auth0 zwraca tokeny JWT (a nie tokeny nieprzejrzyste)
3. Sprawdź, czy endpoint JWKS jest dostępny

Brakujący token odświeżania

Objawy: Brak tokena odświeżania (refresh token) w odpowiedzi uwierzytelniania

Rozwiązanie:

1. Upewnij się, że offline_access jest zawarte w OPENID_SCOPE
2. Zweryfikuj, czy opcja "Allow Offline Access" jest włączona w ustawieniach API Auth0

Najlepsze praktyki

1. Zawsze używaj HTTPS - Auth0 wymaga protokołu HTTPS dla wszystkich adresów URL wywołania zwrotnego (callback URLs)
2. Testowanie lokalne - Użyj ngrok lub podobnych usług, aby utworzyć tunele HTTPS do localhost
3. Zabezpiecz swój sekret sesji - Użyj silnej, losowej wartości dla OPENID_SESSION_SECRET
4. Włącz PKCE - Ustaw OPENID_USE_PKCE=true dla zwiększonego bezpieczeństwa
5. Ogranicz adresy URL wywołania zwrotnego (callback URLs) - Zezwalaj tylko na swoją rzeczywistą domenę w ustawieniach Auth0
6. Monitorowanie logów - Użyj DEBUG_OPENID_REQUESTS=true podczas konfiguracji
7. Identyfikator API - Pamiętaj, że to tylko identyfikator, a nie rzeczywisty endpoint, który musi istnieć

Dodatkowe zasoby

• Dokumentacja Auth0
• Tokeny dostępu Auth0
• Ponowne użycie tokena OpenID w LibreChat