OpenID Connect Token Hergebruik

LibreChat ondersteunt het hergebruik van access- en refresh-tokens die zijn uitgegeven door uw OpenID Connect-provider (zoals Azure Entra ID of Auth0) om de authenticatiestatus van gebruikers te beheren. Wanneer deze functie actief is, wordt het refresh-token dat als cookie aan de gebruiker wordt doorgegeven, uitgegeven door uw OpenID-provider in plaats van door LibreChat, waardoor LibreChat-servers dit kunnen vernieuwen en access-tokens kunnen opvragen bij uw provider.

Vereisten

• Een geconfigureerde OpenID Connect-provider (zoals Azure Entra ID, Auth0, enz.)
• Basis OpenID Connect-configuratie voltooid

Configuratiestappen

1. Stel OPENID_REUSE_TOKENS=true in in je omgevingsvariabelen.

Provider-Specifieke Configuratie

Auth0-configuratie

Voor Auth0 moet je het volgende doen:

1. Maak een API aan in Auth0 (vereist voor JWT-toegangstokens):

   • Ga naar Auth0 Dashboard → Applications → APIs
   • Klik op "Create API"
   • Stel een Identifier in (bijv. https://api.librechat.com)
   • Schakel "Allow Offline Access" in bij de API-instellingen

2. Stel de vereiste omgevingsvariabelen in:

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

Voor gedetailleerde Auth0-configuratie, zie: Auth0 OpenID Connect Configuration

Azure Entra ID Configuratie

2. Configureer uw OpenID-provider (met Azure Entra ID als voorbeeld):
   • Ga naar de Azure Portal en navigeer naar je app-registratie
   • Klik op "Expose API" in het linkermenu
   • Klik op "Add" naast "Application ID URI"
   • Voer uw API URI in (bijv. "api://librechat") en sla op

3. Maak een API-scope aan:
   • Klik in de sectie "Expose API" op "Add a scope"
   • Configureer het bereik met de juiste rechten
   • Sla de scope-configuratie op

4. Configureer API-rechten:
   • Ga naar "API permissions" in het linkermenu
   • Klik op "Add a permission"
   • Zoek onder "APIs my organization uses" naar je app
   • Selecteer "Delegated permissions" en kies het juiste bereik (bijv. "access_user")

5. Stel het vereiste bereik in uw omgeving in:

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

   Let op: De offline_access scope is vereist om een refresh token te verkrijgen voor hergebruik.

6. Beheerderstoestemming verlenen:

   • Ga naar Enterprise Applications in Azure Portal
   • Vind uw LibreChat-applicatie
   • Navigeer naar Security > Permissions
   • Klik op "Grant admin consent"

7. Accepteer de gevraagde machtigingen in de pop-up

8. Wis de LibreChat-cache en herstart de service.

Omgevingsvariabelen

# 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

Aanvullende configuratieopties

• OPENID_AUDIENCE: Audience-waarde voor JWT-validatie en autorisatieverzoeken. Vereist voor Auth0 om JWT-toegangstokens te ontvangen in plaats van ondoorzichtige tokens. Door komma's gescheiden waarden worden geaccepteerd voor JWT-validatie; autorisatieverzoeken gebruiken de eerste niet-lege waarde.
• OPENID_REUSE_MAX_SESSION_AGE_MS: Maximale leeftijd van een hergebruikt OpenID-sessietoken voordat LibreChat een IdP-verversing afdwingt (standaard: 900000 ms / 15 minuten). Accepteert rekenkundige expressies zoals 60 * 60 * 24 * 1000. Verhoog deze waarde richting de levensduur van je IdP-toegangstoken als je provider het vorige toegangstoken intrekt telkens wanneer het wordt ververst.
• OPENID_JWKS_URL_CACHE_ENABLED: Schakelt caching van verificatieresultaten van ondertekeningssleutels in om overmatige HTTP-verzoeken naar het JWKS endpoint te voorkomen
• OPENID_JWKS_URL_CACHE_TIME: Cacheduur in milliseconden (standaard: 600000 ms / 10 minuten)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: Schakelt on-behalf-of flow in voor gebruikersinformatie (Azure-specifiek)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: Scope voor gebruikersinformatie in on-behalf-of flow (Azure-specifiek)
• OPENID_USE_END_SESSION_ENDPOINT: Schakelt het gebruik van het end session endpoint in voor uitloggen
• OPENID_MAX_LOGOUT_URL_LENGTH: Maximale URL-lengte voordat logout_hint wordt gebruikt in plaats van id_token_hint om fouten door een te lange URI te voorkomen (standaard: 2000)

Beveiligingsoverwegingen

• Zorg voor een correcte opslag en afhandeling van tokens
• Implementeer geschikte mechanismen voor tokenvernieuwing
• Monitor tokengebruik en implementeer indien nodig rate limiting
• Roteer regelmatig client secrets
• Gebruik veilige cookie-instellingen voor tokenopslag

Probleemoplossing

Als je problemen ondervindt met token-hergebruik:

1. Controleer of alle vereiste scopes correct zijn geconfigureerd
2. Controleer of er admin-toestemming is verleend
3. Zorg ervoor dat de API-rechten correct zijn ingesteld
4. Controleer of de token-cache werkt zoals verwacht
5. Controleer de applicatielogs op eventuele authenticatiefouten
6. Schakel gedetailleerde OpenID-request header logging in door DEBUG_OPENID_REQUESTS=true in te stellen in je omgevingsvariabelen om naast URL's ook request headers te zien (waarbij gevoelige gegevens worden gemaskeerd).