Auth0

Deze handleiding leidt je door het configureren van Auth0 als een OpenID Connect-provider voor LibreChat.

Overzicht

Auth0 kan worden gebruikt als een OpenID Connect-provider voor LibreChat. Wanneer je Auth0 gebruikt met token-hergebruik ingeschakeld (OPENID_REUSE_TOKENS=true), moet je de omgevingsvariabele OPENID_AUDIENCE configureren om authenticatieproblemen te voorkomen.

Vereisten

• Een Auth0-account met een actieve tenant
• Beheerdersrechten om applicaties en API's aan te maken in Auth0
• LibreChat-instantie klaar voor configuratie

Configuratiestappen

Stap 1: Maak een Auth0-applicatie

1. Ga naar Auth0 Dashboard → Applications → Applications
2. Klik op "Create Application"
3. Configureer de applicatie:
   • Naam: LibreChat (of de naam van jouw voorkeur)
   • Toepassingstype: Selecteer "Single Page Application"
4. Klik op "Create"

Stap 2: Applicatie-instellingen configureren

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

1. In het Settings tabblad van je applicatie:
2. Stel Allowed Callback URLs in:

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

   (Gebruik je ngrok URL voor het testen, of je productie HTTPS URL)
3. Stel Allowed Logout URLs in (indien u end session gebruikt):

   https://your-domain.ngrok.io

4. Stel Allowed Web Origins in:

   https://your-domain.ngrok.io

5. Sla de wijzigingen op

Stap 3: Maak een Auth0 API (Vereist voor Token Hergebruik)

1. Ga naar Auth0 Dashboard → Applications → APIs
2. Klik op "Create API"
3. Configureer de API:
   • Naam: LibreChat API (of de naam van uw voorkeur)
   • Identifier: https://api.librechat.ai (of uw gewenste identifier)
     • Let op: Dit is slechts een unieke identificatie, geen daadwerkelijke URL. Het hoeft niet toegankelijk te zijn.
     • Veelvoorkomende patronen: https://api.yourdomain.com, https://librechat.yourdomain.com, enz.
   • Signing Algorithm: RS256 (aanbevolen)
4. Klik op "Create"

Stap 4: Offline toegang configureren

1. Ga naar de instellingen van je API → Toegangsinstellingen
2. Schakel "Allow Offline Access" in
3. Sla de wijzigingen op

Stap 5: Configuratie-waarden verzamelen

In de sectie Basic Information van je Auth0-applicatie vind je:

• Domain: Wordt weergegeven als dev-example.us.auth0.com (je moet het https:// voorvoegsel toevoegen)
• Client ID: Een lange alfanumerieke reeks
• Client Secret: Standaard verborgen (klik om te onthullen)

Stap 6: Configureer LibreChat omgevingsvariabelen

Voeg de volgende omgevingsvariabelen toe aan je .env bestand:

# 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

OPENID_AUDIENCE begrijpen

Het probleem

Bij gebruik van Auth0 met OPENID_REUSE_TOKENS=true:

• Auth0 retourneert standaard opaque access tokens (JWE-formaat)
• LibreChat verwacht ondertekende JWT-tokens (JWS-formaat) die gevalideerd kunnen worden
• Zonder de juiste configuratie veroorzaakt dit verschil authenticatiefouten en oneindige vernieuwingslussen.

De Oplossing

De OPENID_AUDIENCE omgevingsvariabele:

• Moet worden ingesteld op uw Auth0 API-identifier (aangemaakt in Stap 3)
• Dwingt Auth0 om ondertekende JWT-toegangstokens uit te geven in plaats van ondoorzichtige tokens
• Stelt LibreChat in staat om tokens te valideren met behulp van het JWKS-endpoint van Auth0
• Kan door komma's gescheiden audiences bevatten voor JWT-validatie; Auth0-autorisatieverzoeken gebruiken de eerste niet-lege waarde

Hoe het werkt

Wanneer OPENID_AUDIENCE is geconfigureerd:

1. LibreChat bevat de audience parameter in autorisatieverzoeken, waarbij de eerste niet-lege waarde wordt gebruikt wanneer er meerdere door komma's gescheiden audiences zijn geconfigureerd.
2. Auth0 herkent de audience als een geregistreerde API
3. Auth0 geeft JWT-toegangstokens uit die gevalideerd kunnen worden
4. LibreChat valideert tokens succesvol en authenticatie werkt naar behoren

Referentie voor omgevingsvariabelen

Probleemoplossing

Oneindige verversingslus

Symptomen: Pagina wordt continu opnieuw geladen na het klikken op "Continue with OpenID"

Oplossing:

1. Zorg ervoor dat OPENID_AUDIENCE is ingesteld op je Auth0 API-identifier
2. Controleer of de API is aangemaakt in Auth0 en of offline toegang is ingeschakeld
3. Controleer of de audience-waarde exact overeenkomt

Ongeldige Tokenfouten

Symptomen: Authenticatie mislukt met token-validatiefouten

Oplossing:

1. Schakel debug-logging in: DEBUG_OPENID_REQUESTS=true
2. Controleer of Auth0 JWT-tokens retourneert (geen opaque tokens)
3. Controleer of het JWKS endpoint toegankelijk is

Ontbrekende Refresh Token

Symptomen: Geen refresh token in authenticatie-antwoord

Oplossing:

1. Zorg ervoor dat offline_access is opgenomen in OPENID_SCOPE
2. Controleer of "Allow Offline Access" is ingeschakeld in uw Auth0 API-instellingen

Best Practices

1. Gebruik altijd HTTPS - Auth0 vereist HTTPS voor alle callback-URL's
2. Lokaal testen - Gebruik ngrok of vergelijkbare services om HTTPS-tunnels naar localhost te maken
3. Beveilig je sessiegeheim - Gebruik een sterke, willekeurige waarde voor OPENID_SESSION_SECRET
4. PKCE inschakelen - Stel OPENID_USE_PKCE=true in voor verbeterde beveiliging
5. Callback-URL's beperken - Sta alleen uw eigenlijke domein toe in de Auth0-instellingen
6. Monitor logs - Gebruik DEBUG_OPENID_REQUESTS=true tijdens de installatie
7. API-identificatie - Onthoud dat dit slechts een identificatie is, niet een daadwerkelijk endpoint dat moet bestaan

Aanvullende bronnen

• Auth0-documentatie
• Auth0 Access Tokens
• LibreChat OpenID Token Hergebruik