Auth0

Questa guida ti accompagna nella configurazione di Auth0 come provider OpenID Connect per LibreChat.

Panoramica

Auth0 può essere utilizzato come provider OpenID Connect per LibreChat. Quando si utilizza Auth0 con il riutilizzo dei token abilitato (OPENID_REUSE_TOKENS=true), è necessario configurare la variabile d'ambiente OPENID_AUDIENCE per evitare problemi di autenticazione.

Prerequisiti

• Un account Auth0 con un tenant attivo
• Accesso amministratore per creare applicazioni e API in Auth0
• Istanza di LibreChat pronta per la configurazione

Passaggi di configurazione

Passaggio 1: Creare un'applicazione Auth0

1. Vai su Auth0 Dashboard → Applications → Applications
2. Fai clic su "Create Application"
3. Configura l'applicazione:
   • Nome: LibreChat (o il nome che preferisci)
   • Tipo di applicazione: Seleziona "Single Page Application"
4. Fai clic su "Create"

Passaggio 2: Configurare le impostazioni dell'applicazione

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

1. Nella scheda Settings della tua applicazione:
2. Imposta Allowed Callback URLs:

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

   (Usa il tuo URL ngrok per i test, o il tuo URL HTTPS di produzione)
3. Imposta Allowed Logout URLs (se utilizzi la fine della sessione):

   https://your-domain.ngrok.io

4. Imposta Allowed Web Origins:

   https://your-domain.ngrok.io

5. Salva le modifiche

Passaggio 3: Creare un'API Auth0 (Richiesto per il riutilizzo dei token)

1. Vai alla Dashboard di Auth0 → Applications → APIs
2. Fai clic su "Create API"
3. Configura l'API:
   • Nome: LibreChat API (o il nome che preferisci)
   • Identificativo: https://api.librechat.ai (o il tuo identificativo preferito)
     • Nota: Questo è solo un identificatore univoco, non un URL reale. Non è necessario che sia accessibile.
     • Modelli comuni: https://api.yourdomain.com, https://librechat.yourdomain.com, ecc.
   • Algoritmo di firma: RS256 (consigliato)
4. Clicca su "Create"

Passaggio 4: Configurare l'accesso offline

1. Vai alle Impostazioni della tua API → Impostazioni di Accesso
2. Abilita "Allow Offline Access"
3. Salva le modifiche

Passaggio 5: Raccogliere i valori di configurazione

Nella sezione Basic Information della tua applicazione Auth0, troverai:

• Dominio: Viene visualizzato come dev-example.us.auth0.com (dovrai aggiungere il prefisso https://)
• Client ID: Una lunga stringa alfanumerica
• Client Secret: Nascosto per impostazione predefinita (fai clic per rivelare)

Passaggio 6: Configurare le variabili d'ambiente di LibreChat

Aggiungi le seguenti variabili d'ambiente al tuo file .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

Comprendere OPENID_AUDIENCE

Il problema

Quando si utilizza Auth0 con OPENID_REUSE_TOKENS=true:

• Auth0 restituisce opaque access tokens (formato JWE) per impostazione predefinita
• LibreChat richiede token JWT firmati (formato JWS) che possano essere convalidati
• Senza una configurazione adeguata, questa discrepanza causa errori di autenticazione e cicli di aggiornamento infiniti.

La Soluzione

La variabile d'ambiente OPENID_AUDIENCE:

• Deve essere impostato sul tuo identificatore API Auth0 (creato nel Passaggio 3)
• Forza Auth0 a emettere token di accesso JWT firmati invece di token opachi
• Consente a LibreChat di convalidare i token utilizzando l'endpoint JWKS di Auth0
• Può contenere audience separate da virgole per la validazione JWT; le richieste di autorizzazione Auth0 utilizzano il primo valore non vuoto

Come funziona

Quando OPENID_AUDIENCE è configurato:

1. LibreChat include il parametro audience nelle richieste di autorizzazione, utilizzando il primo valore non vuoto quando sono configurate più audience separate da virgola.
2. Auth0 riconosce l'audience come una API registrata
3. Auth0 emette token di accesso JWT che possono essere convalidati
4. LibreChat convalida correttamente i token e l'autenticazione funziona in modo appropriato

Riferimento alle variabili d'ambiente

Risoluzione dei problemi

Ciclo di aggiornamento infinito

Sintomi: La pagina si ricarica continuamente dopo aver cliccato su "Continue with OpenID"

Soluzione:

1. Assicurati che OPENID_AUDIENCE sia impostato sul tuo identificatore API di Auth0
2. Verifica che l'API sia stata creata in Auth0 e che l'accesso offline sia abilitato
3. Verifica che il valore audience corrisponda esattamente

Errori di Token non valido

Sintomi: L'autenticazione fallisce con errori di validazione del token

Soluzione:

1. Abilita il logging di debug: DEBUG_OPENID_REQUESTS=true
2. Verifica che Auth0 stia restituendo token JWT (non token opachi)
3. Verifica che l'endpoint JWKS sia accessibile

Token di aggiornamento mancante

Sintomi: Nessun refresh token nella risposta di autenticazione

Soluzione:

1. Assicurati che offline_access sia incluso in OPENID_SCOPE
2. Verifica che "Allow Offline Access" sia abilitato nelle impostazioni dell'API Auth0

Best Practices

1. Usa sempre HTTPS - Auth0 richiede HTTPS per tutti gli URL di callback
2. Test in locale - Utilizza ngrok o servizi simili per creare tunnel HTTPS verso localhost
3. Proteggi il segreto della tua sessione - Utilizza un valore forte e casuale per OPENID_SESSION_SECRET
4. Abilita PKCE - Imposta OPENID_USE_PKCE=true per una maggiore sicurezza
5. Limita gli URL di callback - Consenti solo il tuo dominio effettivo nelle impostazioni di Auth0
6. Monitoraggio dei log - Utilizza DEBUG_OPENID_REQUESTS=true durante la configurazione
7. Identificativo API - Ricorda che è solo un identificativo, non un endpoint effettivo che deve esistere

Risorse aggiuntive

• Documentazione Auth0
• Token di accesso Auth0
• Riutilizzo del token OpenID di LibreChat