Overview

This section will cover how to configure OAuth2 and OpenID Connect with LibreChat

OAuth2

• Apple
• Discord
• Facebook
• GitHub
• Google

OpenID Connect

• Auth0
• AWS Cognito
• Azure Entra/AD
• Keycloak
• Re-use OpenID Tokens for Login Session

OpenID JWT User Cache

High-request-rate deployments can set AUTH_USER_CACHE_MODE=on to cache the user document resolved for OpenID JWT authentication for five seconds. This reduces repeated database reads during short request bursts without extending the authentication token lifetime.

The cache is off by default and requires USE_REDIS=true with the AUTH_USER_DOC namespace backed by Redis. LibreChat disables the mode and logs a warning when those requirements are not met. Cached documents are sanitized before storage and invalidated when the user is updated.

USE_REDIS=true
AUTH_USER_CACHE_MODE=on

Troubleshooting OpenID Connect

If you encounter issues with OpenID Connect authentication:

1. Enable Header Debug Logging: Set DEBUG_OPENID_REQUESTS=true in your environment variables to log request headers in addition to URLs (with sensitive data masked). Note: Request URLs are always logged at debug level
2. Check Redirect URIs: Ensure your callback URL matches exactly between your provider and LibreChat configuration
3. Verify Scopes: Make sure all required scopes are properly configured
4. Review Provider Logs: Check your identity provider's logs for authentication errors
5. Validate Tokens: Ensure your provider is issuing valid tokens with the expected claims
6. Ensure nonce is generated: Some identity providers generate nonce url parameter if it's missing in the request. Set OPENID_GENERATE_NONCE=true to force the openid-client to generate it.

Discovery Retries

If your identity provider is unreachable when LibreChat starts, OpenID discovery can be retried. OPENID_DISCOVERY_RETRY_ATTEMPTS sets the number of attempts made before startup continues (0 to 100, default 1; 0 retries only in the background), and OPENID_DISCOVERY_RETRY_DELAY_MS sets the delay between attempts (default 5000). Values set under registration.openidDiscovery in librechat.yaml take precedence. See registration for those keys and for oauthStateTtlMs, which controls how long a started social login may take to reach its callback (default 10 minutes).

Profile Avatar Origins

When fetching the user's profile avatar, LibreChat sends the access token only to the provider's issuer and userinfo origins. If the avatar is served from another origin that requires the token, add it to OPENID_AVATAR_AUTHORIZED_ORIGINS as a comma- or space-separated list of URLs.

OPENID_AVATAR_AUTHORIZED_ORIGINS=https://graph.example.com,https://photos.example.com

Admin Panel Redirects

If the Admin Panel is hosted on a separate URL from LibreChat, set ADMIN_PANEL_URL in the LibreChat API environment. This tells LibreChat where to send admins after the admin OAuth or SSO callback completes.