Riutilizzo del token OpenID Connect

LibreChat supporta il riutilizzo dei token di accesso e di aggiornamento rilasciati dal tuo provider OpenID Connect (come Azure Entra ID o Auth0) per gestire lo stato di autenticazione dell'utente. Quando questa funzionalità è attiva, il token di aggiornamento passato all'utente come cookie viene rilasciato dal tuo provider OpenID anziché da LibreChat, consentendo ai server LibreChat di aggiornarlo e richiedere token di accesso dal tuo provider.

Prerequisiti

• Un provider OpenID Connect configurato (come Azure Entra ID, Auth0, ecc.)
• Configurazione di base di OpenID Connect completata

Passaggi di configurazione

1. Imposta OPENID_REUSE_TOKENS=true nelle tue variabili d'ambiente.

Configurazione specifica del provider

Configurazione di Auth0

Per Auth0, devi:

1. Crea un'API in Auth0 (richiesta per i token di accesso JWT):

   • Vai su Auth0 Dashboard → Applications → APIs
   • Fai clic su "Create API"
   • Imposta un Identificatore (ad es. https://api.librechat.com)
   • Abilita "Allow Offline Access" nelle impostazioni dell'API

2. Imposta le variabili d'ambiente richieste:

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

Per una configurazione dettagliata di Auth0, consulta: Configurazione OpenID Connect di Auth0

Configurazione di Azure Entra ID

2. Configura il tuo provider OpenID (utilizzando Azure Entra ID come esempio):
   • Vai al portale Azure e naviga verso la registrazione della tua app
   • Fai clic su "Expose API" nel menu a sinistra
   • Fai clic su "Add" accanto a "Application ID URI"
   • Inserisci il tuo URI API (ad esempio, "api://librechat") e salva

3. Crea uno scope API:
   • Nella sezione "Expose API", fai clic su "Add a scope"
   • Configura l'ambito con le autorizzazioni appropriate
   • Salva la configurazione dell'ambito

4. Configura le autorizzazioni API:
   • Vai su "API permissions" nel menu a sinistra
   • Fai clic su "Add a permission"
   • Sotto "APIs my organization uses", cerca la tua app
   • Seleziona "Delegated permissions" e scegli l'ambito appropriato (ad esempio, "access_user")

5. Imposta l'ambito richiesto nel tuo ambiente:

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

   Nota: lo scope offline_access è richiesto per ottenere un refresh token da riutilizzare.

6. Concedi il consenso dell'amministratore:

   • Vai su Enterprise Applications nel portale Azure
   • Trova la tua applicazione LibreChat
   • Vai su Security > Permissions
   • Fai clic su "Grant admin consent"

7. Accetta le autorizzazioni richieste nel popup

8. Svuota la cache di LibreChat e riavvia il servizio.

Variabili d'ambiente

# 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

Opzioni di configurazione aggiuntive

• OPENID_AUDIENCE: Valore dell'audience per la convalida JWT e le richieste di autorizzazione. Obbligatorio per Auth0 per ricevere token di accesso JWT invece di token opachi. Sono accettati valori separati da virgola per la convalida JWT; le richieste di autorizzazione utilizzano il primo valore non vuoto.
• OPENID_REUSE_MAX_SESSION_AGE_MS: Età massima in cui un token di sessione OpenID riutilizzato viene servito prima che LibreChat forzi un aggiornamento dell'IdP (predefinito: 900000 ms / 15 minuti). Accetta espressioni aritmetiche come 60 * 60 * 24 * 1000. Aumentalo verso la durata del token di accesso del tuo IdP se il tuo provider revoca il token di accesso precedente ogni volta che viene aggiornato.
• OPENID_JWKS_URL_CACHE_ENABLED: Abilita la memorizzazione nella cache dei risultati di verifica della chiave di firma per evitare richieste HTTP eccessive all'endpoint JWKS
• OPENID_JWKS_URL_CACHE_TIME: Durata della cache in millisecondi (predefinito: 600000 ms / 10 minuti)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: Abilita il flusso on-behalf-of per le informazioni utente (specifico per Azure)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: Scope per le informazioni utente nel flusso on-behalf-of (specifico per Azure)
• OPENID_USE_END_SESSION_ENDPOINT: Abilita l'uso dell'endpoint di fine sessione per il logout
• OPENID_MAX_LOGOUT_URL_LENGTH: Lunghezza massima dell'URL prima di utilizzare logout_hint invece di id_token_hint per prevenire errori di URI troppo lungo (predefinito: 2000)

Considerazioni sulla sicurezza

• Assicurati che l'archiviazione e la gestione dei token siano corrette
• Implementare meccanismi appropriati di aggiornamento dei token
• Monitora l'utilizzo dei token e implementa il rate limiting se necessario
• Ruota regolarmente i client secret
• Utilizzare impostazioni dei cookie sicure per l'archiviazione dei token

Risoluzione dei problemi

Se riscontri problemi con il riutilizzo dei token:

1. Verifica che tutti gli scope richiesti siano configurati correttamente
2. Verifica che il consenso dell'amministratore sia stato concesso
3. Assicurati che le autorizzazioni API siano configurate correttamente
4. Verifica che la cache dei token funzioni come previsto
5. Controlla i log dell'applicazione per eventuali errori di autenticazione
6. Abilita la registrazione dettagliata delle intestazioni delle richieste OpenID impostando DEBUG_OPENID_REQUESTS=true nelle tue variabili d'ambiente per visualizzare le intestazioni delle richieste oltre agli URL (con i dati sensibili mascherati).