OpenID Connect Token Reuse

LibreChat supports reusing access and refresh tokens issued by your OpenID Connect provider (like Azure Entra ID or Auth0) to manage user authentication state. When this feature is active, the refresh token passed to the user as a cookie is issued by your OpenID provider instead of LibreChat, allowing LibreChat servers to refresh it and request access tokens from your provider.

Prerequisites

• A configured OpenID Connect provider (like Azure Entra ID, Auth0, etc.)
• Basic OpenID Connect setup completed

Configuration Steps

1. Set OPENID_REUSE_TOKENS=true in your environment variables.

Provider-Specific Configuration

Auth0 Configuration

For Auth0, you need to:

1. Create an API in Auth0 (required for JWT access tokens):

   • Go to Auth0 Dashboard → Applications → APIs
   • Click "Create API"
   • Set an Identifier (e.g., https://api.librechat.com)
   • Enable "Allow Offline Access" in the API settings

2. Set the required environment variables:

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

For detailed Auth0 configuration, see: Auth0 OpenID Connect Configuration

Azure Entra ID Configuration

2. Configure your OpenID provider (using Azure Entra ID as an example):
   • Go to the Azure Portal and navigate to your app registration
   • Click on "Expose API" in the left menu
   • Click "Add" next to "Application ID URI"
   • Enter your API URI (e.g., "api://librechat") and save

3. Create an API scope:
   • In the "Expose API" section, click "Add a scope"
   • Configure the scope with appropriate permissions
   • Save the scope configuration

4. Configure API permissions:
   • Go to "API permissions" in the left menu
   • Click "Add a permission"
   • Under "APIs my organization uses", search for your app
   • Select "Delegated permissions" and choose the appropriate scope (e.g., "access_user")

5. Set the required scope in your environment:

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

   Note: The offline_access scope is required to obtain a refresh token for reuse.

6. Grant admin consent:

   • Go to Enterprise Applications in Azure Portal
   • Find your LibreChat application
   • Navigate to Security > Permissions
   • Click "Grant admin consent"

7. Accept the requested permissions in the popup

8. Clear LibreChat cache and restart the service.

Environment Variables

# OpenID Token Reuse Configuration
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=api://librechat/.default openid profile email offline_access
 
# 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

Additional Configuration Options

• OPENID_AUDIENCE: The audience parameter for authorization requests. Required for Auth0 to receive JWT access tokens instead of opaque tokens
• OPENID_JWKS_URL_CACHE_ENABLED: Enables caching of signing key verification results to prevent excessive HTTP requests to the JWKS endpoint
• OPENID_JWKS_URL_CACHE_TIME: Cache duration in milliseconds (default: 600000 ms / 10 minutes)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: Enables on-behalf-of flow for user info (Azure-specific)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: Scope for user info in on-behalf-of flow (Azure-specific)
• OPENID_USE_END_SESSION_ENDPOINT: Enables use of the end session endpoint for logout

Security Considerations

• Ensure proper token storage and handling
• Implement appropriate token refresh mechanisms
• Monitor token usage and implement rate limiting if necessary
• Regularly rotate client secrets
• Use secure cookie settings for token storage

Troubleshooting

If you encounter issues with token reuse:

1. Verify all required scopes are properly configured
2. Check that admin consent has been granted
3. Ensure the API permissions are correctly set up
4. Verify the token cache is working as expected
5. Check the application logs for any authentication errors
6. Enable detailed OpenID request header logging by setting DEBUG_OPENID_REQUESTS=true in your environment variables to see request headers in addition to URLs (with sensitive data masked)