✨ docs: Add OpenID Connect token reuse feature documentation (#308)

- Introduced a new section on reusing access and refresh tokens from OpenID Connect providers, specifically for Azure Entra ID. - Added detailed configuration steps and environment variables for enabling token reuse. - Created a dedicated page for "Re-use OpenID Tokens for Login Session" with prerequisites and troubleshooting tips. - Updated existing documentation to reference the new token reuse feature.
2026-03-27 10:48:32 +07:00 · 2025-05-23 17:16:29 -04:00
parent b6a5b6869d
commit c7cbb93bfe
4 changed files with 132 additions and 2 deletions
--- a/pages/docs/configuration/authentication/OAuth2-OIDC/azure.mdx
+++ b/pages/docs/configuration/authentication/OAuth2-OIDC/azure.mdx
@@ -63,3 +63,9 @@ OPENID_USE_END_SESSION_ENDPOINT=true

 > Note: If using docker, run `docker compose up -d` to apply the .env configuration changes

+## Advanced: Token Reuse
+
+LibreChat supports reusing Azure Entra ID tokens for session management, which can provide better integration with your Azure environment. This feature allows LibreChat to use Azure's refresh tokens instead of managing its own session tokens.
+
+To learn more about this feature and how to configure it, see [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse).
+
--- a/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx
+++ b/pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx
@@ -26,4 +26,5 @@ This section will cover how to configure OAuth2 and OpenID Connect with LibreCha
 ## OpenID Connect
  - [AWS Cognito](/docs/configuration/authentication/OAuth2-OIDC/aws)
  - [Azure Entra/AD](/docs/configuration/authentication/OAuth2-OIDC/azure)
-  - [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak)
+  - [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak)
+  - [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse)
--- a/pages/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx
+++ b/pages/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx
@@ -0,0 +1,103 @@
+---
+title: OpenID Connect Token Reuse
+description: How to configure OpenID Connect token reuse with LibreChat
+---
+
+# 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](https://github.com/user-attachments/assets/95bcd3ef-ed54-4002-9c74-a98d15673e71)
+
+3. Create an API scope:
+   - In the "Expose API" section, click "Add a scope"
+   - Configure the scope with appropriate permissions
+   - Save the scope configuration
+
+![image](https://github.com/user-attachments/assets/6f7a7170-92cd-4816-a1a8-dcacb592c893)
+
+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")
+
+![image](https://github.com/user-attachments/assets/d0b23d65-ae39-4eb8-9f4d-97f18c627045)
+
+![image](https://github.com/user-attachments/assets/67d09375-5b80-45e2-89e6-3bd0a00288e4)
+
+![image](https://github.com/user-attachments/assets/1f85ae5e-4be2-4a68-b663-4152f32fa108)
+
+5. Set the required scope in your environment:
+   ```bash filename=".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.
+
+6. Grant admin consent:
+   - Go to Enterprise Applications in Azure Portal
+   - Find your LibreChat application
+   - Navigate to Security > Permissions
+   - Click "Grant admin consent"
+
+![image](https://github.com/user-attachments/assets/d3a8b1f3-0f0a-4a90-92d9-9df91e665c8d)
+
+7. Accept the requested permissions in the popup
+
+![image](https://github.com/user-attachments/assets/cc3eb15a-994e-49fb-b212-f94260d787d3)
+
+8. Clear LibreChat cache and restart the service.
+
+## Environment Variables
+
+```bash filename=".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 
--- a/pages/docs/configuration/dotenv.mdx
+++ b/pages/docs/configuration/dotenv.mdx
@@ -995,6 +995,26 @@ For more information:
  ]}
 />

+##### 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.
+
+<OptionTable
+  options={[
+    ['OPENID_REUSE_TOKENS', 'boolean', 'Enable reuse of OpenID provider tokens for session management.', 'OPENID_REUSE_TOKENS=false'],
+    ['OPENID_SCOPE', 'string', 'Space-separated list of OpenID scopes. Must include offline_access for token reuse.', 'OPENID_SCOPE=api://librechat/.default openid profile email offline_access'],
+    ['OPENID_JWKS_URL_CACHE_ENABLED', 'boolean', 'Enable caching of signing key verification results.', 'OPENID_JWKS_URL_CACHE_ENABLED=true'],
+    ['OPENID_JWKS_URL_CACHE_TIME', 'number', 'Cache duration in milliseconds (default: 600000 ms / 10 minutes).', 'OPENID_JWKS_URL_CACHE_TIME=600000'],
+    ['OPENID_ON_BEHALF_FLOW_FOR_USERINFRO_REQUIRED', 'boolean', 'Enable on-behalf-of flow for user info.', 'OPENID_ON_BEHALF_FLOW_FOR_USERINFRO_REQUIRED=true'],
+    ['OPENID_ON_BEHALF_FLOW_USERINFRO_SCOPE', 'string', 'Scope for user info in on-behalf-of flow.', 'OPENID_ON_BEHALF_FLOW_USERINFRO_SCOPE=user.read'],
+    ['OPENID_USE_END_SESSION_ENDPOINT', 'boolean', 'Enable use of the end session endpoint for logout.', 'OPENID_USE_END_SESSION_ENDPOINT=true'],
+  ]}
+/>
+
+<Callout type="note" title="Note">
+For detailed configuration steps and prerequisites, see [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse).
+</Callout>
+
 #### [LDAP/AD Authentication](/docs/configuration/authentication/ldap)

 For more information: **[LDAP/AD Authentication](/docs/configuration/authentication/ldap)**
@@ -1170,4 +1190,4 @@ If you are using Redis, you will need to set the following variables:
    ['REDIS_KEY_PREFIX', 'string', 'Prefix for Redis keys', '# REDIS_KEY_PREFIX="librechat-staging:"'],
    ['REDIS_MAX_LISTENERS', 'number', 'Maximum number of event listeners allowed for the Redis client instance', '# REDIS_MAX_LISTENERS=20'],
  ]}
-/>
+/>