Auth0

Ce guide vous accompagne dans la configuration d'Auth0 en tant que fournisseur OpenID Connect pour LibreChat.

Aperçu

Auth0 peut être utilisé comme fournisseur OpenID Connect pour LibreChat. Lorsque vous utilisez Auth0 avec la réutilisation de jetons activée (OPENID_REUSE_TOKENS=true), vous devez configurer la variable d'environnement OPENID_AUDIENCE pour éviter les problèmes d'authentification.

Prérequis

• Un compte Auth0 avec un tenant actif
• Accès administrateur pour créer des applications et des API dans Auth0
• Instance LibreChat prête pour la configuration

Étapes de configuration

Étape 1 : Créer une application Auth0

1. Allez dans Auth0 Dashboard → Applications → Applications
2. Cliquez sur "Create Application"
3. Configurez l'application :
   • Nom : LibreChat (ou le nom de votre choix)
   • Type d'application : Sélectionnez "Single Page Application"
4. Cliquez sur "Create"

Étape 2 : Configurer les paramètres de l'application

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

1. Dans l'onglet Settings de votre application :
2. Définissez les Allowed Callback URLs :

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

   (Utilisez votre URL ngrok pour les tests, ou votre URL HTTPS de production)
3. Définissez les Allowed Logout URLs (si vous utilisez la fin de session) :

   https://your-domain.ngrok.io

4. Définissez les Allowed Web Origins :

   https://your-domain.ngrok.io

5. Enregistrer les modifications

Étape 3 : Créer une API Auth0 (Requis pour la réutilisation de jetons)

1. Allez sur le tableau de bord Auth0 → Applications → APIs
2. Cliquez sur "Create API"
3. Configurer l'API :
   • Nom : LibreChat API (ou le nom de votre choix)
   • Identifiant : https://api.librechat.ai (ou votre identifiant préféré)
     • Note : Il s'agit simplement d'un identifiant unique, et non d'une URL réelle. Il n'a pas besoin d'être accessible.
     • Modèles courants : https://api.yourdomain.com, https://librechat.yourdomain.com, etc.
   • Algorithme de signature : RS256 (recommandé)
4. Cliquez sur "Create"

Étape 4 : Configurer l'accès hors ligne

1. Allez dans les paramètres de votre API → Paramètres d'accès
2. Activer "Allow Offline Access"
3. Enregistrer les modifications

Étape 5 : Rassembler les valeurs de configuration

Dans la section Basic Information de votre application Auth0, vous trouverez :

• Domaine : S'affiche sous la forme dev-example.us.auth0.com (vous devrez ajouter le préfixe https://)
• Client ID : Une longue chaîne alphanumérique
• Client Secret : Masqué par défaut (cliquez pour révéler)

Étape 6 : Configurer les variables d'environnement de LibreChat

Ajoutez les variables d'environnement suivantes à votre fichier .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
 
# 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

Comprendre OPENID_AUDIENCE

Le problème

Lors de l'utilisation d'Auth0 avec OPENID_REUSE_TOKENS=true :

• Auth0 renvoie des opaque access tokens (format JWE) par défaut
• LibreChat attend des jetons JWT signés (format JWS) qui peuvent être validés
• Sans une configuration appropriée, cette inadéquation provoque des échecs d'authentification et des boucles de rafraîchissement infinies.

La solution

La variable d'environnement OPENID_AUDIENCE :

• Doit être défini sur votre identifiant d'API Auth0 (créé à l'étape 3)
• Force Auth0 à émettre des jetons d'accès JWT signés au lieu de jetons opaques
• Permet à LibreChat de valider les jetons en utilisant l'endpoint JWKS d'Auth0
• Peut contenir des audiences séparées par des virgules pour la validation JWT ; les requêtes d'autorisation Auth0 utilisent la première valeur non vide

Comment ça fonctionne

Lorsque OPENID_AUDIENCE est configuré :

1. LibreChat inclut le paramètre audience dans les requêtes d'autorisation, en utilisant la première valeur non vide lorsque plusieurs audiences séparées par des virgules sont configurées.
2. Auth0 reconnaît l'audience comme une API enregistrée
3. Auth0 émet des jetons d'accès JWT qui peuvent être validés
4. LibreChat valide les jetons avec succès et l'authentification fonctionne correctement

Référence des variables d'environnement

Dépannage

Boucle de rafraîchissement infinie

Symptômes : La page se recharge en continu après avoir cliqué sur « Continue with OpenID »

Solution :

1. Assurez-vous que OPENID_AUDIENCE est défini sur votre identifiant d'API Auth0
2. Vérifiez que l'API a été créée dans Auth0 et que l'accès hors ligne (offline access) est activé
3. Vérifiez que la valeur de l'audience correspond exactement

Erreurs de jeton invalide

Symptômes : L'authentification échoue avec des erreurs de validation de jeton

Solution :

1. Activer la journalisation de débogage : DEBUG_OPENID_REQUESTS=true
2. Vérifiez qu'Auth0 renvoie des jetons JWT (et non des jetons opaques)
3. Vérifier que le endpoint JWKS est accessible

Jeton de rafraîchissement manquant

Symptômes : Aucun jeton d'actualisation (refresh token) dans la réponse d'authentification

Solution :

1. Assurez-vous que offline_access est inclus dans OPENID_SCOPE
2. Vérifiez que "Allow Offline Access" est activé dans vos paramètres d'API Auth0

Bonnes pratiques

1. Toujours utiliser HTTPS - Auth0 nécessite HTTPS pour toutes les URL de rappel (callback URLs)
2. Test en local - Utilisez ngrok ou des services similaires pour créer des tunnels HTTPS vers localhost
3. Sécurisez votre secret de session - Utilisez une valeur forte et aléatoire pour OPENID_SESSION_SECRET
4. Activer PKCE - Définissez OPENID_USE_PKCE=true pour une sécurité renforcée
5. Restreindre les URLs de rappel - N'autorisez que votre domaine réel dans les paramètres Auth0
6. Surveiller les journaux - Utilisez DEBUG_OPENID_REQUESTS=true lors de la configuration
7. Identifiant API - N'oubliez pas qu'il s'agit simplement d'un identifiant, et non d'un endpoint réel qui doit exister

Ressources supplémentaires

• Documentation Auth0
• Jetons d'accès Auth0
• Réutilisation de jeton OpenID LibreChat