Docs
⚙️ Configuration
Authentication
OAuth2-OIDC
OpenID Connect Token Reuse

OpenID Connect Token Reuse

LibreChat supports reusing access and refresh tokens issued by your OpenID Connect provider (like Azure Entra ID) 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)
  • Basic OpenID Connect setup completed

Configuration Steps

  1. Set OPENID_REUSE_TOKENS=true in your environment variables.

  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

image

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

image

  1. 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”)

image

image

image

  1. Set the required scope in your environment:

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

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

  2. Grant admin consent:

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

image

  1. Accept the requested permissions in the popup

image

  1. Clear LibreChat cache and restart the service.

Environment Variables

.env
# OpenID Token Reuse Configuration
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=api://librechat/.default openid profile email offline_access
OPENID_JWKS_URL_CACHE_ENABLED=true
OPENID_JWKS_URL_CACHE_TIME=600000  # 10 minutes in milliseconds
OPENID_ON_BEHALF_FLOW_FOR_USERINFRO_REQUIRED=true
OPENID_ON_BEHALF_FLOW_USERINFRO_SCOPE=user.read
OPENID_USE_END_SESSION_ENDPOINT=true

Additional Configuration Options

  • 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_USERINFRO_REQUIRED: Enables on-behalf-of flow for user info
  • OPENID_ON_BEHALF_FLOW_USERINFRO_SCOPE: Scope for user info in on-behalf-of flow
  • 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
AuthentikEmail setup